This is an optional API that can be used to query the Order Status
Overview
The Order Status API allows the Partner to query the status of their order after calling the Order Completion API. This API is optional and the preferred way of processing is via Configuring Webhooks
Pre Requisites
- An access token needs to be generated in order to use this API (see Authentication - Generate Access Token)
API Description
Headers
| Header | Description/Value |
|---|---|
| AccessToken | This is the Access Token field returned from the Authentication - Generate Access Token response. This should be in the format Bearer <AccessToken> |
| Content-Type | application/vnd.carry1st.order.distributor+json |
URL Format
To retrieve a list of available payment methods, make a GET request to the following endpoint:
- GET /api/orders/distributors/order-status?reference=?&externalReference=?&showCodes=?
List of URL Query Parameters
| Parameter | Format | Mandatory | Description |
|---|---|---|---|
| reference | String | Y | This is the Carry1st reference received in the Complete Order Request |
| externalReference | String | Y | This is the Partner's externalReference. One of externalReference or reference fields needs to be populated |
| showCodes | String | N | If set to true, then the response will also display the voucher codes for the order. If absent, this is set to falseby default |
Response
The API will respond with a JSON object.
{
"reference": "C-1239884379-P",
"externalReference": "EXT-87456321",
"productBundleSku": "BUNDLE-SKU-001",
"quantity": 1,
"recipientIdentifier": "USER-998877",
"email": "[email protected]",
"voucherCodes": [
[
{
"label": "Code",
"value": "444100070555"
}
]
],
"status": "PENDING"
}Order Fields
| Name | Type | Mandatory | Description |
|---|---|---|---|
| reference | String | Y | The recipientIdentifier that was sent in the response of the Complete Order Request |
| externalReference | Number | Y | The externalReference that was sent in the Complete Order Request |
| quantity | Number | Y | The quantity that was sent in the Complete Order Request |
| recipientIdentifier | String | Y | The recipientIdentifier that was sent in the Complete Order Request |
| String | Y | The email that was sent in the Complete Order Request | |
| voucherCodes | Array of VoucherCode | N | If the product in the order is a voucher based product (i.e. it requires voucher codes), then this webhook will return the codes as a list of VoucherCode objects equal to the quantity of VoucherCodes requested for the product |
| status | String | Y | The status of an order. Possible values:
|
VoucherCode Fields
| Name | Type | Mandatory | Description |
|---|---|---|---|
| VoucherCode | Array of VoucherCodeProperty | Y | This is a list of VoucherCodeProperty objects that make up the voucher code. All VoucherCodeProperty objects combined represent one VoucherCode. |
VoucherCodeProperty Fields
Partners need to assume that VoucherCodeProperty objects will be different per product as each product uses a different set of properties for their codes.
| Name | Type | Mandatory | Description |
|---|---|---|---|
| label | String | Y | This is the name of the voucher code property (e.g. PIN, Code, etc.) |
| value | String | Y | This is the actual value of the property |
HTTP Response Codes
The User Validation API may return the following HTTP Response Codes:
| HTTP Status Code | Name | Description |
|---|---|---|
| 200 | Success | This indicates that the request has been successful |
| 400 | Bad Request | The externalReference or reference could be invalid or missing from the request |
| 401 | Unauthorized | The Access Token might be missing or invalid (see Authentication - Generate Access Token) |
| 403 | Forbidden | The credentials provided might not have access to the resources required |
Error Handling
See Handling Error Codes for more details on handling error responses.