Resources

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.

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

Field Requirements

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.

Error Responses

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"
        ]
    }'