{

Orders

Create, list and query order details

Create a new order

Create a new order to be paid by a shopper.

POST /ps/api/public/v1/merchants/{merchant_key}/orders

Identifiers

Name Description
merchant_key The key of the merchant.

Parameters

Not applicable.

Request

Field Type M Description
order_reference String M The order reference from the merchant.
description String M A description of the order that can be shown to the shopper.
amount Number M The order amount in minor units, e.g. in cents.
currency Currency M The order currency as ISO 4217 Alpha 3, e.g. "EUR".
email String O The email address of the shopper. Mandatory if billing_address_key is not provided, ignored otherwise.
language Language M The language of the shopper as ISO 639-1 Alpha 2. Used for the menu and emails.
country Country O The shopper country as ISO 3166-1 Alpha 2. Needed to control the availability of payment methods in the menu. Some payment methods are only available for specific countries. Mandatory if billing_address_key is not provided, ignored otherwise.
profile String O The profile with payment methods (among other setting) to be used for this order. If not specified all available (and applicable) payment methods for the merchant are used.
billing_address_key String O The address key of the shopper for the billing address.
expiry Block O Specifies when the order should expire.
+ expire_after Block M Specifies that the order must expire after a specified amount of time.
+ + unit String M The unit of the expire after duration. Valid values are 'MINUTES', 'HOURS', or 'DAYS'.
+ + duration String M The duration or amount of the expire after. The value is added to the create timestamp, after converting it to minutes. The duration cannot exceed 21 24 60 minutes.
_returnurls Block O Contains the return urls for the shopper.
+ success Url O The url the shoppers returns to when the order is successfully authorizes.
+ pending Url O The url the shoppers returns to when the result of the authorization is not known yet.
+ canceled Url O The url the shoppers returns to when the order was canceled.
+ error Url O The url the shoppers returns to when the order could not be processed.

Note on return url usage:

  • If a return url is not provided, then the default values configured on the account is used.
  • The order reference is added to the return url if it ends with an equal sign ('=').

Response

Field Type M Description
order_key String M The generated order key.
expires_on DateTime M The date and time when the order expires.
url Url C The url to the menu.

HTTP Status

Status Meaning
201 (Created) The order is successfully created.
400 (Bad Request) The request was not valid.
401 (Unauthorized) Authorization header missing or invalid.
403 (Forbidden) The merchant key is not allowed.
405 (Conflict) The new reference was not unique.

Create Order example The order is created on 2020-01-01 19:00.

> 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 '{
        "order_reference"   : "vk20170224p",
        "description"   : "Order 12345",
        "amount"        : 3330,
        "currency"      : "EUR",
        "email"         : "[email protected]",
        "language"      : "nl",
        "country"       : "BE"
    }'

< Http 201 Created
<    '{
        "order_key" : "F1499C097FFA533D46FB05D52680AB9A",
        "expires_on" : "2020-01-31T19:00:12Z",
        "url"   : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=F1499C097FFA533D46FB05D52680AB9A"
    }'

Create Order example with explicit expiry defined The order is created on 2020-01-01 19:00.

> 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 '{
        "order_reference"   : "vk20170224p_expire_soon",
        "description"   : "Order 12346",
        "amount"        : 1000,
        "currency"      : "EUR",
        "email"         : "[email protected]",
        "language"      : "nl",
        "country"       : "NL",
        "profile"       : "all",
        "expiry"        : {
            "expire_after" : {
                "unit"     : "DAYS",
                "duration" : 1
            }
        }
    }'

< Http 201 Created
<    '{
        "order_key" : "F1499C097FFA533D46FB05D52680AB9A",
        "expires_on" : "2020-01-02T19:00:00Z",
        "url"   : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=F1499C097FFA533D46FB05D52680AB9A"
    }'

Create Order example with return urls defined

> 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 '{
        "order_reference"   : "vk20170224p_expire_soon",
        "description"   : "Order 12346",
        "amount"        : 1000,
        "currency"      : "EUR",
        "email"         : "[email protected]",
        "language"      : "nl",
        "country"       : "NL",
        "return_urls"        : {
            "success" : "https://www.testshop.com/returnSuccess?id=12345&order_reference=" 
        }
    }'

< Http 201 Created
<    '{
        "order_key" : "F1499C097FFA533D46FB05D52680AB9A",
        "expires_on" : "2020-01-02T19:00:00Z",
        "url"   : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=F1499C097FFA533D46FB05D52680AB9A"
    }'

Create Order example with billing address key

> 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 '{
        "order_reference"       : "vk20170224p",
        "description"           : "Order 12345",
        "amount"                : 1000,
        "currency"              : "EUR",
        "language"              : "nl",
        "profile"               : "all-af",
        "billing_address_key"   : "4905560f-f83e-497d-a1cf-616d2cdbcf76"
    }'

< Http 201 Created
<    '{
        "order_key" : "56058234D3F394FDF9956B02C3DEAE5C",
        "expires_on" : "2020-09-14T14:42:35Z",
        "url"   : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=56058234D3F394FDF9956B02C3DEAE5C"
    }'

Returns a list of orders

Returns a list of all orders created on a specific day.

GET /ps/api/public/v1/merchants/{merchant_key}/orders?[date={date}]

Identifiers

Name Description
merchant_key The key of the merchant.

Parameters

Name Format M Description
date Date O The day to list the orders from as yyyy-mm-dd. If not specified the current day is used.

Request

Not applicable.

Response

Array of:

Field Type M Description
order_reference String M The order reference from the merchant.
timestamp DateTime M The date and time when the order was created.
expires_on DateTime M The date and time when the order expires.
order_key String M The order key.
url String C The url to the menu.

HTTP Status

