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.