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.

ElementDescriptionComments
_idURI for this orderMay be useful for your records
_linksA block containing relevant, context-aware linksIf the order is not yet paid, the payment page link will appear here
referenceThe internal system reference for this orderThis will always be unique
outletIdThe outlet used to create this orderMay be useful for your records
createDateTimeThe date and time of order creation, for your recordsUTC time format
paymentMethodsA block containing the payment methods available to this orderDepending on your configured payment methods, both cards, wallets and other payment methods will appear here
_embeddedA container block for child elementsChild 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:

ElementDescriptionComments
_idURI for this orderMay be useful for your records
_linksA block containing relevant, context-aware linksSee below
_links.[cnp:capture].hrefA capture link, allowing authorized funds to be capturedWill only be present if there are still funds remaining to be captured for this order
_links.[cnp:cancel].hrefA cancellation link, allowing an authorization to be cancelled/reversedWill only be present if the authorization was successful and no captures have been made against this order
_links.[cnp:refund].hrefA refund link, allowing captures made before midnight the previous day to be refunded to the customerWill 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:

ElementDescriptionComments
authorizationCodeIf the authorization was successful, the value of this field will contain the authorization code for this transaction.Example 012345
successIndicates whether the transaction was successfully authorized or nottrue / false
resultCodeProvides an ISO8583 standard result code for this transactionTypically, a successful authorization will have a resultCode of 00
resultMessageProvides a human readable message outlining a description of the given resultCodeN/A
rrnA unique reference number for the transaction that will also be provided in any settlement reporting provided by your acquirer.Example: 01234567890