Two stage payments

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).

HeaderValue
AuthorizationBearer parameters]
{
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

Note: If you wish to have the card holder/customer IP address in the gateway reports,
The request header should have the key 'X-Forwarded-For' with the value being the customer IP address(IPv4 or IPv6) This ideally needs to be extracted from the request you receive from the payer while they are making the payment on your website/portal.

Body:

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

ParameterDescriptionExample value
actionOrder type"AUTH", "SALE", "PURCHASE"
amount { }Amount blockN/A
amount.currencyCodeOrder currency"AED", "USD", "EUR"
amount.valueOrder amount1000 (minor units)
emailAddressPayer's email address[email protected]
billingAddress { }Billing address blockN/A
billingAddress.firstNamePayer's first namemandatory
billingAddress.lastNamePayer's last/second namemandatory

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.paymentse ._links.to your reques.href

Headers:

Add these headers to your request:

HeaderValue
AuthorizationBearer parameters]
{
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

Body:

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

AttributeDescriptionPossible value(s)
panThe PAN (longest number) on the card4111111111111111
expiryCard expiry date (YYYY-MM)2025-04
cvvThe payment card’s security code123
cardholderNameThe name of the card-holderJohn 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:

StateDescription and next steps
AUTHORISEDAuthorization of the payment has been successful but you will need to capture the payment before funds will be transferred.
PURCHASEDThe 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).
CAPTUREDThe 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_3DSA 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.
FAILEDThe 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 attributeFunction / description
3ds.acsurlThe URL of the issuer’s challenge page
3ds.acsPaReqThe ck:ayer eteuthentication : {
uest value required by the issuer for providing the challenge to your card-holder.
3ds.acsMdAnother value required by the bank issuing your card-holder’s 3-D Secure challenge page.
_links.parameters].hrefThe 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):

StateDescription and next steps
AUTHORISEDAuthorization of the payment has been successful but you will need to capture the payment before funds will be transferred.
PURCHASEDThe 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).
CAPTUREDThe 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).
FAILEDThe payment has not been successful. You should ask the customer to retry using either the same payment card, or a different one.