Date of cancellation as Unixtimestamp in the future (after this date no further renewals will be carried out)
Format
Unixtimestamp
access_expiretime
Can be
either used with creating a new access (createaccess) -> Set expiry date/time of the initial term as Unixtimestamp (e.g. date of first renewal)
- deprecated, should not be used. Please use “period_unit_trail”, “period_length_trail” instead. - do not use with “period_unit_trail”, “period_length_trail”
or used with updating an existing access (updateaccess) -> Update expiry date/time of the current term as Unixtimestamp (e.g. overwrite date of next renewal)
Format Unixtimestamp
access_starttime
Access starting date as Unixtimestamp
Format
Unixtimestamp
action
Action to perform to given contract
Format LIST
Value
Comment
update
Update access (default)
cancel
Cancel subscription
reverse_cancel
Revoke cancellation of subscription
lock
Block access
unlock
Unblock access
add_paydata[..._entity_type]
Klarna (KLS, KLV, KIV, KIS) - Extra Merchant Data → Value range: Link
Format LIST
Payment specific:
Payment type
Comment
KLS, KLV, KIV, KIS
Mandatory for B2B transactions
Values:
Value
LIMITED_COMPANY
PUBLIC_LIMITED_COMPANY
ENTREPRENEURIAL_COMPANY
LIMITED_PARTNERSHIP_LIMITED_COMPANY
LIMITED_PARTNERSHIP
GENERAL_PARTNERSHIP
REGISTERED_SOLE_TRADER
SOLE_TRADER
CIVIL_LAW_PARTNERSHIP
PUBLIC_INSTITUTION
OTHER
add_paydata[reservation_txid]
The reservation_txid is a technical id returned from the PAYONE platform to identify a reservation. A reservation is a part of a payment process (identified by a txid). The reservation is used for "genericrequest".
Format
CHAR(12..50)
Permitted Symbols [0-9,A-Z]
add_paydata[...url_standard_n]
Example = Response from Content Delivery network Klarna (https, svg) Sample: Badge
add_paydata[...url_descriptive_n]
Example = Response from Content Delivery network Klarna (https, svg) Sample: Badge
add_paydata[...identifier_n]
The values known to us at the time of implementation are as follows:
Payment Category
pay_later
direct_debit
pay_over_time
add_paydata[...tegory_name_n]
Payment Type
Slice it
Pay Later
Direct debit
addressaddition
Specifies an additional address line for the invoice address of the customer.
Format CHAR(1..50)
Samples 7th floor
c/o Maier
Payment specific:
Payment type
Comments
KLV, KLS
Mandatory
addresschecktype
Specifies type of address check to be performed
Format LIST
Value
Group
Comment
BA
PAYONE Services
Addresscheck Basic, i.e. address is checked whether the address itself is valid and existing
PE
PAYONE Services
Addresscheck Person, i.e. address is checked whether the address itself is valid and existing and whether the given person is recorded at this address
BB
Boniversum Services
Addresscheck Basic, i.e. address is checked whether the address itself is valid and existing
PB
Boniversum Services
Addresscheck Person, i.e. address is checked whether the address itself is valid and existing and whether the given person is recorded at this address
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
Payment specific:
Payment type
Comments
PDT
Maximum amount is limited to 5000000 (i.e. 50,000.00 Euro)
amount capture
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
Special use cases:
with previous preauthorization and clearingtype=”cc”: An “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at the acquirer.
with previous preauthorization and clearingtype=”wlt”, wallettype=”PPE”: An “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at PayPal.
with previous preauthorization/ authorization and clearingtype=”elv”: An “amount = 0” can be used to cancel a direct debit transaction. This is not possible if the parameter “due_time” has been used, if the portal has enabled a delayed settlement (setup by PAYONE) or the direct debit has already been processed (after midnight).
with previous preauthorization and clearingtype=”fnc”, “financingtype=“KLV” or “KLS”: An “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at external Payment Service Provider.
Not supported for other payments.
amount debit
Gross amount of debit (in smallest currency unit! e.g. cent, max. 19 999 999 99)
Credit: amount < 0
Payment request: amount > 0
The amount must be less than or equal to the amount of the outstanding payment request of the corresponding booking.
Format
NUMERIC(1..10)
Permitted values
max. +/- 19 999 999 99
amount refund
Amount of refund (in smallest currency unit! e.g. cent, max. 19 999 999 99). The amount must be less than or equal to the amount of the corresponding booking. Always provide a negative amount
Format NUMERIC(1..10)
Permitted values
max. +/- 19 999 999 99
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)
Permitted values
max. +/- 19 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.
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”
URL is required for any type of redirect payments, e.g. - Bancontact, EPS, Giropay, iDEAL, Multibanco, PostFinance, Przelewy24, SOFORT, Trustly, ... - PayPal, ... - credit card with 3-D secure
Allowed schemes for URL: - For Channel "Frontend" / "Client-API" only schemes "http" or "https" allowed. - For Channel "Server-API" individual schemes like "app://app.domain.com" is allowed
URL can be - either defined in PMI -> configuration -> portal -> then this URL is used as default (this requires channel "Frontend" to be avalibale) - or it can be specified via API parameter -> then this URL overrides the PMI-configuration.
Example
Valid for all channels (Server, Client, Frontend):
https://www.domain.com/success.html
https://www.domain.com/success.html?exit=success&txid=__txid__
https://www.domain.com/back.html?exit=back
https://www.domain.com/error.html?exit=error&errorcode=__errorcode__
Valid additionally for Server-API:
app://app.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/error.html?exit=error&errorcode=__errorcode__
Payment specific:
Payment type
Comments
Redirect payment
For redirect payments (e.g. PayPal, Giropay, SOFORT, ...) an URL has to be provided.
It can be
either defined in PMI -> configuration -> portal -> then this URL is used as default
or it can be specified via API parameter -> then this URL overrides the PMI-configuration.
bankaccount
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)
bankaccountholder
Account holder
Format
CHAR(1..50)
The account holder is required for bank transfer (SEPA direct debit and SEPA credit transfer). If the account holder is not specified the PAYONE platform will use firstname / lastname / company for account holder
bankcode
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)
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
bankcountry obt
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
Values
onlinebanktransfertype
Payment type
BE
BCT
Bancontact
AT
EPS
EPS
NL
IDL
iDEAL
PT
MBC
Multibanco
IT
MYB
MyBank
PL
P24
Przelewy24 (P24)
CH
PFC
PostFinanceCard
CH
PFF
Post E-Finance
DE;AT;CH;NL;PL;BE
PNT
SOFORT
DE;DK;EE;ES;FI;IT;
MT;NL;NO;PL;SE
TRL
Trustly
FI
VKP
Verkkopankki
bankgrouptype
Issuer of Online-Bank-Transfer used for iDEAL and EPS
Format
LIST
Value
Comment
List of supported EPS banks
Bank Groups (EPS) (bankgrouptype)
List of supported iDEAL banks
Bank Groups (iDEAL) (bankgrouptype)
Payment specific:
Payment type
Comment
EPS
Mandatory
IDL
Mandatory
bic
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.
birthday
Date of birth of customer
Format
DATE(8), YYYYMMDD
Samples
20190101
19991231
Payment specific:
Request
Payment type/ score type
Comments
preauthorization authorization
KLV, KLS, KIV, KIS
Parameter is mandatory for this payment type
preauthorization authorization
POV
Parameter is mandatory for this payment type with businessrelation=b2c
preauthorization authorization
PYV, PYM, PYS, PYD
Parameter is mandatory for this payment
consumerscore
SCHUFA Services “b2c”
Parameter is mandatory for this request
booking_date
Booking date (YYYYMMDD)
Format
DATE(8), YYYYMMDD
businessrelation
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)
Request specific:
Payment type
Comment
POV
Mandatory
Full list of values:
Value
Business from
Business to
Comment
b2c
business (company)
consumer (private)
b2b
business (company)
business (company)
b2a
business (company)
administration (government)
not in use by now
a2a
administration (government)
administration (government)
not in use by now
a2b
administration (government)
business (company)
not in use by now
a2c
administration (government)
consumer (private)
not in use by now
c2a
consumer (private)
administration
not supported
c2b
consumer (private)
business (company)
not supported
c2c
consumer (private)
consumer (private)
not supported
businessrelation (scoring)
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)
Payment specific:
Consumerscoretype
Comment
SFS, SFM
"businessrelation" is mandatory for SCHUFA-checks
other
"businessrelation" is recommended be set to "b2c" for other checks
Specifies whether this capture is the last one or whether there will be another one in future.
Format
LIST
Value
Comment
completed
Set with last capture; i.e.: Delivery completed.
No further capture is allowed.
notcompleted
Set with partial deliveries (last delivery with "completed")
Another capture is expected to complete the transaction.
Payment specific:
Payment type
Comment
PDT
Parameter "capturemode" is mandatory.
KLS, KLV
Parameter "capturemode" is mandatory.
cardcvc2
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.
cardexpiredate
Credit card expiry date YYMM
Format
NUMERIC(4), YYMM
cardexpiremonth
Credit card expiry month MM
Format
NUMERIC(2), MM
cardexpireyear
Credit card expiry year YYYY
Format NUMERIC(4), YYYY
cardholder
Cardholder of credit card.
Format
CHAR(1..50)
if the cardholder is not specified the PAYONE platform will use firstname / lastname for cardholder However, the correct cardholder name plays a great role in the internal risk assessment of the issuer, so providing it can be beneficial in terms of 3-D Secure
cardissuenumber
Card issue number (only Maestro UK cards)
Format
NUMERIC(1..2)
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
Full list of values:
M
Value
Commentfrom
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
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.)
Parameter "cardtype" can be omitted for request "creditcardcheck". The card type will then be detected automatically and returned in response.
Parameter "cardtype" must be present for credit card payment requests . Value for "cardtype" can be retrieved from previous creditcardcheck-response.
cavv
3-D Secure authentication value
Format
CHAR(1..40)
checktype
Specifies type of check to be performed, e.g. creditcardcheck or bankaccountcheck
Format LIST
Request
Value
Comment
bankaccountcheck
0
regular check (default)
IBAN is checked for correct syntax (mode live only)
IBAN is splitted into BBAN (mode live only)
bankaccountcheck
1
check against POS blacklist (only DE)
bankaccountcheck
2
check against NCA list (non-consumer account)
creditcardcheck
without "checktype" given the regular check is performed (LUHN-check)
For Deutsche Bahn only:
Request
checktype
Comment
creditcardcheck
TC
For Deutsche Bahn only: extended check for travelcards with specific response data
city
City of customer
Format
CHAR(2..50)
Payment specific:
Payment type
Comments
KLV, KLS
Mandatory
PYV, PYM, PYS, PYD
Mandatory
ELV
Mandatory for direct debit (ELV) used with IBAN-countries CH, SM, MC, PM, JE, GG
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. This takes effect when “capture” is done.
clearingsubtype
Only valid with “clearingtype=rec”. Used for PAYONE Secure Invoice.
Format
LIST
Value
Comment
POV
PAYONE secure purchase on invoice
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
clearingtype debit
Use for changes of payment type - only to select new payment type.
Format
LIST
Payment specific:
Value
Comments
rec
Invoice
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)
Payment specific:
Payment/ request type
Comments
PNT
Company name is limited to 27 characters
consumerscore B2B
"company" required for b2b-request (e.g. “PAYONE GmbH”)
"company" empty for person managed companies
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"
Request restrictions:
Request
Comment
addresscheck
Check “BB”, “PB”: only “DE” supported
consumerscore
only “DE” supported
creditor_identifier
Creditor identifier as recorded at PAYONE
Format
CHAR(1..35)
currency
Specifies currency for this transaction
Format
LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples EUR USD GBP
customerid
Merchant's customer ID, defined by you / merchant to refer to the customer record
Format CHAR(1..20)
Permitted values [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.
customermessage
The customermessage is returned to your system in order to be displayed to the customer.
(Language selection is based on the end customer's language, parameter "language")
Format
CHAR(1..1024)
With “api_version>=3.10” you may get more detailed error messages from the external payment processor (e.g. Ratepay)
customer_is_present
Indicates whether customer is “present” and can enter their data in the shop (=yes). Or customer is not present and can not enter any data (=no).
Format
LIST
Permitted values yes
no
consumerscoretype
Specifies type of consumer score to be performed.
Format LIST
Value
Comment
Arvato Infoscore Services – must be combined with addresschecktype “NO”, “BA”, “PE”
Specifies whether the customer address should be queried - instead of providing them in the Frontend request URL.
Format LIST
Payment specific:
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.
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
document_date
Document date (YYYYMMDD)
Format DATE(8), YYYYMMDD
due_time
Due date (Unixtimestamp)
Format
Unixtimestamp
Payment specific:
Payment type
Comment
rec
Due time of the invoice; needed to start dunning run
elv
Debit will be initiated on this date. Please pay attention that 5 or 2 days are added to the due_time – depending on FIRST or RECURRENT debit.
E
eci
3-D Secure e-commerce indicator
Format
CHAR(1..2)
ecommercemode
Specifies how the payment transaction should be processed - if not default.
Format LIST
Value
Comments
internet
eCommerce Transaction (SSL secured)
3dsecure
3-D Secure transaction (can be enabled alternatively in the risk settings)
moto
Mail or telephone order transaction
A credit card transaction has different types of processing, e.g. "internet/ecommerce" (e.g. online shop) or "moto" (e.g. call center). A default can be setup in a payment portal (identified by portalid) with different defaults per portal. This default can be overruled by this parameter.
However: a callcenter payment transaction can never be 3-D secure as the customer will not be able to personally enter the 3-D password and he will never tell it to a callcenter agent.
ed[n]
Delivery period end date (YYYYMMDD)
Format DATE(8), YYYYMMDD
Array
Array elements [n] starting with [1]; serially numbered; max [400]
URL is required for any type of redirect payments, e.g. - Bancontact, EPS, Giropay, iDEAL, Multibanco, PostFinance, Przelewy24, SOFORT, Trustly, ... - PayPal, ... - credit card with 3-D secure
Allowed schemes for URL: - For Channel "Frontend" / "Client-API" only schemes "http" or "https" allowed. - For Channel "Server-API" individual schemes like "app://app.domain.com" is allowed
URL can be - either defined in PMI -> configuration -> portal -> then this URL is used as default (this requires channel "Frontend" to be avalibale) - or it can be specified via API parameter -> then this URL overrides the PMI-configuration.
---end
Example
Valid for all channels (Server, Client, Frontend):
https://www.domain.com/success.html
https://www.domain.com/success.html?exit=success&txid=__txid__
https://www.domain.com/back.html?exit=back
https://www.domain.com/error.html?exit=error&errorcode=__errorcode__
Valid additionally for Server-API:
app://app.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/error.html?exit=error&errorcode=__errorcode__
Payment specific:
Payment Type
Comment
Redirect payment
For redirect payments (e.g. PayPal, Giropay, SOFORT, ...) an URL has to be provided. It can be
either defined in PMI -> configuration -> portal -> then this URL is used as default
or it can be specified via API parameter -> then this URL overrides the PMI-configuration.
errormessage
In case of error the PAYONE Platform returns an error message for your internal usage.
Format CHAR(1..1024)
Please refer to the error codes section.
The errormessage is returned to your system and should only be used for internal purpose (e.g. logging).
It should not be returned to the customer.
exiturl
Exit-URL to be forwarded after authentication on the ACS
Format
CHAR(2..255)
F
financingtype
Used with "clearingtype=fnc" to identify Financing type
Format
LIST
Value
Comment
Server-API
Client-API
Frontend
RPV
Ratepay Open Invoice
x
x
x
RPS
Ratepay Installments
x
x
RPP
Ratepay Prepayment
x
x
x
RPD
Ratepay Direct Debit
x
x
x
PYV
Unzer Invoice
x
x
PYS
Unzer Installment
x
x
PYD
Unzer Direct Debit
x
x
KIS
Klarna Payments "Slice it" (Installments)
x
KIV
Klarna Payments "Pay now" (Invoice)
x
KDD
Klarna Payments "Pay now" (Direct Debit)
x
KBT
Klarna Payments "Pay now" (Bank Transfer)
x
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)
Payment specific:
Payment/ request type
Comment
PNT
Combination of firstname + lastname is limited to 27 characters
BCT
firstname / lastname are always mandatory
KLV, KLS
firstname / lastname are always mandatory
PYV, PYM, PYS, PYD
firstname / lastname are always mandatory
PDT
firstname is optional
addresscheck
firstname / lastname are always mandatory
consumerscore
firstname / lastname are always mandatory
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)
G
gender
Gender of customer (female / male / diverse)
Format
LIST
Permitted values
f
m
d
Payment type
Comment
KLV, KLS
Mandatory in DE, NL, AT
getusertoken
Can be used to get a reference (usertoken) to a debtor which can be passed to another merchant account within the PAYONE platform.
This usertoken is valid for 15 minutes. This reference to a PAYONE debtor can be used for authorization / preauthorization. The debtor-data will then be copied to the other merchant account.
Must not be used together with Parameter "type".
Format LIST
Value
Comment
yes
get usertoken
H
hash
The hash code is used to prevent that a customer changes any relevant value (like payment type, your MID or the amount).
Format
CHAR(1..96) lowercase
Permitted Symbols [0-9,a-z]
I
iban
IBAN to be used for payment or to be checked
Format
CHAR(10..34)
Permitted Symbols
[0-9][A-Z]
IBAN / BIC will be validated.
Only capital letters and digits, no spaces
It's not checked whether IBAN and BBAN (Bankcode/Bankaccount) refer to the same account or whether the account does exist.
For some countries IBAN, BIC will be splitted into bankcode, bankaccount automatically
If both (bankcode/bankaccount and IBAN) are submitted, IBAN is splitted into bankcode/bankaccount and IBAN is used for processing - bankcode/bankaccount parameters are ignored.
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][()[]{} +-_#/:]
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][()[]{} +-_#/:]
id[n]
Product number, SKU, etc. of this item
Format
CHAR(1..32)
Array
Array elements [n] starting with [1]; serially numbered; max [100]
Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]
invoiceappendix
Dynamic text on the invoice
Format
CHAR(1..255)
You may use "|" (pipe-symbol) to transmit up to three individual text lines which will be placed on customer documents (invoice, credit note, reminder).
This text will then be displayed at the end of the document - each part in a new line.
invoiceid
Merchant's invoice number
Format CHAR(1..20)
The PAYONE platform can also incremented the invoiceid automatically. By this your invoices and credit notes will always have a unique id.
The prefix can be specified by our merchant service, e.g. "INVOICE-" - so invoiceids will be generated like "INVOICE-1", "INVOICE-2", "INVOICE-3", ...
The start number can be given as well.
The invoiceid will then be in a sequence for invoices and credit notes (sharing the same sequence).
invoice_deliverydate
Delivery date (YYYYMMDD)
Format
DATE(8), YYYYMMDD
invoice_deliveryenddate
Delivery end date (YYYYMMDD)
Format
DATE(8), YYYYMMDD
invoice_deliverymode
Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer.
Format LIST
Value
Comments
M
Postal Mail
P
PDF (via email)
N
no delivery
ip
Customer's IP-V4-address (123.123.123.123) or IP-V6-address
Format
CHAR(1..39)
Payment specific for clearingtype financing:
financing type
Comments
KLS, KLV
Mandatory
PYV, PYM, PYS, PYD
Mandatory
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]
Payment portal key as MD5 value. The key is used to check the authentification of the sender (either your system for sending requests or PAYONE platform for sending notifications).
Format
CHAR(1..32) lowercase
Permitted Symbols
[0-9,a-z]
MD5 value has to be presented in lower case
Not the key as a value is used, but the MD5 hash of the key value.
You can assign the key to be used in the PMI (PAYONE Merchant Interface) in the portal configuration.
Do not pass this key to third parties in any case.
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
ISO 639-1 (Language) 2-letter-codes
Languages supported for specific customer messages:
Value
Language
de
German
en
English
es
Spanish
fr
French
it
Italian
nl
Dutch
pt
Portuguese
Payment specific reference:
Payment type financingtype
Comments
KLV, KLS
Parameter is mandatory for this payment type
This payment types supports following languages
Code
Meaning
sv
swedish
nb
norwegian
fi
finnish
da
danish
de
german
nl
dutch
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)
Payment specific:
Payment/request type
Comments
PNT
Combination of firstname + lastname is limited to 27 characters
BCT
firstname / lastname is mandatory
KLV, KLS
firstname / lastname is mandatory
PYV, PYM, PYS, PYD
firstname / lastname is mandatory
PDT
lastname is mandatory
PSC
firstname / lastname is mandatory
addresscheck
firstname / lastname is mandatory
consumerscore
firstname / lastname is mandatory
M
mandate_identification
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
mandate_status
Status of SEPA mandate
Format
LIST
Value
Comment
pending
indicates a new created mandate Pending mandate has to be used within 2 hours by authorization / preauthorization to complete a payment.
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]
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]
pr[n]
Unit gross price of the item in smallest unit! e.g. cent
Format
NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
pseudocardpan
Pseudo primary account number for a credit card.
Format
NUMERIC(16..19)
This pseudo card pan is a token to a real cardpan, but it's not PCI DSS relevant. So therefore it can be handled and stored by the merchant system without any PCI DSS impact - however you have to complete a PCI DSS compliance in any case.
This token is unique per merchant and cardpan/expiredate and can be used in any payment-request with credit cards to refer to an existing credit card in the PAYONE platform.
Indicates recurring payments. Currently supported for PayPal and Credit Card payments.
Format
LIST
Value
Comments
installment
a recurring payment, which has an a priori defined frequency, limit/threshold and end date
none
a non recurring payment, i.e. a single authorization which might be captures at once or later in one or multiple charges
oneclick
a form of payment on which the cardholder is authenticated only on the initial transaction. Follow-up transactions are authorized without active interaction of the cardholder
recurring
a recurring payment, which has an a priori defined frequency and limit/threshold
redirecturl
Redirect URL → zMerchant system has to redirect customer to this URL to complete payment
Format
CHAR(2..2000)
Payment specific:
Payment type
Comment
Redirect payment
Merchant system has to redirect customer to this URL to complete payment
reference
Merchant reference number for the payment process (case insensitive)
Format
CHAR(1..20)
Permitted Symbols
[0-9][a-z][A-Z], .,-,_,/
Special limits / restrictions:
Payment type
Format
GPY
CHAR(4..16)
PDT
_ is not allowed
Merchant Reference has to be unique per merchant (mid) and mode, i.e.: the same Reference can be used for Live / Test
Merchant Reference can not be the same for two different portals, i.e.: Portal X, Mode=Live and Portal Y, Mode=Live
reg 2015-847
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.
reminderlevel
Set reminder status
Format
LIST
Value
Comment
1
1st dunning level
2
2nd dunning level
3
3rd dunning level
4
4th dunning level
5
Transfer to an encashment agency
A
Dunning procedure ended
S
Dunning procedure starts (again)
M
Dunning proposal list
I
Encashment proposal list
remindertime
Date of the next dunning level as Unixtimestamp (the next reminder will be sent on this date)
Format
Unixtimestamp
request
The type of request you would like to perform
Format
LIST
S
salutation
The customer's salutation
Format
CHAR(1..10)
SAQ A
Please refer to PCI DSS Security Standards listed in SAQ A V3 on https://de.pcisecuritystandards.org
score
Indication for all consumerscoretypes
Format
LIST
Value
Comments
G
"green", high degree of creditworthiness
Y
"yellow", average degree of creditworthiness
R
"red", low degree of creditworthiness
U
unknown / not available
Please keep in mind that each merchant may have a different need of safety.
The scorevalue is more detailed - but not for all services present.
sd[n]
Delivery date (YYYYMMDD)
Format
DATE(8), YYYYMMDD
Array
Array elements [n] starting with [1]; serially numbered; max [400]
secstatus
Response code of address check to return whether address has been corrected
Format
LIST
Value
Status
Comment
10
VALID
address correct
20
VALID
address could be corrected / has changed
30
INVALID
address could not be corrected
secscore
For consumerscoretype: IA, IB, IH, IF; Negative criteria if registered.
Format
LIST
sendreminder
Send reminder to customer yes / no
Format
LIST
Value
Comments
yes
Sends the reminder for the current/ updated dunning level, or transfers the case to encashment when dunning level 5 is reached.
no
Simply sets the indicated dunning level.
sequencenumber
Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2
Required for multi partial capture (starting with the 2nd capture)
Format
NUMERIC(1..3)
Permitted values 0..127
settleaccount
Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.
Format
LIST
Value
Comment
yes
Settlement of outstanding balances is carried out.
no
Do not carry out settlement of outstanding balances, book request only.
auto
The system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)
Payment specific:
Payment type
Comment
KLS, KLV
Value "no" is not valid for Klarna and will be rejected.
settleaccount response
Provides information about whether a settlement of balances has been carried out.
Format
LIST
Value
Comment
yes
Settlement of outstanding balances has been carried out.
no
Settlement of outstanding balances has not been carried out.
settletime
Date for the next invoicing Unixtimestamp in the future.
Format
Unixtimestamp
settle_period_length
Length of the accounting period
Format
NUMERIC(1..3)
settle_period_unit
Time unit of the accounting period
Format
LIST
Value
Comment
Y
Value “length” is in years
M
Value “length” is in months
D
Value “length” is in days
shipping_addressaddition
Specifies an additional address line for the delivery address of the customer, e.g. "7th floor", "c/o Maier".
Format
CHAR(1..50)
shipping_city
City of delivery address
Format
NUMERIC(1..3)
shipping_company
Company Name of the 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
shipping_firstname
First name of delivery address
Format
CHAR(1..50)
shipping_lastname
Surname of delivery address
Format
CHAR(1..50)
shipping_state
Specifies country of delivery address for the customer
Specifies state of country of delivery address for the customer
"shipping_state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN (if shipping_country is given) and must not be used in all other countries.
Format
LIST
Permitted values
ISO 3166-2 States (regions) 2-letter-codes
Samples US
AK AL AR
Samples CA
AB BC
shipping_street
Street number and name of delivery address
Format
CHAR(2..50)
shipping_zip
Postcode of delivery address
Format
CHAR(2..10)
Permitted values
[0-9][A-Z][a-z][_.-/ ]
shippingprovider
Shipping Provider
Format
LIST
Shipping Provider
Comment
DHL
DHL, Germany
state
Specifies state / region of country for the customer.
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.
Format
LIST
Permitted values
ISO 3166-2 States (regions) 2-letter-codes
Samples US
AK AL AR
Samples CA
AB BC
storecarddata
Specifies whether a pseudocardnumber shall be generated for later use (e.g. payment request)
Format
LIST
Value
Comment
no
Card data is not stored
yes
Card data is stored, a pseudo card number is returned
street
Street number and name (required: at least one character)
Format
CHAR(1..50)
Payment specific:
Payment Type
Comment
KLV, KLS
Mandatory
PYV, PYM, PYS, PYD
Mandatory
ELV
Mandatory for direct debit (ELV) used with IBAN-countries CH, SM, MC, PM, JE, GG
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. This takes effect when “capture” is done.
streetname
Street name
Format
CHAR(1..50)
streetnumber
Street number
Format
CHAR(1..50)
subtype
Overview of "cardtype" in use with "clearingtype=cc"
Card type of credit card
Format
LIST
Value
Comment
BIN-Range for automatic 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
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
Overview of "clearingsubtype" in use with "clearingtype=rec"
Only valid with “clearingtype=rec”. Used for PAYONE Secure Invoice.
Format
LIST
Value
Comment
POV
PAYONE secure purchase on invoice
Overview of "financingtype" in use with "clearingtype=fnc"
Used with "clearingtype=fnc" to identify Financing type
Format
LIST
Value
Comment
Server-API
Client-API
Frontend
RPV
Ratepay Open Invoice
x
x
x
RPS
Ratepay Installments
x
x
RPP
Ratepay Prepayment
x
x
x
RPD
Ratepay Direct Debit
x
x
x
PYV
Unzer Invoice
x
x
PYS
Unzer Installment
x
x
PYM
Unzer Monthly
x
x
PYD
Unzer Direct Debit
x
x
PPI
PayPal Installment
x
x
KLV
Klarna Checkout Invoice
x
x
KLS
Klarna Checkout Installment
x
x
KIS
Klarna Payments "Slice it" (Installments)
x
KIV
Klarna Payments "Pay now" (Invoice)
x
KDD
Klarna Payments "Pay now" (Direct Debit)
x
KBT
Klarna Payments "Pay now" (Bank Transfer)
x
PIV
PAYONE Secured Invoice
x
PDD
PAYONE Secured Direct Debit
x
PIN
PAYONE Secured Installment
x
Overview of "onlinebanktransfertype" in use with "clearingtype=sb"
Format
LIST
Value
Comment
Server-API
Client-API
Frontend
BCT
Bancontact
x
x
EPS
eps – online transfer (AT)
x
x
x
IDL
iDEAL (NL)
x
x
x
MBC
Multibanco
x
x
MYB
MyBank
x
x
P24
Przelewy24 (PL)
x
x
x
PFF
PostFinance E-Finance (CH)
x
x
x
PPI
PayPal Installment
x
x
x
PFC
PostFinance Card (CH)
x
x
x
PNT
SOFORT Überweisung
x
x
x
TRL
Trustly
x
x
VKP
Verkkopankki
x
x
Overview of "wallettype" in use with "clearingtype=wlt"
Used with "clearingtype=wlt" to identify wallet payment types
Allowed schemes for URL: - For Channel "Frontend" / "Client-API" only schemes "http" or "https" allowed. - For Channel "Server-API" individual schemes like "app://app.domain.com" is allowed
URL can be -either defined in PMI -> configuration -> portal -> then this URL is used as default (this requires channel "Frontend" to be avalibale) - or it can be specified via API parameter -> then this URL overrides the PMI-configuration.
Example
Valid for all channels (Server, Client, Frontend):
https://www.domain.com/success.html
https://www.domain.com/success.html?exit=success&txid=__txid__
https://www.domain.com/back.html?exit=back
Valid additionally for Server-API:
app://app.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/success.html?exit=success&txid=__txid__
Payment specific:
Payment type
Comment
Redirect payment
For redirect payments (e.g. PayPal, Giropay, SOFORT, ...) an URL has to be provided. It can be - either defined in PMI -> configuration -> portal -> then this URL is used as default - or it can be specified via API parameter -> then this URL overrides the PMI-configuration.
scorevalue
The scorevalue is a more detailed indication of credit worthiness of customers than the score (traffic light).
Please pay attention that the values and the interpretation are provider specific.
Format
NUMERIC(1..4), values and ranges see table below.
consumerscoretype
Provider
Range
Remarks
IA, IB, IH, IF
Arvato Infoscore
Score: 100-990
The higher the value, the higher the degree of creditworthiness
Please refer to Decision matrix Arvato Infoscore Boni-Score/Informa-Score
CE
Boniversum VERITA
Score: 0-6000
The higher the value, the lower the degree of creditworthiness
Please refer to Decision matrix Boniversum VERITA score
SFS, SFM
SCHUFA B2B
Score: 100-600
The higher the value, the lower the degree of creditworthiness; values e.g. “100”, “204”, “202.3”
SFS
SCHUFA B2C
Score: 1-9999
The higher the value, the higher the degree of creditworthiness
secscore
For consumerscoretype: IA, IB, IH, IF; Negative criteria if registered.
Type “tel” can be used to display a simple, numeric phone keyboard on mobile devices.
telephonenumber
Phone number of customer
Format
CHAR(1..50)
Payment specific:
Payment Type
Comment
KLV, KLS
Parameter is mandatory for this payment type
title
Title of the customer
Format
CHAR(1..20)
Samples
Dr Prof. Dr.-Ing.
ti_recurring[n]
Title (subsequent term)
Format
CHAR(1..100)
Array
Array elements [n] starting with [1]; serially numbered; max [100]
ti_trail[n]
Title (initial term)
Format
CHAR(1..100)
Array
Array elements [n] starting with [1]; serially numbered; max [100]
transaction_param
Optional parameter for merchant information (per payment request)
Format
CHAR(1..50)
Permitted Symbols
[0-9][A-Z][a-z][.-_/]
- In case of Paypal this parameter is passed to Paypal as "PAYMENTREQUEST_n_CUSTOM" to appear as merchant customizable value in Paypal settlement files. - Only used for reporting purpose on PMI-export “Export -> Payment events”. - param is an individual parameter per payment process, which can be exported with PMI -> export -> payments - transaction_param is an individual parameter per payment request which can be exported with PMI -> export -> payment events
transactiontype
Type of payment request
Format
LIST
Value
Comment
RL
Direct debit return fee
MG
Dunning charge
VZ
Default interest
VD
Delivery charges
FD
Payment request (default for amount > 0)
GT
Credit (default for amount < 0)
RT
Returns
truncatedcardpan
Masked cardpan, i.e. 411111xxxxxx1111 (is returned if storecarddata=yes)
Format
CHAR(13..19)
The first six and the last four digits are visible - the rest ist masked. This presentation is PCI DSS compliant and may be stored and logged.
txid
The txid specifies the payment process within the PAYONE platform
Format
NUMERIC(9..12)
type
Type of request:
getuser: Can be used to retrieve debtor data. Must not be used together with “getusertoken”
Format
LIST
Request
Value
Comment
getuser
userdata
Returns user data of debtor (in JSON only)
HTTP Accept header in the API request has to be set to “Accept: application/json” to indicate that a JSON response should be sent.
getuser
usertoken
Get usertoken for further authorization/preauthorization
U
use_customerdata
Use account details from debtor's master data
Format
CHAR(1..50)
Value
Comment
yes
Uses current account details from debtor's master data (default)
no
Uses the last known account details in the payment process
UsedInHash
The parameters with a "+" must be included in the calculation of the hash value to prevent changes by the customer.
userid
PAYONE User ID, defined by PAYONE
Format
NUMERIC(6..12)
"userid" can be used to refer to an existing customer record. "userid" must already exist and mode (test/live) must must match.
If "userid" is used then stored customer data are loaded automatically.
usertoken
PAYONE User token, defined by PAYONE
Format
CHAR(30)
Reference to debtor which can be used for authorization / preauthorization within 15 minutes from another merchant id.
V
vaccountname
ID/name of the merchant's billing account
Format
CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]
va[n]
VAT rate (% or bp)
Format
NUMERIC(4)
Array
Array elements [n] starting with [1]; serially numbered; max [400]
- value <= 99 = per cent (e.g. 19 = 19%)
- value > 99 = basis points (e.g. 1900 = 19%)
Payment specific:
Payment Type
Comment
KLS, KLV
Mandatory
va_recurring[n]
VAT rate (% or bp) (subsequent term)
Format
NUMERIC(4)
Array
Array elements [n] starting with [1]; serially numbered; max [100]
- value <= 99 = per cent (e.g. 19 = 19%)
- value > 99 = basis points (e.g. 1900 = 19%)
va_trail[n]
VAT rate (% or bp) (first term)
Format
NUMERIC(4)
Array
Array elements [n] starting with [1]; serially numbered; max [100]
- value <= 99 = per cent (e.g. 19 = 19%)
- value > 99 = basis points (e.g. 1900 = 19%)
vaid
Billing account ID
Format
NUMERIC(1..8)
vatid
VAT identification number. Used for b2b transactions to indicate VAT number of customer.
The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.
Format
CHAR(1..50)
X
xid
3-D Secure transaction ID (if the request "3dscheck" was used previous transactions), i.e.:
value for "xid" is returned by request 3dscheck (optional request)
and then has to be used for request authorization, preauthorization or createaccess in request data
Format
CHAR(1..60)
Y
Z
zip
Postcode
Format
CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]
Payment specific:
Payment Type
Comment
KLV, KLS
Mandatory
PYV, PYM, PYS, PYD
Mandatory
ELV
Mandatory for direct debit (ELV) used with IBAN-countries CH, SM, MC, PM, JE, GG
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. This takes effect when “capture” is done.