With two stage payments, orders are first created, then supplied with payment information in two separate steps. This approach can be useful when you have received an order for goods/services, but need to collect payment at a later time or date.
If you plan to collect payment at the same time as creating the order, please refer to the One stage payments section instead.
Create 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 mandatory 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] |
| billingAddress { } | Billing address block | N/A |
| billingAddress.firstName | Payer's first name | mandatory |
| billingAddress.lastName | Payer's last/second name | mandatory |
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": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/apple-pay"
},
"self": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558"
},
"payment:card": {
"href": "https://<<apiSandboxDomain>>/transactions/outlets/5edab6d7-5946-43f4-b8c7-06b29c272bdd/orders/76fb9d52-a3ef-42d3-8b4e-90092f57534c/payments/2fff837f-9a39-4a02-8435-9aaa7cb6b558/card"
},
"payment:samsung_pay": {
"href": "https://<<apiSandboxDomain>>/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": "https://<<apiSandboxDomain>>/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": "https://<<apiSandboxDomain>>/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"
}
]
}
}
Submit payment card information
At this stage, it is expected that you be capturing the PAN, expiry date, card security code (CVV/CSC) of the payer’s card on your site/service.
The following method describes how these details will be passed to the N-Genius Online transaction service for insertion into the order we just created.
HTTP Request Method: PUT
Resource (URI): https://api-gateway.sandbox.ngenius-payments.com/transactions/outlets/[your-outlet-reference]/orders/[your-order-reference]/payments/[your-payment-reference]/card *
Constructing the card payment URL
The resource above need not be constructed yourself. Instead, once an order has been created, you can extract this from the order response (above) from the attribute below:
_embedded.payment[0]._links.[payment:card].href
Headers:
Add these headers to your request:
| 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.
| Attribute | Description | Possible value(s) |
|---|---|---|
| pan | The PAN (longest number) on the card | 4111111111111111 |
| expiry | Card expiry date (YYYY-MM) | 2025-04 |
| cvv | The payment card’s security code | 123 |
| cardholderName | The name of the card-holder | John Brown |
Example request (body):
{
"pan": "411111111111111111111",
"expiry": "2021-06",
"cvv": "123",
"cardholderName": "John Brown"
}
Example response (body):
{
"_id": "urn:payment:b9040ddd-3b2c-4873-8099-889815b37352",
"_links": {
"self": {
"href": "[self-urn]"
},
"curies": [
{
"name": "cnp",
"href": "https://<<apiDomain>>/docs/rels/{rel}",
"templated": true
}
]
},
"paymentMethod": {
"expiry": "2021-06",
"cardholderName": "John Brown",
"name": "VISA",
"pan": "411111******1111",
"cvv": "***"
},
"outletId": "94223ab2-5bb9-467f-a6a7-fc4b22c435af",
"orderReference": "ceb2dad7-ec1e-4ab2-9a3a-75f99d17a166",
"state": "AWAIT_3DS",
"amount": {
"currencyCode": "AED",
"value": 100
},
"updateDateTime": "2019-02-05T10:15:18.810Z",
"authResponse": {
"authorizationCode": "1234567",
"success": true
}
}
Code example (PHP + cURL):
$postData = new StdClass();
$postData->pan = $pan;
$postData->expiry = $expiry;
$postData->cvv = $cvv;
$postData->cardholderName = $name;
$json = json_encode($postData);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $cardpay_url);
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);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
$output = json_decode(curl_exec($ch));
$state = $output->state;
if ($state == "AWAIT_3DS") {
$cnp3ds_url = $output->_links->{'cnp:3ds'}->href;
$acsurl = $output->{'3ds'}->acsUrl;
$acspareq = $output->{'3ds'}->acsPaReq;
$acsmd = $output->{'3ds'}->acsMd;
$acsterm = "https://[your-post-3ds-script]";
}
curl_close ($ch);
The 'state' attribute
The primary attribute of the response received (above) we should concern ourselves with is the state attribute, which determines what your next action should be in the card payment processing journey using N-Genius Online.
The possible values of the 'state' attribute are as follows:
| State | Description and next steps |
|---|---|
| STARTED | Order has been created |
| AUTHORISED | Authorization of the payment has been successful but you will need to capture the payment before funds will be transferred. |
| PURCHASED | The payment has been purchased successfully. No further action is required. This is the typical ‘state’ outcome for a payment made using the ‘PURCHASE’ action (see the order creation step). |
| CAPTURED | The payment has been authorized and captured successfully. No further action is required. This is the typical ‘state’ outcome for a payment made using the ‘SALE’ action (see the order creation step). |
| AWAIT_3DS | A further step, to invoke and manage the 3-D Secure process is required before an authorization attempt will be made. If you have 3-D Secure enabled on your N-Genius Online account, this is a very common outcome. See Step 2 (Process 3-D Secure challenge) for the next steps. |
| FAILED | The payment has not been successful. You should ask the customer to retry using either the same payment card, or a different one. |
Fraud Screening
Please go to https://docs.ngenius-payments.com/docs/fraud-screening to know more about the fraud screening capabilities
It is important, if you are registered for enhanced screening, that when a transaction is Fraud Checked with a status of rejected, you do not deliver the goods or services. To avoid card-holder impact, the Ngenius platform will automatically initiate an Authorization Reversal, to remove the shadow from the cardholders account and release their funds.
Note that, for most card transactions, the most common value of the 'state' attribute will be 'AWAIT_3DS', which infers that the 3-D Secure authentication challenge must now be processed. Since this is a direct integration, it is expected that you will process this challenge yourself, as outlined below.
Process 3-D Secure challenge
3DS 1.x will no longer be supported from October 2022
Customers integrating with N-Genius Online should be aware that all card schemes will be decommissioning support for the 1.x protocol of 3-D Secure from October 2022. As such, merchants are advised to follow the EMV 3DS (3DS 2.x) integration guidelines found here: EMV 3DS (3DS 2.X) Integration
The following sub-steps are required to facilitate and manage the 3-D Secure challenge process.
Step 1: Invoke or redirect with attributes received from step above (submit payment card information). These attributes are:
| 3-D Secure attribute | Function / description |
|---|---|
| 3ds.acsurl | The URL of the issuer’s challenge page |
| 3ds.acsPaReq | The [P]ayer [A]uthentication [Req]uest value required by the issuer for providing the challenge to your card-holder. |
| 3ds.acsMd | Another value required by the bank issuing your card-holder’s 3-D Secure challenge page. |
| _links.['cnp:3ds'].href | The N-Genius Online endpoint for submission of PaRes data at the end of the 3-D Secure challenge process |
Step 2: POST the data above to the acsurl of the card-holder’s issuer from the script running in your 3-D Secure handling . The card-holder’s issuer will display a page in this challenging the card-holder to authenticate themselves.
Step 3: Interpret the POST data sent to you by the card issuer’s 3-D Secure challenge page at the end of the 3-D Secure challenge process, and look specifically for the form attribute named PaRes.
Step 4: Pass the value of this PaRes form field back to your main payment processing script and submit it to N-Genius Online via a POST request to cnp3ds_url.
Example hand-over script (HTML + PHP):
<iframe src="<?php echo("[your-3ds-handler-script]?acsUrl=".$acsurl."&TermUrl=".$acsterm."&PaReq=".urlencode($acspareq)."&MD=".$acsmd); ?>">
</iframe>
Note: $acsterm designates a URL on your site, to which the issuer presenting the 3-D Secure challenge will POST the resulting authentication result.
Example 3-D Secure Handling script (HTML + PHP + cURL):
<?php
$out_acsurl = "";
$out_acspareq = "";
$out_acsmd = "";
$out_acsterm = "";
$in_acspares = "";
$in_acsmd = "";
if (!empty($_GET)) {
if (isset($_GET['acsUrl'])) { $out_acsurl = $_GET['acsUrl']; }
if (isset($_GET['PaReq'])) { $out_acspareq = $_GET['PaReq']; }
if (isset($_GET['MD'])) { $out_acsmd = $_GET['MD']; }
if (isset($_GET['TermUrl'])) { $out_acsterm = $_GET['TermUrl']; }
}
if (!empty($_POST)) {
if (isset($_POST['PaRes'])) { $in_acspares = $_POST['PaRes']; }
if (isset($_POST['MD'])) { $in_acsmd = $_POST['MD']; }
}
?>
<html>
<head>
</head>
<?php if (!empty($_GET)) : ?>
acsUrl: <?php echo($out_acsurl); ?> <br>
<form action="<?php echo($out_acsurl); ?>" method="POST" enctype="application/x-www-form-urlencoded">
PaReq: <input type="text" id="PaReq" name="PaReq" value="<?php echo($out_acspareq); ?>"><br>
TermUrl: <input type="text" id="TermUrl" name="TermUrl" value="<?php echo(‘[your-3ds-termination-script]'); ?>"><br>
MD: <input type="text" id="MD" name="MD" value="<?php echo($out_acsmd); ?>"><br>
<input type="submit">
</form>
<?php elseif (!empty($_POST)) :?>
PaRes: <input type="text" id="PaRes" name="PaRes" value="<?php echo ($in_acspares); ?>"><br>
MD: <input type="text" id="MDRes" name="MDRes" value="<?php echo ($in_acsmd); ?>"><br>
<?php else : ?>
<center>[ Awaiting 3DS ]</center>
<?php endif; ?>
</body>
</html>
Example PaRes submission script (PHP + cURL):
$postData = new StdClass();
$postData->PaRes = $pares;
$json = json_encode($postData);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $cnp3ds_url);
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));
$state = $output->state;
The response from the above step (submission of PaRes to N-Genius Online) will contain an updated 'state' attribute. Now, the 'state' attribute will now contain the final outcome of the payment request, per the following potential values (note that the ‘AWAIT_3DS’ outcome will no longer be relevant):
| State | Description and next steps |
|---|---|
| AUTHORISED | Authorization of the payment has been successful but you will need to capture the payment before funds will be transferred. |
| PURCHASED | The payment has been purchased successfully. No further action is required. This is the typical ‘state’ outcome for a payment made using the ‘PURCHASE’ action (see the order creation step). |
| CAPTURED | The payment has been authorized and captured successfully. No further action is required. This is the typical ‘state’ outcome for a payment made using the ‘SALE’ action (see the order creation step). |
| FAILED | The payment has not been successful. You should ask the customer to retry using either the same payment card, or a different one. |