The order object

In this section we will provide a full outline of the 'order' object, and an overview of the key elements and data blocks that comprise it.

Any order information you have provided when creating the order (see Create an order) will also be re-presented to you in this object.

Example (complete) order object:

{
  "_id": "urn:order:9662e6bd-729d-4ec9-b56b-391df748106c",
  "_links": {
    "self": {
      "href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/9662e6bd-729d-4ec9-b56b-391df748106c"
    },
    "tenant-brand": {
      "href": "http://config-service/config/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/configs/tenant-brand"
    },
    "merchant-brand": {
      "href": "http://config-service/config/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/configs/merchant-brand"
    }
  },
  "action": "PURCHASE",
  "amount": {
    "currencyCode": "AED",
    "value": 100
  },
  "language": "en",
  "merchantAttributes": {
    "redirectUrl": "https://yoursite.com/redirect"
  },
  "emailAddress": "[email protected]",
  "reference": "9662e6bd-729d-4ec9-b56b-391df748106c",
  "outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
  "createDateTime": "2019-04-17T11:53:21.195Z",
  "paymentMethods": {
    "card": [
      "DINERS_CLUB_INTERNATIONAL",
      "AMERICAN_EXPRESS",
      "MASTERCARD",
      "MASTERCARD",
      "VISA",
      "VISA"
    ],
    "wallet": [
      "SAMSUNG_PAY",
      "APPLE_PAY"
    ]
  },
  "referrer": "urn:Ecom:9662e6bd-729d-4ec9-b56b-391df748106c",
  "formattedAmount": "د.إ.‏ 1",
  "formattedOrderSummary": {},
  "_embedded": {
    "payment": [
      {
        "_id": "urn:payment:b63725f7-8205-42b8-829f-268c91922b28",
        "_links": {
          "cnp:capture": {
            "href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/9662e6bd-729d-4ec9-b56b-391df748106c/payments/b63725f7-8205-42b8-829f-268c91922b28/captures"
          },
          "self": {
            "href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/9662e6bd-729d-4ec9-b56b-391df748106c/payments/b63725f7-8205-42b8-829f-268c91922b28"
          },
          "cnp:cancel": {
            "href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/9662e6bd-729d-4ec9-b56b-391df748106c/payments/b63725f7-8205-42b8-829f-268c91922b28/cancel"
          },
          "curies": [
            {
              "name": "cnp",
              "href": "https://<<apiSandboxDomain>>/docs/rels/{rel}",
              "templated": true
            }
          ]
        },
        "paymentMethod": {
          "expiry": "2025-04",
          "cardholderName": "Test Customer",
          "name": "VISA",
          "pan": "401200******1112"
        },
        "savedCard": {
          "maskedPan": "401200******1112",
          "expiry": "2025-04",
          "cardholderName": "Test Customer",
          "scheme": "VISA",
          "cardToken": "dG9rZW5pemVkUGFuLy92MS8vU0hPV19OT05FLy9yYnJjdjRkaGV6YmEzaXZv"
        },
        "state": "AUTHORISED",
        "amount": {
          "currencyCode": "AED",
          "value": 100
        },
        "updateDateTime": "2019-04-17T11:55:12.336Z",
        "outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
        "orderReference": "9662e6bd-729d-4ec9-b56b-391df748106c",
        "authResponse": {
          "authorizationCode": "139537",
          "success": true,
          "resultCode": "00",
          "resultMessage": "Successful approval/completion or that VIP PIN verification is valid",
          "rrn": "01234567890"
        },
        "3ds": {
          "status": "SUCCESS"
        }
      }
    ]
  }
}

Key elements and their function

Below is a table representing the key (read: important) elements of the order object, which is returned to you whenever an order is queried or updated.

Element

Description

Comments

_id

URI for this order

May be useful for your records

_links

A block containing relevant, context-aware links

If the order is not yet paid, the payment page link will appear here

reference

The internal system reference for this order

This will always be unique

outletId

The outlet used to create this order

May be useful for your records

createDateTime

The date and time of order creation, for your records

UTC time format

paymentMethods

A block containing the payment methods available to this order

Depending on your configured payment methods, both cards, wallets and other payment methods will appear here

_embedded

A container block for child elements

Child elements will include any payment/transaction history related to this order.

_embedded child elements:

The _embedded element will contain an array of payment. In most cases, only one payment will be present. However, in some circumstances (i.e. recurring payments), this array will contain more than one payment per order.

An overview of the key payment object elements is below:

Element

Description

Comments

_id

URI for this order

May be useful for your records

_links

A block containing relevant, context-aware links

See below

_links.[cnp:capture].href

A capture link, allowing authorized funds to be captured

Will only be present if there are still funds remaining to be captured for this order

_links.[cnp:cancel].href

A cancellation link, allowing an authorization to be cancelled/reversed

Will only be present if the authorization was successful and no captures have been made against this order

_links.[cnp:refund].href

A refund link, allowing captures made before midnight the previous day to be refunded to the customer

Will only be present if th

authResponse elements

The authResponse block can be found in the _embedded.payment[x] block, and contains a number of data elements that may be useful for the interpretation of card transaction responses:

Element

Description

Comments

authorizationCode

If the authorization was successful, the value of this field will contain the authorization code for this transaction.

Example 012345

success

Indicates whether the transaction was successfully authorized or not

true / false

resultCode

Provides an ISO8583 standard result code for this transaction

Typically, a successful authorization will have a resultCode of 00

resultMessage

Provides a human readable message outlining a description of the given resultCode

N/A

rrn

A unique reference number for the transaction that will also be provided in any settlement reporting provided by your acquirer.

Example: 01234567890