Create, list and query order details
Create a new order to be paid by a shopper.
POST /ps/api/public/v1/merchants/{merchant_key}/ordersIdentifiers
| 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". |
| 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:
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&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 | 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&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 | 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". |
| 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"
}
]
}
]
}'