Frontend API Endpoints

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

Request Parameters

Important notes for hash calculation

The UsedInHash-column defines whether the parameter value has to be included in your hash.
The parameters with a "+" must be included in the calculation of the hash value to prevent changes by the customer.

Request to Frontend

Common Parameter

Required

UsedInHash

aid

+

Sub-Account ID, defined by PAYONE

Format

NUMERIC(5..6)

portalid

+

Portal ID, defined by PAYONE

Format

NUMERIC(7)

api_version

+

New parameter api_version should be added to current implementations as it will be mandatory in future.

Format

LIST

api_version	Comment	Description
3.8	Current API-version (Default if not present)
3.9	New API-version from 2015-01-05	New response “pending” added for “preauthorization” / “authorization”
3.10	New API-version from 2016-06-01	Response for “customermessage” can be more specific in case of error by containing detailed error messages from external payment gateways (e.g. Ratepay, …)
3.11	New API-version from 2018-02-01	Request “capture” with response “pending” Announcement for upcoming request “refund” / response “pending” Announcement for upcoming request “createaccess” / response “pending”

mode

+

Mode for transactions, either ‘live’ or ‘test’

Format

LIST

value	Comment
live	Transaction should be performed in live mode.
test	Transaction should be simulated

request

+

The type of request you would like to perform

Format

LIST

Link to Request-Overview: Request Overview

encoding

-

+

The type of character encoding used in the request.

Format

LIST

value	Comment
ISO-8859-1	Default if not specified
UTF-8

clearingtype

+

Format

LIST

value	Comment	Description / Comments
elv	Debit payment	According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19. Please use request “updateuser” to update customers address data. This means that the whole address for bank transfers needs to be provided.
cc	Credit card
rec	Invoice
cod	Cash on delivery	not allowed for vauthorization, createaccess, updateaccess
vor	Prepayment	not allowed for vauthorization, createaccess, updateaccess
sb	Online Bank Transfer	not allowed for vauthorization, createaccess, updateaccess
wlt	e-wallet	not allowed for vauthorization, createaccess, updateaccess
fnc	Financing	not allowed for vauthorization, createaccess, updateaccess
csh	Cash or Hybrid Payments	not allowed for vauthorization, createaccess, updateaccess

reference

+

Merchant reference number for the payment process (case insensitive)

Format

CHAR(1..20)

Permitted Symbols

[0-9][a-z][A-Z], .,-,_,/

customerid

-

+

Merchant's customer ID, defined by you / merchant to refer to the customer record

Format

CHAR(1..20)

Permitted Symbols

[0-9, a-z, A-Z, .,-,_,/]

"customerid" can be used to identify a customer record.
If "customerid" is used then stored customer data are loaded automatically.

invoiceid

-

+

Merchant's invoice number

Format

CHAR(1..20)

invoice_deliverydate

-

+

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoice_deliveryenddate

-

+

Delivery end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoiceappendix

-

+

Dynamic text on the invoice

Format

CHAR(1..255)

param

-

+

Individual parameter (per payment process)

Format

CHAR(1..255)

narrative_text

-

+

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

display_name

-

+

Specifies whether the customer name / company should be queried - instead of providing them in the Frontend request URL.

Format

LIST

value	Comment
yes	Name will be queried (default)
no	name/company will not be queried if all necessary data were already transferred and are correct

display_address

-

+

Specifies whether the customer address should be queried - instead of providing them in the Frontend request URL.

Format

LIST

Value	Comment
yes	Address will be queried (default)
no	Address will not be queried if all necessary data were already transferred and are correct

display_change_order

-

Specifies whether payment details or payment information should be displayed first.

Format

LIST

Value	Comment
no	Unchanged order (default)
yes	Changed order: Payment details are listed after the payment information.

autosubmit

-

+

Specifies whether payment details should be queried with customer interaction or with payment details provided in Frontend request URL.

Format

LIST

Value

Comment

no

no: No auto-submit (default)

yes

Payment is executed immediately without customer interaction. If the payment was successful the customer is forwarded directly to the „successurl“.