Status Meaning
200 (OK) Success.
400 (Bad Request) The data parameter is not a valid date.
401 (Unauthorized) Authorization header missing or invalid.
403 (Forbidden) The merchant key is not allowed.

List Orders example

> curl \
    -X GET \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders?date=2017-02-24

< Http 200 Ok
<    '[
        {
            "order_reference"   : "vk20170224p",
            "timestamp"         : "2017-02-24T17:08:43Z",
            "expires_on"        : "2017-03-24T17:08:43Z",
            "order_key"         : "F1499C097FFA533D46FB05D52680AB9A",
            "url"               : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=F1499C097FFA533D46FB05D52680AB9A"
        },
        {
            "order_reference"   : "vk20170224q",
            "timestamp"         : "2017-02-24T17:40:15Z",
            "expires_on"        : "2017-03-24T17:08:43Z",
            "order_key"         : "94D261BBF80E4AC7212B127D3BD2E279",
            "url"               : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=94D261BBF80E4AC7212B127D3BD2E279"
        }
    ]'

Return details of order

Returns the details of an order including the status

GET /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}

Identifiers

Name Description
merchant_key The key of the merchant.
order_key The key of the order.

Parameters

Not applicable.

Request

Not applicable.

Response

Field Type M Description
order_reference String M The order reference from the merchant.
description String M A description of the order that can be shown to the shopper.
amount Number M The order amount in minor units, e.g. in cents.
currency Currency M The order currency as ISO 4217 Alpha 3, e.g. "EUR".
email String M The email address of the shopper.
language Language M The language of the shopper as ISO 639-1 Alpha 2. Used for the menu and emails.
country Country M The shopper country as ISO 3166-1 Alpha 2. Needed for switching platform. No payment method filtering if not present.
profile String M The profile with payment methods (among other setting) to be used for this order. If not specified the profile "default" is used which contains all available payment methods for the merchant.
timestamp DateTime M The date and time when the order was created.
expires_on DateTime M The date and time when the order expires.
_consideredsafe Block C The considered safe result. Only available when the order is considered safe.
+ level String M The considered safe level for the order: "FASTEST", "FAST", "SAFE" or "SAFEST".
+ timestamp DateTime M The date and time in seconds when the order was considered safe. Formatted according ISO 8601 with timezone in UTC.
payments Block[] O A list of payment (attempts) on this order.
+ id String M The payment identifier.
+ method String M The payment method, e.g. "IDEAL" or "SEPA_DIRECT_DEBIT".
+ authorization Block M The authorization details.
+ + amount Number M The authorized amount in minor units, e.g. in cents.
+ + currency Currency M The authorized currency as ISO 4217 Alpha 3, e.g. "EUR".
+ + confidence String C The confidence level, i.e. ACQUIRER_APPROVED, ACQUIRER_PENDING or SHOPPER_PENDING. Only available when the status is "AUTHORIZED".
+ + state String M The status of the authorization.
+ + reason String O The reason of the authorization status.
+ captures Block[] O The capture details.
+ + amount Number M The capture amount in minor units, e.g. in cents.
+ + currency Currency M The capture currency as ISO 4217 Alpha 3, e.g. "EUR".
+ + state String M The status of the capture.
+ + reason String O The reason of the capture status.
+ refunds Block[] O The refund details.
+ + amount Number M The refund amount in minor units, e.g. in cents.
+ + currency Currency M The refund currency as ISO 4217 Alpha 3, e.g. "EUR".
+ + state String M The status of the refund.
+ + reason String O The reason of the refund status.
+ chargebacks Block[] O The chargeback details.
+ + amount Number M The chargeback amount in minor units, e.g. in cents.
+ + currency Currency M The chargeback currency as ISO 4217 Alpha 3, e.g. "EUR".
+ + state String M The status of the chargeback.
+ + reason String O The reason of the chargeback.

HTTP Status

Status Meaning
200 (OK) Success.
404 (Not Found) The order key was not found.

Order Details example

> curl \
    -X GET \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/94D261BBF80E4AC7212B127D3BD2E279

< Http 200 Ok
<    '{
        "order_reference"   : "vk20170224p",
        "description"       : "Order 12345",
        "amount"            : 3330,
        "currency"          : "EUR",
        "email"             : "[email protected]",
        "language"          : "nl",
        "country"           : "BE"
        "profile"           : "_default_",
        "timestamp"         : "2017-02-24T17:40:15Z",
        "expires_on"        : "2017-03-24T17:40:15Z",
        "considered_safe"   : {
            "level" : "SAFE"
        },
        "payments"  : [
            {
                "id"            : "pid2163179776t",
                "method"        : "IDEAL",
                "authorization" : {
                    "amount"        : 3330,
                    "currency"      : "EUR",
                    "state"         : "CANCELED",
                    "reason"        : "Authorization request failed, received an error from iDeal."
                }
            },
            {
                "id"            : "pid2163179782t",
                "method"        : "SEPA_DIRECT_DEBIT"
                "authorization" : {
                    "amount"        : 3330,
                    "currency"      : "EUR",
                    "confidence"    : "ACQUIRER_PENDING",
                    "state"         : "AUTHORIZED"
                },
                "captures"      : [
                    {
                        "amount"        : 3330,
                        "currency"      : "EUR",
                        "state"         : "CAPTURED"
                    }
                ],
                "refunds"       : [
                    {
                        "amount"        : 1000,
                        "currency"      : "EUR",
                        "state"         : "NEW"
                    }
                ],
                "chargebacks"   : [
                    {
                        "amount"        : 3330,
                        "currency"      : "EUR",
                        "state"         : "CHARGED",
                        "reason"        : "AC06 Account blocked"
                    }
                ]
            }
        ]
    }'