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

Response

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