All payment data must be transmitted in this version.

successurl

o

+

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>

<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

backurl

o

+

URL for "Back" or "Cancel"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>

<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

targetwindow

-

+

Specifies target window for Frontend form.

Format

LIST

Value	Comment
window	default
opener
top
parent
blank
self

hash

+

The hash code is used to prevent that a customer changes any relevant value (like payment type, your MID or the amount).

MD5 hash code SHA2-384 hash code. Details: FE - Calculation of the HASH value

Format

CHAR(1..96) lowercase

Permitted Symbols

[0-9,a-z]

Parameter ( „pre-/authorization“ )

amount

+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

currency

+

Specifies currency for this transaction

Format

LIST

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR

USD

GBP

it[n]

+

Parameter it[n] specifies the item type of a shopping cart item.

Format

LIST

Array

Array elements [n] starting with [1]; serially numbered; max [400]

it[n]	Comments
goods	Goods
shipment	Shipping charges
handling	Handling fee	Not to be used with PDT
voucher	Voucher / discount	Not to be used with PDT

id[n]

+

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols

[0-9][A-Z][a-z][()[]{} +-_#/:]

pr[n]

+

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

no[n]

+

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

de[n]

+

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example

de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

va[n]

o

+

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Parameter („createaccess“)

productid

+

ID for the offer

Format

NUMERIC(1..7)

accessname

-

+

Customer's user name

Format

CHAR(1..32)

accesscode

-

+

Customer's password

Format

CHAR(1..32)

frontend_description

-

+

Confirmation text for the end customer after creating access. The transfer of HTML elements is permitted. At 10,000 characters this parameter is truncated.

Format

CHAR(1..10000)

amount_trail

-

+

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).

Format

NUMERIC(1..8), max. value 999 999 99

amount_recurring

-

+

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".

Format

NUMERIC(1..8), max. value 999 999 99

period_unit_trail

-

+

Time unit for initial term

Do not use with “access_expiretime”.

Do not exceed 5 years / 60 months.

Format

LIST

value	Comment
Y	Value “length” is in years
M	Value “length” is in months
D	Value “length” is in days

period_length_trail

-

+

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”

Format

NUMERIC(1..4)

period_unit_recurring

-

+

Time unit for subsequent term

Do not exceed 5 years / 60 months.

Format

LIST

value	Comment
Y	Value “length” is in years
M	Value “length” is in months
D	Value “length” is in days
N	No subsequent term given

period_length_recurring

-

+

Duration of the subsequent term. Can only be used in combination with period_unit_recurring.

Required when period_length_recurring is submitted.

Format

NUMERIC(1..4)

id_trail[n]

+

Product number, order number, etc. of this item (initial term)

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Permitted Symbols

