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
POST /ps/api/public/v1/merchants/{merchant_key}/subscriptions/{subscription_reference}/orders

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
subscription_reference String(1, 255) The subscription reference from the merchant.

Parameters

Not applicable.

Request

Field Type M Description
order_reference String(1, 255) M The order reference from the merchant.
description String(1, 255) M A description of the order that can be shown to the shopper.
amount Amount 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(1, 200) 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(1, 50) 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 AddressKey O The address key, as returned by the 'create shopper'-request, 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 Enum(16) M The unit of the duration. Valid values are 'MINUTES', 'HOURS', or 'DAYS'.
+ + duration Number(1, 30240) M The duration after which the order expires. The value is added to the create timestamp, after converting it to minutes.
return_urls 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 OrderKey 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 Type Description
merchant_key MerchantKey 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(1, 255) 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 OrderKey M The order key.
url Url 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 Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

Not applicable.

Response

Field Type M Description
order_reference String(1, 255) M The order reference from the merchant.
description String(1, 255) M A description of the order that can be shown to the shopper.
amount Amount 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(1, 200) 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(1, 50) 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.
considered_safe Block C The considered safe result. Only available when the order is considered safe.
+ level Enum(16) M The considered safe level for the order.
+ 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 PaymentIdentifier M The payment identifier.
+ method PaymentMethod M The payment method, e.g. "IDEAL" or "SEPA_DIRECT_DEBIT".
+ authorization Block M The authorization details.
+ + amount Amount 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 Enum(32) C The confidence level, i.e. ACQUIRER_APPROVED, ACQUIRER_PENDING or SHOPPER_PENDING. Only available when the status is "AUTHORIZED".
+ + state Enum(32) M The status of the authorization.
+ + reason String(1, 255) O The reason of the authorization status.
+ receipt Block[] O The receipts for POINT_OF_SALE payments.
+ + shopper_receipt String(1, 2048) O The receipt for the shopper.
+ + merchant_receipt String(1, 2048) O The receipt for the merchant, which must be signed by the shopper.
+ captures Block[] O The capture details.
+ + amount Amount 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 Enum(32) M The status of the capture.
+ + reason String(1, 255) O The reason of the capture status.
+ + date_last_modified DateTime M The date the state has last been modified.
+ refunds Block[] O The refund details.
+ + amount Amount 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 Enum(32) M The status of the refund.
+ + reason String(1, 255) O The reason of the refund status.
+ + date_last_modified DateTime M The date the state has last been modified.
+ chargebacks Block[] O The chargeback details.
+ + amount Amount 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 Enum(32) M The status of the chargeback.
+ + reason String(1, 255) O The reason of the chargeback.
+ + chargeback_date DateTime M The date of the chargeback according to acquirer.
+ shopper_bank_account Block O The shopper bank account information. This is only shown after agreement with CM Payments.
+ + name String(1, 255) O The consumer account holder name.
+ + iban String(5, 34) M The consumer international bank account number.
+ + bic String(8, 11) O The bank identification code of iban.

The Considered Safe Level can have one of the following possible values:

Level Description
FASTEST All orders with a successful authorization are considered safe. This includes bank transfer, for which shoppers still have to transfer the money.
FAST Consider all orders safe in which the initiative is at an acquirer. E.g. a direct debit authorization which has passed checks but is not yet confirmed by the acquirer.
SAFE The payment is successfully captured or it is an acquirer approved authorizations (e.g. credit cards do not require a capture to be considered safe).
SAFEST The payment is successfully captured and there are no chargebacks expected anymore when checking the status with the exception of credit cards.

Captures and refunds can have one of the following states:

State Description
NEW Initial state.
STARTED Capture or refund is requested and/or grouped in a batch.
CAPTURED Capture or refund is processed successfully.
CANCELED, The capture or refund has been revoked manually.
FAILED, The capture or refund was processed but declined.
ERROR The capture or refund process failed due to an error.
ERROR_RETRY The capture or refund process failed due to an error and will be retried.

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",
                        "modified_date" : "2020-10-29T16:28:52.596+01:00" 
                    }
                ],
                "refunds"       : [
                    {
                        "amount"        : 1000,
                        "currency"      : "EUR",
                        "state"         : "NEW",
                        "modified_date" : "2020-10-29T16:30:14.283+01:00" 
                    }
                ],
                "chargebacks"   : [
                    {
                        "amount"          : 3330,
                        "currency"        : "EUR",
                        "state"           : "CHARGED",
                        "reason"          : "AC06 Account blocked",
                        "chargeback_date" : "2020-10-29T16:34:50.593+01:00"
                    }
                ]
                "shopper_bank_account"   : {
                    "name"        : "Onderheuvel",
                    "iban"        : "NL44RABO0123456789",
                    "bic"         : "RABONL2U"
                }
            }
        ]
    }'