{

Orders

Create, list and query order details

Create a new order

Create a new order to be payed 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 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.

Response

Field Type M Description
order_key String M The generated order key.
url String 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

> 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"         : "johan.devries@docdatapayments.com",
        "language"      : "nl",
        "country"       : "BE"
    }'

< Http 201 Created
<    '{
        "order_key" : "F1499C097FFA533D46FB05D52680AB9A",
        "url"   : "https://testsecure.docdatapayments.com/ps/menu?command=show_payment_cluster&amp;merchant_name=testshop&amp;payment_cluster_key=F1499C097FFA533D46FB05D52680AB9A"
    }'

Returns a list of orders

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

The day to list the orders from is in the Amsterdam/Paris time zone (UTC+1).

This means that the timestamps in de response range from 23:00:00 the previous day until 23:00:00 the current 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 date 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 in seconds when the order was created. Formatted according ISO 8601 with timezone in UTC.
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",
            "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",
            "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 for 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 in seconds when the order was created. Formatted according ISO 8601 with timezone in UTC.
considered_safe 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 checkdigit id of the payment.
+ 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"             : "johan.devries@docdatapayments.com",
        "language"          : "nl",
        "country"           : "BE"
        "profile"           : "_default_",
        "timestamp"         : "2017-02-24T17:40:15Z",
        "considered_safe"   : {
            "level" : "SAFE"
        },
        "payments"  : [
            {
                "id"            : "2163179776",
                "method"        : "IDEAL",
                "authorization" : {
                    "amount"        : 3330,
                    "currency"      : "EUR",
                    "state"         : "CANCELED",
                    "reason"        : "Authorization request failed, received an error from iDeal."
                }
            },
            {
                "id"            : "2163179782",
                "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"
                    }
                ]
            }
        ]
    }'