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.
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.
Apple Pay Initialize and authorize Apple Pay payments.

Type Formats

The following types are used throughout the Rest API.

Type Example Description
String "AUTHORIZED" A sequence of characters delimited with double-quotation marks.
Number 3330 An unsigned positive number.
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.
Currency "EUR" A currency as ISO 4217 Alpha 3, i.e. three uppercase letters.
Language "nl" A language as ISO 639-1 Alpha 2, i.e. two lowercase letters.
Country "NL" A country as ISO 3166-1 Alpha 2, i.e. two uppercase letters.
Url "https://testsecure..." A string containing an url starting with "http"

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

Reference Type Actual Type Format Description
merchant_key String UUID (36 characters) The merchant key as received after registering an account.
order_key String alpha-numeric (32 characters), all capitals The order key received after creating an order.
payment_identifier String alpha-numeric (14 characters), prefix 'pid', postfix 't' The payment identifier is received after starting a payment or when the shopper started a payment attempt in the menu.

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[] 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"