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

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

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

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.