Order
Our Order API endpoints provide a secure and efficient solution for managing ecommerce transactions. They allow for the storage and retrieval of order details, generation of orders, and facilitate updates to orders, aiding smooth operations for merchants and their connected systems.
info
- Authentication required: These endpoints require authentication. To learn how to authenticate, see our authentication documentation.
- Sample requests & responses: To test these endpoints with sample requests, use our Postman collection
- Swagger file: To view definitions for these endpoints, see our swagger file
POST Order
Securely stores order_details, and returns an order_token. This endpoint does not perform validation, only storage/vaulting.
You can use /charge?action = validate if you want these order_details validated by the vault or a connected business system.
Endpoint
/order_token
Required request fields
| Field | Type | Description |
|---|---|---|
order_request.details_format | string (enum) | Format discriminator for the order details payload. Currently the only supported value is details. |
order_request.order_details.order.service_id | string (UUID) | Identifier for your merchant service. Provided during onboarding and shown as Token on the Merchant Dashboard's Payment Configuration page. |
order_request.order_details.order.order_amount.value | integer | Order amount in minor units (for example, 100000 represents 1,000.00 in the order currency). |
order_request.order_details.order.order_amount.currency.currency_code | string | ISO 4217 currency code (for example, IDR, INR, AUD). |
order_request.order_details.order.customer | object | Payer details — see the Entity endpoint for the supported fields. |
Sample Messages
Sample Request
{
"order_request": {
"details_format": "details",
"order_details": {
"order": {
"service_id": "{{service_id}}",
"order_amount": {
"value": 4000,
"currency": {
"currency_code": "IDR"
}
},
"customer": {
"entity_type": "person",
"details_format": "details",
"entity_details": {
"addresses": [
{
"type": "billing",
"details": {
"line_1": "test 1",
"line_2": "test2",
"city": "Mumbai",
"country": "IN",
"postal_code": "40001",
"state_region_province": "MH"
}
}
],
"email": "companyinfo@email.com",
"name": {
"first": "Jim",
"last": "Jones"
},
"phone_number": {
"type": "mobile",
"details": {
"unformatted_number": "+61555555555"
}
}
}
},
"your_order_details": [
{
"key": "hpp_post_code",
"value": "12345"
},
{
"key": "merchant_order_ref",
"value": "<<merchant defined custom value>>"
},
{
"key": "merchant_customer_ref",
"value": "<<merchant defined custom value>>"
}
]
}
}
}
}
Sample Response
{
"order_id": "955a26a3-aaaa-4fb9-a38e-439a804628b9",
"service_id": "6cf4a729-cb4f-4e60-8bee-3dee0f7b7a4f",
"order_amount": {
"value": 4000,
"currency": {
"currency_code": "INR"
}
},
"customer": {
"entity_id": "eed37ecd-90e3-4744-b6bf-ebdf5f4eba75",
"your_entity_reference": "",
"entity_type": "person",
"entity_details": {
"name": {
"first": "",
"middle": "",
"last": "",
"suffix": "",
"prefix": "",
"full_name": "Company Name"
},
"addresses": null,
"email": "companyinfo@email.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "",
"unformatted_number": "+913852543512",
"formatted_number": ""
},
"your_phone_number_reference": ""
}
}
},
"your_order_reference": "",
"order_line_items": []
}
GET Order Details
Returns the details of an order.
Endpoint
/order_token/{order_token}
Parameters
| Name | Value | Required | Explanation |
|---|---|---|---|
| order_token | {order_token} | Yes | A unique reference to an order |
Sample Messages
Sample Response
{
"order_id": "11d4a0d5-34ed-4193-8cde-a19e591a736a",
"service_id": "e3fa2406-30a4-4c67-825f-a968710c7016",
"order_amount": {
"value": 4000,
"currency": {
"currency_code": "INR"
}
},
"customer": {
"entity_id": "afc84ddc-706e-4515-828f-4d913360cb13",
"your_entity_reference": "",
"entity_type": "person",
"entity_details": {
"name": {
"first": "",
"middle": "",
"last": "",
"suffix": "",
"prefix": "",
"full_name": "Company Name"
},
"addresses": [
{
"type": "shipping",
"details": {
"line_1": "Suite 1, Level 29/100 Barangaroo Ave",
"line_2": "",
"line_3": "",
"postal_code": "2000",
"city": "Barangaroo",
"state_region_province": "NSW",
"country": "AU",
"your_address_reference": ""
}
}
],
"email": "companyinfo@email.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "61",
"unformatted_number": "490000000",
"formatted_number": "0490000000"
},
"your_phone_number_reference": ""
}
}
},
"your_order_reference": "",
"order_line_items": []
}
POST Update Order
Updates details of an order.
Endpoint
/order_token/\{order_token\}
Parameters
| Name | Value | Required | Explanation |
|---|---|---|---|
| order_token | {order_token} | Yes | A unique reference to an order |
Sample Messages
Sample Request
{
"entity_type": "person",
"details_format": "details",
"entity_details": {
"name": {
"first": "NewFirstName",
"middle": "",
"last": "Roger",
"suffix": "",
"prefix": ""
},
"addresses": [
{
"type": "billing",
"details": {
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"city": "Richardson",
"state_region_province": "TX",
"country": "US",
"your_address_reference": "string"
}
}
],
"email": "user@example.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "IR",
"unformatted_number": "123456789",
"formatted_number": "333"
},
"your_phone_number_reference": "string"
}
}
}
Sample Response
{
"entity_id": "6ef9c24e-55ce-4212-8112-bf410c0e0d04",
"your_entity_reference": "",
"entity_type": "details",
"entity_details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "NewFirstName",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "IR",
"formatted_number": "333",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
}
}
HTTP Response Codes
Below is a table summarizing the various HTTP response codes and their descriptions.
| HTTP Status Code | Response Schema | Description |
|---|---|---|
| 200 | Charge | The charge response provides the status of the most recent charge event and ledger balances and tokens for the payment, order, and settlement (if available). |
| 201 | Charge Pending | The pending charge response provides the pending status of the most recent charge event. |
| 202 | Charge Money Error | The money error charge response provides error information about the most recent charge event, which had a money error. Please review the error fields to determine how to resolve this error. |
| 203 | Charge Connectivity Error | The connector error charge response provides error information about the most recent charge event, which had a connector error. Please review the error fields to determine how to resolve this error. |
| 211 | Charge Data Error | The charge error response provides error information and the status of the charge as well as balances for the payment, order, and settlement (if available) ledgers. Also provided are the token references for the associated payment, order, session, and entity tokens. |
| 400 | Charge Request Error | The request error charge response provides error information about the most recent API request, which contained a schema error. Please review the error fields to determine how to resolve this error. |
| 500 | System Error | An error occurred either within /charge or externally in a system Connected to /charge. Please notify DMG via ecomm@datameshgroup.com. |