Create an order

Creating an order

Now that an access token has been provided, we are now able to create orders in the N-Genius Online gateway. To accept a payment from a customer, an order is always required so that we have something to interact with in all our API interactions with the gateway, and on the Portal user interface.

HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/[your-outlet-reference]/orders

Headers:

Add these headers to your request (note that you should replace 'access_token' with the access token value we received from the Obtain an access token step).

Header

Value

Authorization

Bearer access_token

Content-Type

application/vnd.ni-payment.v2+json

Accept

application/vnd.ni-payment.v2+json

Body:

Add the following JSON information to the form/body content of your request.

Parameter

Description

Example value

action

Order type

"AUTH", "SALE", "PURCHASE"

amount { }

Amount block

N/A

amount.currencyCode

Order currency

"AED", "USD", "EUR"

amount.value

Order amount

1000 (minor units)

emailAddress

Payer's email address

[email protected]

Note: these are the mandatory minimum input parameters for creating an order using the N-Genius Online gateway APIs - many more values are available. Please consult the List of order input attributes section for a complete list of these parameters.

📘

AUTH or PURCHASE?

Orders created with the ‘PURCHASE’ action will, if successfully authorized, automatically and immediately attempt to capture/settle the full order amount, whereas orders created with the ‘AUTH’ action will await some further action from instructing N-Genius Online to capture/settle the funds.

Unless you are ready to ship your goods/services immediately, or you are selling digital content, we recommend you use the ‘AUTH’ action and capture your customers’ successful authorizations when you are ready to ship the goods to your customer.

Example request (body):

{  
  "action": "PURCHASE",   
  "amount" : { "currencyCode" : "AED", "value" : 100 } 
}

Example response (body):

{
  "_id": "urn:order:76fb9d52-a3ef-42d3-8b4e-90092f57534c",
  "_links": {
    "cnp:payment-link": {
      "href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payment-link"
    },
    "payment-authorization": {
      "href": "https://<<apiSandboxDomain>>/transactions/paymentAuthorization"
    },
    "self": {
      "href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c"
    },
    "tenant-brand": {
      "href": "http://config-service/config/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/configs/tenant-brand"
    },
    "payment": {
      "href": "https://<<paypageSandboxDomain>>/?code=8ad2daf8bc86d0a9"
    },
    "merchant-brand": {
      "href": "http://config-service/config/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/configs/merchant-brand"
    }
  },
  "action": "PURCHASE",
  "amount": {
    "currencyCode": "AED",
    "value": 1000
  },
  "language": "en",
  "merchantAttributes": {
    "redirectUrl": "https://yoursite.com"
  },
  "emailAddress": "",
  "reference": "76fb9d52-a3ef-42d3-8b4e-90092f57534c",
  "outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
  "createDateTime": "2019-04-17T08:15:18.912Z",
  "paymentMethods": {
    "card": [
      "DINERS_CLUB_INTERNATIONAL",
      "AMERICAN_EXPRESS",
      "MASTERCARD",
      "MASTERCARD",
      "VISA",
      "VISA"
    ],
    "wallet": [
      "APPLE_PAY",
      "SAMSUNG_PAY"
    ]
  },
  "referrer": "urn:Ecom:76fb9d52-a3ef-42d3-8b4e-90092f57534c",
  "formattedAmount": "د.إ.‏ 10",
  "formattedOrderSummary": {},
  "_embedded": {
    "payment": [
      {
        "_id": "urn:payment:2fff837f-9a39-4a02-8435-9aaa7cb6b558",
        "_links": {
          "payment:apple_pay": {
            "href": "<<paymentUrl>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/apple-pay"
          },
          "self": {
            "href": "<<paymentUrl>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558"
          },
          "payment:card": {
            "href": "<<paymentUrl>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/card"
          },
          "payment:samsung_pay": {
            "href": "<<paymentUrl>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/samsung-pay"
          },
          "payment:saved-card": {
            "href": "<<paymentUrl>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/saved-card"
          },
          "curies": [
            {
              "name": "cnp",
              "href": "<<paymentUrl>>/docs/rels/{rel}",
              "templated": true
            }
          ]
        },
        "state": "STARTED",
        "amount": {
          "currencyCode": "AED",
          "value": 1000
        },
        "updateDateTime": "2019-04-17T08:15:18.912Z",
        "outletId": "5edab6d7-5946-43f4-b8c7-06b29c272bdd",
        "orderReference": "76fb9d52-a3ef-42d3-8b4e-90092f57534c"
      }
    ]
  }
}

Code example (PHP + cURL):

$postData = new StdClass();
$postData->action = "PURCHASE";
$postData->amount = new StdClass();
$postData->amount->currencyCode = "AED";
$postData->amount->value = 100;

$outlet = "[your-outlet-reference]";
$token = "[your-access-token]";

$json = json_encode($postData);
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "<<paymentUrl>>/transactions/outlets/".$outlet."/orders");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Authorization: Bearer ".$token, 
"Content-Type: application/vnd.ni-payment.v2+json",
"Accept: application/vnd.ni-payment.v2+json"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);

$output = json_decode(curl_exec($ch));
$order_reference = $output->reference;
$order_paypage_url = $output->_links->payment->href;

curl_close ($ch);

Note: you will require the order_paypage_url (hosted payment page URL) values for the following steps. It may also be beneficial for you to extract and hold the order_reference value.