Type Formats
The following base types are used throughout the Rest API.
| Type | Example | Description |
|---|---|---|
| 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) | 3330 | A number within the range of 'y' (inclusive) and 'x' (inclusive) |
| boolean | false | Boolean either 'true' or 'false' |
| Block | key: { ... } | 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 Type | Actual Type | Format | Description |
|---|---|---|---|
| MerchantKey | String(36, 36) | UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76. | The merchant key as received after registering an account. |
| ShopperKey | String(36, 36) | UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76. | The shopper key as received after creating a new shopper. |
| AddressKey | String(36, 36) | UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76. | The address key as received after creating a new shopper. |
| OrderKey | String(32, 32) | alpha-numeric, all capitals | The order key received after creating an order. |
| PaymentIdentifier | String(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. |
| Currency | String(3, 3) | alpha-numeric, all capitals, following ISO 4217 Alpha 3 | A currency code, for example "EUR". |
| Language | String(2, 2) | alpha-numeric, all lower case, following ISO 639-1 Alpha 2 | A language code, for example "nl". |
| Country | String(2, 2) | alpha-numeric, all capitals, following ISO 3166-1 Alpha 2 | A country code, for example "NL". |
| Url | String(1, 255) | alpha-numeric | A 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. |
| Amount | Number(1, 9_999_999_999) | The amount of an order, payment, capture, refund, or chargeback always in the minor unit of the currency. | |
| AmountZero | Number(0, 9_999_999_999) | Same as amount with zero as minimum. Only used in the OrderDetails-response for backwards compatibility. | |
| PaymentMethod | String(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. |
| AuthenticationMethod | String(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 Value | Description |
|---|---|
AMEX | AMEX |
APPLE_PAY | Apple Pay is wallet, can contain any kind of payment method |
BANCONTACT | BanContact |
BANK_TRANSFER | Manual bank transfers |
BELFIUS_PAY_BUTTON | Belfius pay button |
BLIK | Blik |
CBC | CBC |
E_FINANCING | Loan |
EBANKING | Sofort Banking |
ELV | ELV |
EPS | EPS payment method |
GIROPAY | Giropay |
GOOGLE_PAY | GOOGLE payment method |
IDEAL | iDEAL |
IN_THREE | in_three payment method |
INVOICE | Invoice payment method |
KBC | KBC |
KLARNA | KLARNA |
MAESTRO | Maestro |
MASTERCARD | Mastercard |
OFFLINE | Offline payment method |
PAYPAL_EXPRESS_CHECKOUT | PayPal. |
PAYSAFECARD | Paysafe card payment method |
POINT_OF_SALE | Point of Sale payment method |
PRZELEWY_24 | przelewy24 payment method |
SEPA_DIRECT_DEBIT | Sepa Direct Debit |
SOFORT_UEBERWEISUNG | Sofortüberweisung |
V_PAY | V PAY is a Single Euro Payments Area (SEPA) debit card for use in Europe, issued by Visa Europe |
VISA | Visa |
Authentication Methods
The following values are allowed for the enumeration "AuthenticationMethod".
| Authentication Method Value | Description |
|---|---|
NOT_AUTHENTICATED | The shopper is not authenticated or none of the methods succeeded |
USER_PASSWORD | The shopper is successfully authenticated using a user name and password |
OUT_OF_BAND | The shopper is successfully authenticated using an out-of-band method, for example verification via SMS |
HARDWARE_KEY | The 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_KEY | The 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_BASED | The shopper is authenticated through a location-based authentication method, for example the GPS location of the consumer device |
ENVIRONMENTAL | The 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) |
BEHAVIORAL | The shopper is authenticated through behavioral analysis, for example to discriminate the actual user from robots |
BIOMETRICS | The 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:
| Value | Description |
|---|---|
| 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. |