The PAYONE Frontend hosted-iFrame is configured in the same way as the existing Frontend solution. You can configure the Frontend design via PMI, payment portals, extended configuration. You will now find two tabs named "Classic Frontend (secure.pay1.de)" and "Frontend PCI DSS SAQ A (frontend.pay1.de)". For both frontend configuration the HTML header and footer can be specified and the design of the frontend can be customized. PAYONE already copied your existing frontend configuration into the configuration for PAYONE Frontend hosted-iFrame. However, the display of the PAYONE Frontend hosted-iFrame may differ from the existing Frontend as the size of an input field and an input iframe may differ. So please verify that the design of the PAYONE Frontend hosted-iFrame meets your expectations. After setup the new PAYONE Frontend hosted-iFrame you will simply have to replace the URL in your shop:
old URL to Frontend: https://secure.pay1.de/frontend/
-> HTML footer/header in PMI-Tab "Classic Frontend (secure.pay1.de)"
new URL to PAYONE Frontend hosted-iFrame: https://frontend.pay1.de/frontend/v2/
-> HTML footer/header in PMI-Tab "Frontend PCI DSS SAQ A (frontend.pay1.de)"
Important notes:
The HTML footer and header for "PAYONE Frontend" and "PAYONE Frontend hosted-iFrame" can be and have to be configured separately.
It is recommended to disable the usage of the Frontend classic once the PAYONE Frontend hosted-iFrame has been setup and tested. Otherwise it may be possible that an offender may change the new URL after calling the PAYONE Frontend hosted-iFrame to the old URL.
Feature "auto-submit" must not be used with PAYONE Frontend hosted-iFrame and credit card data.
You may customize the HTML-type and HTML-CSS for the PAYONE hosted-iFrames. Therefore you may put a script-block named "config" into your HTML Header Code within the PMI-Portal configuration in tab "Frontend PCI DSS SAQ A (frontend.pay1.de)".
This block may look like this (example):
|
Please pay attention to separate the elements by "," – but not the last element of a list.
Please find a list of supported elements in the next chapter.
These attributes and values are allowed in object "config.fields":
card-type | card-pan | card-cvc2 | card-expire-month | card-expire-year | attribute | value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
x |
|
|
|
|
cardtypes |
define possible cardtypes for selection in PAYONE iFrame, e.g. ["V", "M", "A"] |
||||||||||
|
x | x | x | x | size | size of input field in characters, e.g. "20" | ||||||||||
|
x | x | x | x | maxlength | maximum length of accepted input, e.g. "20" | ||||||||||
|
|
x |
|
|
length | Array of exact length of accepted input per CC-type e.g.: length: { "A": 4, "V": 3, "M": 3, "J": 0 } |
||||||||||
|
x | x | x | x | type | define type of input field:
|
||||||||||
x | x | x | x | x | style |
CSS style properties, e.g. "font-size: 1em; border: 1px solid #000; background: white; color: red; width: 145px; height: 70px; font-family: 'Courier'; font-style: italic; font-weight: bold; text-align: center; letter-spacing: 2px;" Remark: if "url" is used the style will be ignored as PCI DSS does not allow external ressources. |
||||||||||
x | x | x | x | x | iframe.height | size | ||||||||||
x | x | x | x | x | iframe.width | size, e.g.: iframe: { height: "25px", width: "250px" } |
These attributes and values are allowed in object "config.defaultStyle":
attribute | value |
---|---|
input |
CSS style properties for input fields, e.g. "font-size: 1em; border: 1px solid #000; width: 175px;" |
select |
CSS style properties for select fields, e.g. "font-size: 1em; border: 1px solid #000;" |
iframe.height |
size in pixel |
iframe.width |
size in pixel, e.g.: |
Request URL to PAYONE Frontend hosted-iFrame: https://frontend.pay1.de/frontend/v2/
The Endpoint to Frontend Classic: https://secure.pay1.de/frontend/ should not be used for new implementations; existing implementations should be migrated
You can create a Frontend-Page by sending a POST Request to our Frontend Endpoint with your desired parameters:
|
Alternatively, you can also pass the values via URL (as GET request). The example above would look like this:
|
The calculation of the hash value can be found here: FE - Calculation of the HASH value.
In the „Access" version all offers (accesses or subscriptions) you want to bill have first to be created (see 2.1.2). The payment window is opened using this offer ID.
Account | Here you select the account (sub-account) for which the bookings are to be listed in the statistics. |
---|---|
Offer | Select the desired offer |
|
Alternatively, you can also pass the values via URL (via GET request). The calculation of the hash value can be found here: Calculation of the HASH value.
PAYONE Platform Frontend supports the automatic triggering of a payment without the customer having to re-confirm the payment on the Frontend. This can be useful in payment methods where you already have obtained all relevant customer data (e.g. prepayment, invoice). This function also allows you to ask for the payment data already on your site and then simply transfer them to the Frontend. In this case the Frontend executes the payment automatically. If the payment was successful the customer is forwarded directly. In case of an error the customer is shown the Frontend and given the option to correct his data.
Note:
Payment data should not come into contact with your system. This is very important with credit card data. Certification according to the PCI standard is not necessary only if the card data does not come into contact with your systems. To prevent your systems from coming into contact with sensitive payment data, the payment data from your form should be sent directly to the Frontend and not be forwarded through your systems (see below). Any other data can be queried in preceding steps.
|
The PAYONE Platform supports the automatic storage of your customers' master and payment data. The PAYONE Platform Frontend can use these data to accelerate the payment process for the customer. If the customer is already known to the PAYONE Platform, it is possible for these data not having to be requested again during the payment process via the Frontend. The data are only displayed to the customer for checking. If the customer does not wish to change the data, he can complete the payment process with a single click.
To use the One-Click Checkout function you have to have it activated by the PAYONE Merchant Service. It is also technically necessary to transmit the customer ID („customerid") of your customer with every request. This is necessary for the unique identification of the customer. In addition, you must use the hash method in this documentation (2.x). The hash method from the documentation of version 1.x is not permitted.
Note:
The PAYONE Platform supports the automatic storage of your customers' master and payment data. The PAYONE Platform Frontend can use these data to accelerate the payment process for the customer. If the customer is already known to the PAYONE Platform, it is possible for these data not having to be requested again during the payment process via the Frontend. The data are only displayed to the customer for checking. If the customer does not wish to change the data, he can complete the payment process with a single click.
This method requires a certain level of security on behalf of the merchant. It must be ensured that the user is indeed the correct customer. This must be ensured using correspondingly secure login mechanisms. Otherwise it might be possible that a customer misuses the payment data of a third party.
To prevent changes to the request to PAYONE, we need to incorporate a checksum of the used parameters to the PAYONE platform. For this, we use the parameter hash.
The hash value is calculated from the request parameters and a secret key using the hash function hash("md5" , $data) or hash("sha384", $data). Any parameter values to be protected are concatenated in alphabetical order. Finally, the key will be attached to the string and the hash value is calculated.
Parameters are sorted alphabetically by their name. It does not matter in which order they are used in the request URL. The parameters to be protected can be found in FE - Parameters in the request URL. They have been identified with a "usedinhash" in the hash column.
|
You can adjust the look and feel of the Frontend using templates. The template consists of an HTML header and an HTML footer. In the HTML header you must define a stylesheet (CSS) amongst other things. Ideally use the "Default CSS" and adapt it as desired.
|
Request URL to PAYONE Frontend hosted-iFrame: https://frontend.pay1.de/frontend/v2/
The Endpoint to Frontend Classic: https://secure.pay1.de/frontend/ should not be used for new implementations; existing implementations should be migrated.
The UsedInHash-column defines whether the parameter value has to be included in your hash.
The parameters with "usedinhash" must be included in the calculation of the hash value to prevent changes by the customer.
request
required
usedinhash
|
Format LIST
|
|||||||||||||||
mid
required
usedinhash
|
Format NUMERIC(5..6)
Merchant ID, defined by PAYONE |
|||||||||||||||
aid
required
usedinhash
|
Format NUMERIC(5..6)
Sub-Account ID, defined by PAYONE |
|||||||||||||||
portalId
required
usedinhash
|
Format LIST
Portal ID, defined by PAYONE |
|||||||||||||||
api_version required
usedinhash
|
Format LIST
New parameter api_version should be added to current implementations as it will be mandatory in future. |
|||||||||||||||
mode required
usedinhash
|
Format LIST
Mode for transactions, either ‘live’ or ‘test’ |
|||||||||||||||
encoding optional
usedinhash
|
Format LIST
The type of character encoding used in the request. |
|||||||||||||||
key
required
usedinhash
|
your key value, alpha-numeric
|
clearingtype
required
usedinhash
|
Format LIST
|
||||||||||||||||||||
reference required
usedinhash
|
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]
Merchant reference number for the payment process (case insensitive) |
||||||||||||||||||||
customerid optional
usedinhash
|
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]
Merchant's customer ID, defined by you / merchant to refer to the customer record. "customerid" can be used to identify a customer record. If "customerid" is used then stored customer data are loaded automatically. |
||||||||||||||||||||
invoiceid optional
usedinhash
|
Format CHAR(1..20)
Merchant's invoice number |
||||||||||||||||||||
invoice_deliverydate optional
usedinhash
|
Format DATE(8), YYYYMMDD
Delivery date (YYYYMMDD) |
||||||||||||||||||||
invoice_deliveryenddate optional
usedinhash
|
Format DATE(8), YYYYMMDD
Delivery end date (YYYYMMDD) |
||||||||||||||||||||
invoiceappendix optional
usedinhash
|
Format CHAR(1..255)
Dynamic text on the invoice |
||||||||||||||||||||
param optional
usedinhash
|
Format CHAR(1..255)
Individual parameter (per payment process) |
||||||||||||||||||||
narrative_text
optional
usedinhash
|
Format CHAR(1..81)
Dynamic text element on account statements |
||||||||||||||||||||
display_name optional
usedinhash
|
Format LIST
Specifies whether the customer name / company should be queried - instead of providing them in the Frontend request URL. |
||||||||||||||||||||
display_address optional
usedinhash
|
Format LIST
Specifies whether the customer address should be queried - instead of providing them in the Frontend request URL. |
||||||||||||||||||||
display_change_order optional
|
Format LIST
Specifies whether payment details or payment information should be displayed first. |
||||||||||||||||||||
autosubmit optional
usedinhash
|
Format LIST
Specifies whether payment details should be queried with customer interaction or with payment details provided in Frontend request URL. |
||||||||||||||||||||
successurl
required
usedinhash
|
Format CHAR(2..255)
Scheme <scheme>://<host>/<path> <scheme>://<host>/<path>?<query> scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}
URL for "payment successful" |
||||||||||||||||||||
backurl required
usedinhash
|
Format CHAR(2..255)
Scheme <scheme>://<host>/<path> <scheme>://<host>/<path>?<query> scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}
URL for "Back" or "Cancel" |
||||||||||||||||||||
targetwindow optional
usedinhash
|
Format LIST
Specifies target window for Frontend form. |
||||||||||||||||||||
hash required
|
Format CHAR(1..96) lowercase
Permitted Symbols [0-9,a-z]
The hash code is used to prevent that a customer changes any relevant value (like payment type, your MID or the amount). SHA2-384 hash code. |
amount
required
usedinhash
|
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99 Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro. The amount must be less than or equal to the amount of the corresponding booking. |
||||||
currency
required
usedinhash
|
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR USD GBP Specifies currency for this transaction |
||||||
it[n] required
usedinhash
|
Format LIST
Array elements [n] starting with [1]; serially numbered; max [400]
Parameter it[n] specifies the item type of a shopping cart item. |
||||||
id[n] required
usedinhash
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]
Product number, SKU, etc. of this item |
||||||
pr[n] required
usedinhash
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent |
||||||
no[n] required
usedinhash
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item |
||||||
de[n] required
usedinhash
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
de[1]=Product 1 de[2]=Product 2 de[3]=Product 3 ... de[400]=Product 400 Description of this item. Will be printed on documents to customer. |
||||||
va[n] optional
usedinhash
|
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [400]
VAT rate (% or bp) |
productid required
usedinhash
|
Format CHAR(1..7)
ID for the offer |
||||||||||
accessname optional
usedinhash
|
Format CHAR(1..32)
Customer's user name |
||||||||||
accesscode optional
usedinhash
|
Format CHAR(1..32)
Customer's password |
||||||||||
frontend_description optional
usedinhash
|
Format CHAR(1..10000)
Confirmation text for the end customer after creating access. The transfer of HTML elements is permitted. At 10,000 characters this parameter is truncated. |
||||||||||
amount_trail optional
usedinhash
|
Format NUMERIC(1..8), max. value 999 999 99
Total gross amount for initial term Must equal the sum (quantity x price) of all items for the initial term. Required when item is submitted. Amount can be "0" (e.g. for test period). |
||||||||||
amount_recurring optional
usedinhash
|
Format NUMERIC(1..8), max. value 999 999 99
Total gross amount of all items of one period during the subsequent term Must equal the sum (quantity x price) of all items during the subsequent term. Required when item is submitted. Amount must not be "0". |
||||||||||
period_unit_trail optional
usedinhash
|
Format LIST
Time unit for initial term Do not use with “access_expiretime”. Do not exceed 5 years / 60 months. |
||||||||||
period_length_trail optional
usedinhash
|
Format NUMERIC(1..4)
Duration of the initial term. Can only be used in combination with period_unit_trail. Required when period_unit_trail is submitted. Do not use with “access_expiretime” |
||||||||||
period_unit_recurring optional
usedinhash
|
Format LIST
Time unit for subsequent term Do not exceed 5 years / 60 months. |
||||||||||
period_length_recurring optional
usedinhash
|
Format NUMERIC(1..4)
Duration of the subsequent term. Can only be used in combination with period_unit_recurring. Required when period_length_recurring is submitted. |
||||||||||
id_trail[n] required
usedinhash
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]
Product number, order number, etc. of this item (initial term) |
||||||||||
no_trail[n] required
usedinhash
|
Format NUMERIC(8) max. 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]
Quantity of this item (initial term) |
||||||||||
pr_trail[n] required
usedinhash
|
Format NUMERIC(8) max. 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item (initial term) in smallest unit. |
||||||||||
de_trail[n] required
usedinhash
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
de[1]=Product 1 de[2]=Product 2 de[3]=Product 3 ... de[100]=Product 100 Description of this item (initial term) |
||||||||||
ti_trail[n] required
usedinhash
|
Format CHAR(1..100)
Array elements [n] starting with [1]; serially numbered; max [400]
Title (initial term) |
||||||||||
va_trail[n] required
usedinhash
|
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [400]
VAT rate (% or bp) (first term) |
||||||||||
id_recurring[n] optional
usedinhash
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]
Product number, order number, etc. of this item (subsequent term) |
||||||||||
no_recurring[n] optional
usedinhash
|
Format NUMERIC(5)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item (subsequent term) |
||||||||||
pr_recurring[n] optional
usedinhash
|
Format NUMERIC(8) max. 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item (subsequent term) in smallest unit. |
||||||||||
de_recurring[n] optional
usedinhash
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]
de[1]=Product 1 de[2]=Product 2 de[3]=Product 3 ... de[100]=Product 100 Description of this item (subsequent term) |
||||||||||
ti_recurring[n] optional
usedinhash
|
Format CHAR(1..100)
Array elements [n] starting with [1]; serially numbered; max [400]
Title (subsequent term) |
||||||||||
va_recurring[n] optional
usedinhash
|
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [400]
VAT rate (% or bp) (subsequent term) |
businessrelation optional
|
Format LIST
Value specifies business relation between merchant and customer |
||||||
firstname optional
|
Format CHAR(1..50)
First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname" |
||||||
lastname optional
|
Format CHAR(2..50)
Lastname of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname" |
||||||
company optional
|
Format CHAR(2..50)
Campany name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname" |
||||||
street optional
|
Format CHAR(1..50)
Street number and name (required: at least one character) |
||||||
addressaddition optional
|
Format CHAR(1..50)
Samples
7th floor c/o Maier Specifies an additional address line for the invoice address of the customer. |
||||||
zip optional
|
Format CHAR(2..50)
Permitted Symbols[0-9][A-Z][a-z][_.-/ ]
Postcode |
||||||
city optional
|
Format CHAR(2..50)
City of customer. |
||||||
country optional
|
Format LIST
Permitted values ISO 3166 2-letter-codes
Specifies country of address for the customer |
||||||
telephonenumber optional
|
Format CHAR(1..30)
Phone number of customer |
||||||
birthday optional
|
Format DATE(8), YYYYMMDD
Samples
20190101 19991231 Date of birth of customer |
||||||
language optional
|
Format LIST
Permitted values ISO 639-1 (Language)2-letter-codes
Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display). If the language is not transferred, the browser language will be used. For a non-supported language English will be used. |
||||||
gender optional
|
Format LIST
Permitted values f, m, d
Gender of customer (female / male / diverse* ) |
||||||
email optional
|
Format CHAR(5..254)
Permitted Symbols RFC 5322
Special Remark email validation: Max. length for email is 254 characters. Validation is set up in the following way: Username = Max. 63 characters
|
||||||
personalid optional
|
Format CHAR(1..32)
Permitted Symbols [0-9][A-Z][a-z][+-./()]
Person specific numbers or characters, e.g. number of passport / ID card |
shipping_firstname optional
|
Format CHAR(1..50)
First name of delivery address |
shipping_lastname optional
|
Format CHAR(1..50)
Surname of delivery address |
shipping_company optional
|
Format CHAR(2..50)
Company Name of the delivery address |
shipping_street optional
|
Format CHAR(2..50)
Street number and name of delivery address |
shipping_zip optional
|
Format CHAR(2..10)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]
Postcode of delivery address |
shipping_city optional
|
Format CHAR(2..50)
City of delivery address |
shipping_country optional
|
Format LIST
Permitted values ISO 3166 2-letter-codes
Specifies country of delivery address for the customer |
cardholder optional
|
Format CHAR(1..50)
Cardholder of credit card. |
cardpan required
|
Format NUMERIC(13..19)
Primary account number of credit card If your system handles "cardpan" directly you can not be PCI DSS SAQ A compliant.
For simple PCI DSS SAQ A compliance please use PAYONE hosted iFrames together with pseudocardpan.
|
cardtype required
|
Format LIST
Card type of credit card |
cardexpireyear required
|
Format NUMERIC(4), YYYY
Credit card expiry year YYYY |
cardexpiremonth required
|
Format NUMERIC(2), MM
Credit card expiry month MM |
cardcvc2 optional
|
Format NUMERIC(3..4)
Credit card security number For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used.
|
iban optional
|
Format CHAR(10..34)
Permitted Symbols [0-9][A-Z]
IBAN to be used for payment or to be checked |
bic optional
|
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]
Bank Identifier Code to be used for payment or to be checked |
bankaccountholder optional
|
Format CHAR(1..50)
Account holder |
bankcountry optional
|
Format LIST
Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE DE: Mandatory with bankcode, bankaccount, optional with IBAN For other countries than DE please use IBAN or IBAN/BIC |
bankaccount optional
|
Format NUMERIC(1..10)
Account number (BBAN) DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions. Not DE: Please use IBAN or IBAN / BIC. |
bankcode optional
|
Format NUMERIC(8)
Sort code (BBAN) (only in DE) DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions. Not DE: Please use IBAN or IBAN / BIC. |
mandate_identification optional
|
Format CHAR(1..35)
Permitted Symbols [A-Z,a-z,0-9,+,-,.,(,)]
A SEPA mandate can be created if a payment is initiated (amount > 0). Can be used to enforce a merchant specific mandate identification. The mandate_identification has to be unique. If the mandate_identification is not set PAYONE will create an unique mandate identification (pattern: PO-nnnnnnnnnn). PPS (PAYONE Payment Service): This parameter must not be used! For PPS the PAYONE platform defines the mandate_identification |
onlinebanktransfertype optional
|
Format LIST
|
||||||||||||||
bankcountry required
|
Format LIST
Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE DE: Mandatory with bankcode, bankaccount, optional with IBAN For other countries than DE please use IBAN or IBAN/BIC |
||||||||||||||
iban optional
|
Format CHAR(10..34)
Permitted Symbols [0-9][A-Z]
IBAN to be used for payment or to be checked |
||||||||||||||
bic optional
|
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]
Bank Identifier Code to be used for payment or to be checked BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. |
||||||||||||||
bankaccount optional
|
Format NUMERIC(1..10)
Account number (BBAN) DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions. Not DE: Please use IBAN or IBAN / BIC. |
||||||||||||||
bankcode optional
|
Format NUMERIC(8)
Sort code (BBAN) (only in DE) DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions. Not DE: Please use IBAN or IBAN / BIC. |
||||||||||||||
bankgrouptype optional
|
Format LIST
Issuer of Online-Bank-Transfer used for iDEAL and EPS |
wallettype required
|
Format LIST
Used with "clearingtype=wlt" to identify wallet payment types |
financingtype required
|
Format LIST
Used with "clearingtype=fnc" to identify Financing type |
Host: Content-Type: application/x-www-form-urlencoded