[0-9][A-Z][a-z][()[]{} +-_#/:]

no_trail[n]

+

Quantity of this item (initial term)

Format

NUMERIC(5)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

pr_trail[n]

+

Unit gross price of the item (initial term) in smallest unit.

Format

NUMERIC(8) max. 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [100]

de_trail[n]

+

Description of this item (initial term)

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Example

de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100

ti_trail[n]

+

Title (initial term)

Format

CHAR(1..100)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

va_trail[n]

-

+

VAT rate (% or bp) (first term)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

id_recurring[n]

-

+

Product number, order number, etc. of this item (subsequent term)

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Permitted Symbols

[0-9][A-Z][a-z][()[]{} +-_#/:]

no_recurring[n]

-

+

Quantity of this item (subsequent term)

Format

NUMERIC(5)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

pr_recurring[n]

-

+

Unit gross price of the item (subsequent term) in smallest unit.

Format

NUMERIC(8) max. 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [100]

de_recurring[n]

-

+

Description of this item (subsequent term)

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Example

de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100

ti_recurring[n]

-

+

Title (subsequent term)

Format

CHAR(1..100)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

va_recurring[n]

-

+

VAT rate (% or bp) (subsequent term)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Parameter ( personal data )

businessrelation

o

+

Value specifies business relation between merchant and customer

Format

LIST

value	Comment
b2c	Indicates business to private customer
b2b	indicates business to business customer (company)

firstname

-

First name of customer; optional if company is used, i.e.: you may use

"company"
or "lastname"
or "firstname" plus "lastname"

Format

CHAR(1..50)

lastname

-

Last name of customer; optional if company is used, i.e.: you may use

"company"
or "lastname"
or "firstname" plus "lastname"

Format

CHAR(2..50)

company

-

Company name of customer; The company name is optional if lastname is used, i.e.: you may use

"company"
or "lastname"
or "firstname" plus "lastname"

Format

CHAR(2..50)

street

-

Street number and name (required: at least one character)

Format

CHAR(1..50)

addressaddition

-

Specifies an additional address line for the invoice address of the customer.

Format

CHAR(1..50)

Samples

7th floor

c/o Maier

zip

-

Postcode

Format

CHAR(2..10)

Permitted Symbols

[0-9][A-Z][a-z][_.-/ ]

city

-

City of customer

Format

CHAR(2..50)

country

-

Specifies country of address for the customer

Format

LIST

Permitted values

ISO 3166 2-letter-codes

Samples

DE

GB

US

Some countries require additional information in parameter "state"

email

-

email-address of customer

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
Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters

Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

telephonenumber

-

Phone number of customer

Format

CHAR(1..30)

birthday

-

Date of birth of customer

Format

DATE(8), YYYYMMDD

Samples

20190101

19991231

language

-

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.

Format

LIST

Permitted values

ISO 639-1 (Language) 2-letter-codes

gender

-

Gender of customer (female / male / diverse* )

Format

LIST

Permitted values

* currently not in use

personalid

-

Person specific numbers or characters, e.g. number of passport / ID card

Format

CHAR(1..32)

Permitted Symbols

[0-9][A-Z][a-z][+-./()]

Parameter ( delivery data )

shipping_firstname

-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname

-

Surname of delivery address

Format

CHAR(1..50)

shipping_company

-

Company Name of the delivery address

Format

CHAR(2..50)

shipping_street

-

Street number and name of delivery address

Format

CHAR(2..50)

shipping_zip

-

Postcode of delivery address

Format

CHAR(2..10)

Permitted Symbols

[0-9][A-Z][a-z][_.-/ ]

shipping_city

-

City of delivery address

Format

CHAR(2..50)

shipping_country

-

Specifies country of delivery address for the customer

Format

LIST

Permitted values

ISO 3166 2-letter-codes

Samples

DE

GB

US

Some countries require additional information in parameter shipping_state

Parameter („autosubmit“ - credit card)

cardholder

-

Cardholder of credit card.

Format

CHAR(1..50)

cardpan

+

-

Primary account number of credit card

Format

NUMERIC(13..19)

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

+

-

Card type of credit card

Format

LIST

value	Comment	BIN-Range for automatic card type detection
V	Visa	4
M	MasterCard	51-55,2221-2720
A	American Express	34, 37
D	Diners / Discover	300-305,3095,36,38,39 601, 64, 65
C	~~Discover~~
J	JCB	3528-3589
O	Maestro International	50, 56-58,602, 61, 620, 627, 63, 67
P	China Union Pay	62212600-62299800,624-626, 6282-6288
U	UATP / Airplus	1220, 1920 -> coming soon; not available yet
G	girocard	68 *

*girocard is currently only viable for e-commerce-payments via Apple Pay.

cardexpireyear

+

-

Credit card expiry year YYYY

Format

NUMERIC(4), YYYY

cardexpiremonth

+

-

Credit card expiry month MM

Format

NUMERIC(2), MM

cardcvc2

o

-

Credit card security number

Format

NUMERIC(3..4)

For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used.

Parameter („autosubmit“ - direct debit)

iban

o

-

IBAN to be used for payment or to be checked

Format

CHAR(10..34)

Permitted Symbols

[0-9][A-Z]

bic

o

-

Bank Identifier Code to be used for payment or to be checked

Format

CHAR(8 or 11) Only capital letters and digits, no spaces

Permitted Symbols

[0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

bankaccountholder

-

Account holder

Format

CHAR(1..50)

bankcountry

o

-

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

Format

LIST

bankaccount

o

-

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.

Format

NUMERIC(1..10)

bankcode

o

-

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.

Format

NUMERIC(8)

mandate_identification

o

+

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.

Format

CHAR(1..35)

Permitted Symbols

[A-Z,a-z,0-9,+,-,.,(,)]

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

Parameter („autosubmit“ - Online transfer)

onlinebanktransfertype

+

-

Format

LIST

Value	Comment	Server-API	Client-API	Frontend
BCT	Bancontact
EPS	eps – online transfer (AT)
GPY	giropay (DE)
IDL	iDEAL (NL)
MBC	Multibanco
MYB	MyBank
P24	Przelewy24 (PL)
PFF	PostFinance E-Finance (CH)
PFC	PostFinance Card (CH)
PNT	SOFORT Überweisung
TRL	Trustly
VKP	Verkkopankki

bankcountry

+

-

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

Format

LIST

iban

o

-

IBAN to be used for payment or to be checked

Format

CHAR(10..34)

Permitted Symbols

[0-9][A-Z]

bic

o

-

Bank Identifier Code to be used for payment or to be checked

Format

CHAR(8 or 11) Only capital letters and digits, no spaces

Permitted Symbols

[0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

bankaccount

o

-

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.

Format

NUMERIC(1..10)

bankcode

o

-

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.

Format

NUMERIC(8)

bankgrouptype

o

-

Issuer of Online-Bank-Transfer used for iDEAL and EPS

Format

LIST

Parameter („autosubmit“ - e-wallet)

wallettype

+

-

Used with "clearingtype=wlt" to identify wallet payment types

Format

LIST

Value	Comment	Server-API	Client-API	Channel Frontend
ALP	Alipay
AMZ	Amazon Payments
PDT	paydirekt
PPE	PayPal
PSC	paysafecard
APL	Apple Pay

Parameter („autosubmit“ - Financing)

financingtype

+

-

Used with "clearingtype=fnc" to identify Financing type

Format

LIST

Value	Comment	Server-API	Client-API	Frontend
RPV	Ratepay Open Invoice
RPS	Ratepay Installments
RPP	Ratepay Prepayment
RPD	Ratepay Direct Debit
PYV	Unzer Invoice
PYS	Unzer Installment
PYM	Unzer Monthly
PYD	Unzer Direct Debit
PPI	PayPal Installment
KLV	Klarna Checkout Invoice
KLS	Klarna Checkout Installment
KIS	Klarna Payments "Slice it" (Installments)
KIV	Klarna Payments "Pay now" (Invoice)
KDD	Klarna Payments "Pay now" (Direct Debit)
KBT	Klarna Payments "Pay now" (Bank Transfer)

Page tree

Frontend API Endpoints

Request Parameters

Important notes for hash calculation

Request to Frontend

Common Parameter

Parameter ( „pre-/authorization“ )

Parameter („createaccess“)

Parameter ( personal data )

Parameter ( delivery data )

Parameter („autosubmit“ - credit card)

Parameter („autosubmit“ - direct debit)

Parameter („autosubmit“ - Online transfer)

Parameter („autosubmit“ - e-wallet)

Parameter („autosubmit“ - Financing)

Social Media

PAYONE

Help

Intranet Tools

Page tree

FE - Parameters in the request URL

Frontend API Endpoints

Request Parameters

Important notes for hash calculation

Request to Frontend

Common Parameter

Parameter ( „pre-/authorization“ )

Parameter („createaccess“)

Parameter ( personal data )

Parameter ( delivery data )

Parameter („autosubmit“ - credit card)

Parameter („autosubmit“ - direct debit)

Parameter („autosubmit“ - Online transfer)

Parameter („autosubmit“ - e-wallet)

Parameter („autosubmit“ - Financing)