Create, list and query order details.

Create 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	C	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 expires.
+ expire_after	Block	M	Specifies when the order expires.
+ + 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.

Notes on return url usage:

If a return url is not provided, then the default value configured on the account is used.
The order reference is added to the return url if it ends with an equal sign ('=') or a ('/') sign.
The return url may include multiple parameters that are replaced with order specific values.
The following parameters are supported:

Field	Type	Description
country	Country	The (billing) country of the shopper as ISO 3166-1 Alpha 2.
currency	Currency	The order currency as ISO 4217 Alpha 3, e.g. "EUR".
client_id	String(1, 50)	The id of the shopper.
order_key	OrderKey	The generated order key.
language	Language	The language of the shopper as ISO 639-1 Alpha 2.
merchant_name	String(1, 50)	The name of the merchant.
order_reference	String(1, 255)	The order reference from the merchant.

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=",
    	    "canceled" : "https://www.testshop.com/${merchant_name}/canceled?id=${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.
profile	String(1, 50)	M	The profile with payment methods (among other settings) used for this order. If not specified the profile "default" is used which contains all available payment methods.
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".
+ created_date	DateTime	M	The date when the payment started.
+ 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",
                "created_date"  : "2017-02-24T18:02:10Z",
                "authorization" : {
                    "amount"        : 3330,
                    "currency"      : "EUR",
                    "state"         : "CANCELED",
                    "reason"        : "Authorization request failed, received an error from iDeal."
                }
            },
            {
                "id"            : "pid2163179782t",
                "method"        : "SEPA_DIRECT_DEBIT"
                "created_date"  : "2017-02-24T18:03:46Z",
                "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"
                }
            }
        ]
    }'

List Payment Methods

Returns a list of all available payment methods of an order.

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

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

Array of:

Field	Type	M	Description
method	PaymentMethod	M	The payment method, e.g. IDEAL, BANCONTACT, SEPA_DIRECT_DEBIT or MASTERCARD.
bancontact_details	Block	C	The payment details for a Bancontact payment method. Only present when Bancontact Mobile QR is enabled.
+ qr_url	Url	M	The URL to the Bancontact Mobile QR image.
+ intent_url	Url	M	The URL for a Bancontact Mobile intent button; does not have to start with `http`.
ideal_details	Block	C	The payment details for an iDEAL payment method.
+ issuers	Block[]	M	The list of available issuing banks.
+ + id	Enum(50)	M	The id of the issuing bank, e.g. RABONL2U
+ + name	String(1, 255)	M	The name of the issuing bank, e.g. Rabobank.
+ qr_url	Url	O	The URL to the iDEAL QR image. Only present when IDeal QR is enabled.
sepa_direct_debit_details	Block	C	The payment details for an SEPA_DIRECT_DEBIT payment method.
+ mandates	Block[]	O	The list of active mandates for the shopper.
+ + id	String(1, 255)	M	The mandate id.
+ + type	Enum(16)	M	The type of mandate, i.e. ONE_OFF or RECURRING
+ + scheme	Enum(16)	M	The mandate scheme, i.e. CORE or B2B
google_pay_details	Block	C	The payment details for GOOGLE_PAY payment method.
+ server_url	Url	M	The URL to the Mobile Pay Server. The Url in example is not a full Url. For more details, check here.
+ merchant_country	Country	M	The country of the merchant.
+ gateway_id	String(64)	M	Payment Processor Id of CM.com as registered with Google.
+ environment	Enum(64)	M	The environment the Google Pay's client should use. For testing on lower environments, TEST should be used. For production, environment will be PRODUCTION.
+ merchant_id	String(64)	C	The Google merchant identifier issued by Google. Mandatory for production environment, but optional for other environments.
+ merchant_origin	String(255)	O	The fully qualified domain name of the merchant.
+ allowed_card_networks	String(1, 64)[]	M	The allowed card networks for Payment via Google Pay.
apple_pay_details	Block	C	The payment details for APPLE_PAY payment method.
+ server_url	Url	M	The URL to the Mobile Pay Server. The Url in example is not a full Url. For more detail, check here and or here.
+ merchant_country	Country	M	The country of the merchant.
+ supported_networks	String(1, 64)[]	M	The supported card networks for Payment via Apple Pay.

HTTP Status

Status	Meaning
200 (OK)	Success.
400 (Bad Request)	The request was not valid.
401 (Unauthorized)	Authorization header missing or invalid.
403 (Forbidden)	The merchant key is not allowed.
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/payments/methods
 
< Http 200 Ok
<    '[
        {
            "method" : "VISA"
        },
        {
            "method" : "MASTERCARD"
        },

        {
            "method" : "IDEAL",
            "ideal_details" : {
                "issuers"   : [
                    {
                        id   : "ABNA",
                        name : "ABN AMRO"
                    },
                    {
                        id   : "RABO",
                        name : "Rabobank"
                    },
                    {
                        id   : "INGB",
                        name : "ING"
                    }
                ],
                "qr_url"        : "https://qrcode.ideal.nl/codes/5d6b159b-41ab-48eb-b379-da18ddea06d"
            }
        },
        {
            "method" : "BANCONTACT",
            "bancontact_details"    : {
                "qr_url"    : "https://testtma-assets.docdatapayments.com/qr?data=BEP%3A%2F%2F1TESTTMA.DOCDATAPAYMENTS.COM%2FBEP%24QLI7W4RDFDZMH4Z5FCAJ7DZV",
                "intent_url"    : "bepgenapp://DoTx?TransId=1TESTTMA.DOCDATAPAYMENTS.COM/BEP$QLI7W4RDFDZMH4Z5FCAJ7DZV"
            }
        },
        {
            "method" : "SEPA_DIRECT_DEBIT",
            "sepa_direct_debit_details" : {
                "mandates"  : [
                    {
                        id      : "ps-sim-1575466412104",
                        type    : "ONE_OFF",
                        scheme  : "CORE"
                    }
                ],
            }
        },
        {
            "method": "APPLE_PAY",
            "apple_pay_details": {
                "server_url": "https://testsecure.docdatapayments.com:8484",
                "merchant_country": "NL",
                "supported_networks": [
                    "visa",
                    "masterCard"
                ]
            }
        },
        {
            "method": "GOOGLE_PAY",
            "google_pay_details": {
                 "server_url": "https://testsecure.docdatapayments.com:8484",
                 "merchant_country": "NL",
                 "gateway_id": "example",
                 "environment": "TEST",
                 "merchant_id": "default",
                 "merchant_origin": "www.example.com",
                 "allowed_card_networks": [
                     "MASTERCARD",
                     "VISA"
                  ]
             }
        }
    ]'