The Rest API works by sending http calls to specific resources identified by url's. The http verb (e.g. GET or POST) defines the action on the resource.
Resource | Description |
---|---|
Orders | Create, list and query order details. |
Items | Create and list order items. |
Payments | Start the Payment for a given Order. |
Captures | Create and update captures. |
Shoppers | Create shopper details. |
Methods | List available payment methods. |
Refunds | Refund an already processed payment. |
Subscriptions | Create and list subscriptions, and start recurring payments |
Apple Pay | Initialize and authorize Apple Pay payments. |
Google Pay | Authorize Google Pay payments. |
Adding additional payment data | Manage additional payment method specific payment data. |
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 references to 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 | 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. | |
PaymentMethod | String(1, 255) | alpha-numeric, all capitals, including underscore (_ ). |
The name of a payment method. A list of possible values can be found in the table below. |
The following values are allowed for the reference type "PaymentMethod".
PaymentMethod Value | Description |
---|---|
AFTERPAY_DIRECT_DEBIT |
Afterpay open invoice method. |
AFTERPAY_OPEN_INVOICE |
Afterpay open invoice method. |
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 |
BELMONDO_CADEAUBON |
Belmondo Cadeaubon. |
BLIK |
Blik |
BOEKENBON |
Boekenbon. |
CBC |
CBC |
DIAMOND_POINT |
Diamond Point cadeaukaart |
E_FINANCING |
Loan |
EBANKING |
Sofort Banking. |
EBON |
E-Bon Giftcard. |
ELV |
ELV. |
EPS |
EPS payment method. |
FASHION_CHEQUE |
Fashion cheque gift card. |
FASHION_GIFTCARD |
Fashion Giftcard. |
FIJNCADEAU_GIFTCARD |
Fijncadeau Giftcard. |
FONQ_NL_GIFTCARD |
Fonq.nl Giftcard. |
GIROPAY |
Giropay |
GOOGLE_PAY |
GOOGLE payment method. |
IDEAL |
iDEAL |
IN_THREE |
in_three payment method |
INVOICE |
Invoice payment method. |
JUMBO_GOLFWERELD_GIFTCARD |
Jumbo Golfwereld Giftcard. |
KBC |
KBC |
KLARNA |
KLARNA |
LOYALTY_IN_A_BOX |
Loyalty in a box. |
LUCARDI_GIFTCARD |
Lucardi Giftcard. |
MAESTRO |
Maestro. |
MASTERCARD |
Mastercard. |
NATIONALE_BIOSCOOPBON_GIFTCARD |
Nationale Bioscoopbon Giftcard. |
NATIONALE_ENTERTAINMENTCARD |
Nationale Entertainmentcard Giftcard. |
NATIONALE_KADOBON |
Nationale kadobon gift card. |
OFFLINE |
Offline payment method. |
OV_KADOKAART |
OV-kadokaart. |
PAYPAL_EXPRESS_CHECKOUT |
PAYPAL EXPRESS CHECKOUT. |
PAYSAFECARD |
Paysafe card payment method. |
PODIUM_GIFTCARD |
PODIUM Giftcard. |
POINT_OF_SALE |
Point of Sale payment method. |
PRZELEWY_24 |
przelewy24 payment method |
SEPA_DIRECT_DEBIT |
Sepa Direct Debit |
SIEBEL_JUWELIERS_CADEAUKAART |
Siebel Juweliers Cadeaukaart. |
SOFORT_UEBERWEISUNG |
Sofortüberweisung. |
TCS_GIFT_CARD |
Your gift card. |
V_PAY |
V PAY is a Single Euro Payments Area (SEPA) debit card for use in Europe, issued by Visa Europe. |
VISA |
Visa. |
VOETBAL_KADOBON |
Voetbal Kado gift card. |
VVV_GIFTCARD |
VVV Giftcard. |
WEB_SHOP_GIFT_CARD |
Web shop gift card. |
WIJNCARD |
Wijncard gift card. |
WINKELCHEQUE |
Winkel Cheque gift card. |
For each field in the request and response the requirements are specified in the column M:
Mandatory (M) | The field must be included in the request, or will be present in the response. |
Optional (O) | The field may be included in the request, or may be present in the response. |
Conditional (C) | The field must be included in the request, or will be present in the response, depending on other conditions. |
Errors are indicated by the http status 4xx. The JSON response contain the details of the error.
Response
Field | Type | M | Description |
---|---|---|---|
messages | String(1,255) [] | M | One or more messages giving details about the error. |
HTTP Status
Status | Meaning |
---|---|
400 (Bad Request) | The parameters or request are not valid. |
401 (Unauthorized) | Authorization header missing or invalid. |
403 (Forbidden) | The merchant key is not allowed, or the request is not (yet) allowed. |
404 (Not Found) | The reference was not found. |
405 (Conflict) | The new reference was not unique. |
500 (Internal Server Error) | Something went wrong. |
Error response example
> curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders \
-d '{
"reference" : "vk20170224p",
"description" : "Order 12345",
"amount" : 3330,
"currency" : "EUR",
"country" : "NLD"
}'
< Http 400 - Bad Request
< '{
"messages": [
"Property 'country' must match \"[A-Z]{2}\"",
"Property 'email' may not be null"
]
}'