Create, list and query order details
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". |
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:
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&merchant_name=testshop&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&merchant_name=testshop&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&merchant_name=testshop&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&merchant_name=testshop&payment_cluster_key=56058234D3F394FDF9956B02C3DEAE5C"
}'
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&merchant_name=testshop&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&merchant_name=testshop&payment_cluster_key=94D261BBF80E4AC7212B127D3BD2E279"
}
]'
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". |
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"
}
}
]
}'