Type Formats

The following base types are used throughout the Rest API.

TypeExampleDescription
String(y,x)"Some text"A sequence of characters delimited with double-quotation marks, with a minimum of 'y' and maximum of 'x' characters.
String(y,x)[]["Some text", "OtherText"]A list of strings, with the specified lengths.
Number(y,x)3330A number within the range of 'y' (inclusive) and 'x' (inclusive)
booleanfalseBoolean either 'true' or 'false'
Blockkey: { ... }A block identified by a key containing a collection of key-value pairs.
Block[]key: [ { ... }, { ... } ]An array of blocks identified by a key where each block contains a collection of key-value pairs.
Date"2017-02-24"A date formatted as yyyy-mm-dd.
DateTime"2017-02-24T17:08:43Z"A date and time in seconds formatted according ISO 8601 with timezone in UTC.

In addition, there are several fields that have a specific format and/or type.

Reference TypeActual TypeFormatDescription
MerchantKeyString(36, 36)UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76.The merchant key as received after registering an account.
ShopperKeyString(36, 36)UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76.The shopper key as received after creating a new shopper.
AddressKeyString(36, 36)UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76.The address key as received after creating a new shopper.
OrderKeyString(32, 32)alpha-numeric, all capitalsThe order key received after creating an order.
PaymentIdentifierString(14, 14)alpha-numeric, prefix 'pid', postfix 't'The payment identifier is received after starting a payment or when the shopper started a payment attempt in the menu.
CurrencyString(3, 3)alpha-numeric, all capitals, following ISO 4217 Alpha 3A currency code, for example "EUR".
LanguageString(2, 2)alpha-numeric, all lower case, following ISO 639-1 Alpha 2A language code, for example "nl".
CountryString(2, 2)alpha-numeric, all capitals, following ISO 3166-1 Alpha 2A country code, for example "NL".
UrlString(1, 255)alpha-numericA string containing an url starting with "http". Note: in some cases the URL can be longer than 255 characters, this specifically applies to intent/QR urls.
Enum(x)String(1, x)alpha-numeric, all capitals, the maximum size is specified by x.A value from a set of constant values. The first character is always a letter.
AmountNumber(1, 9_999_999_999)The amount of an order, payment, capture, refund, or chargeback always in the minor unit of the currency.
AmountZeroNumber(0, 9_999_999_999)Same as amount with zero as minimum. Only used in the OrderDetails-response for backwards compatibility.
PaymentMethodString(1, 255)enumeration, alpha-numeric, all capitals, including underscore (_).The name of a payment method. A list of possible values can be found in the table below.
AuthenticationMethodString(1, 255)enumeration, alpha-numeric, all capitals, including underscore (_).The authentication method used that successfully authenticated the shopper. A list of possible values can be found in the table below.

Enumeration Values

Payment Methods

The following values are allowed for the enumeration "PaymentMethod".

PaymentMethod ValueDescription
AMEXAMEX
APPLE_PAYApple Pay is wallet, can contain any kind of payment method
BANCONTACTBanContact
BANK_TRANSFERManual bank transfers
BELFIUS_PAY_BUTTONBelfius pay button
BLIKBlik
CBCCBC
E_FINANCINGLoan
EBANKINGSofort Banking
ELVELV
EPSEPS payment method
GIROPAYGiropay
GOOGLE_PAYGOOGLE payment method
IDEALiDEAL
IN_THREEin_three payment method
INVOICEInvoice payment method
KBCKBC
KLARNAKLARNA
MAESTROMaestro
MASTERCARDMastercard
OFFLINEOffline payment method
PAYPAL_EXPRESS_CHECKOUTPayPal.
PAYSAFECARDPaysafe card payment method
POINT_OF_SALEPoint of Sale payment method
PRZELEWY_24przelewy24 payment method
SEPA_DIRECT_DEBITSepa Direct Debit
SOFORT_UEBERWEISUNGSofortüberweisung
V_PAYV PAY is a Single Euro Payments Area (SEPA) debit card for use in Europe, issued by Visa Europe
VISAVisa

Authentication Methods

The following values are allowed for the enumeration "AuthenticationMethod".

Authentication Method ValueDescription
NOT_AUTHENTICATEDThe shopper is not authenticated or none of the methods succeeded
USER_PASSWORDThe shopper is successfully authenticated using a user name and password
OUT_OF_BANDThe shopper is successfully authenticated using an out-of-band method, for example verification via SMS
HARDWARE_KEYThe shopper is successfully authenticated through a secret/private key in a secure hardware solution, for example a smart-card or hardware-based OTP token generator
SOFTWARE_KEYThe shopper is successfully authenticated through a secret/private key in a secure software solution, for example a mobile application or software-based OTP token generator
LOCATION_BASEDThe shopper is authenticated through a location-based authentication method, for example the GPS location of the consumer device
ENVIRONMENTALThe shopper is authenticated through an environmental-based authentication method, for example the found WIFI SSID and MAC addresses in a secure software solution (mobile application)
BEHAVIORALThe shopper is authenticated through behavioral analysis, for example to discriminate the actual user from robots
BIOMETRICSThe shopper is successfully authenticated through biometric authentication, for example a fingerprint validation by mobile phone

It is allowed to combine various values with each other. For example, the values USER_PASSWORD and OUT_OF_BAND should be supplied to indicate that the shopper was successfully authenticated through username/password authentication and SMS verification.

The value NOT_AUTHENTICATED cannot be combined with any other value. This value is used to indicate that no authentication was performed at the website.

Field Requirements

For each field in the request and response the requirements are specified in the column M:

ValueDescription
M(andatory)The field must be included in the request or will be present in the response.
O(ptional)The field may be included in the request or may be present in the response.
C(onditional)The field must be included in the request or will be present in the response, depending on other conditions.