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.

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 order.
AddressKey String(36, 36) UUID (36 characters), for example "4905560f-f83e-497d-a1cf-616d2cdbcf76. The merchant key as received after creating a new order.
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.

Note that for the identifiers in the previous all strings are without double-quotation marks.

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.


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"