Hosted Payment Page

Simple, secure and PCI DSS compliant.

---

Easy-to-integrate, mobile-first, responsive payment pages, and a wide range of currencies and payment methods allow you to accept payments from shoppers on the move, wherever they are.

A hosted payment page (sometimes referred to as a Pay Page) integration is by far the most common implementation method for small and medium-sized businesses the world over who wish to accept payments online.

This integration type offers a competitive level of branding and customization, combined with the peace-of-mind that comes from knowing that payment card information is being entered onto a page controlled by Network International, allowing you to get on with the business of running your business.

 

By now, you should have been provided with an N-Genius Online Portal login. If you have not been provided with this login, please contact your N-Genius Online Portal administrator, which may be someone in your own company.

In order to integrate with the N-Genius Online payment APIs, you will need to generate a Service Account API key and outlet reference for your trading outlet.

You will need both the API key and the outlet reference for your N-Genius Online account to proceed with the integration guides contained in this document, so be sure to take a note of them.

 

Request an access token

---

This section will describe how you will authenticate yourself to the N-Genius Online identity services, and receive an access token in return, which you can then use to perform more meaningful operations using the N-Genius Online payment APIs.

 

Request an access token

The first step for any N-Genius Online gateway interaction is to validate ourselves with the identity service and obtain an access token. This token allows us to execute operations on the gateway APIs with authority, and whilst a single token will expire after 5 minutes, we can use our Service Account API key to generate one at any time.

HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.mybank.ngenius-payments.com/identity/auth/access-token.

Headers:

Add these headers to your request (note that you should replace ‘your_api_key‘ with the service account API key in the Getting started section).

Header	Value
Content-Type	application/vnd.ni-identity.v1+json
Authorization	Basic your_api_key

 

Sample Request

---

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.mybank.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	“PURCHASE”
amount { }	Amount block	N/A
amount.currencyCode	Order currency	“AED”, “USD”, “EUR”
amount.value	Order amount	1000 (minor units) this means multiply your amount by 100
emailAddress	Payer’s email address	customer@test.com
merchantOrderReference	Your Reference (optional)	customer-unique-number
billingAddress { }	Address Block (optional)	N/A
billingAddress.firstName	billingAddress.firstName (optional)	Payer first name
billingAddress.lastName	billingAddress.lastName (optional)	Payer Last Name
merchantAttributes { }	attributes Block (optional)	N/A
merchantAttributes.redirectUrl	this redirection URL will enable you to redirect your customer to your page after they finish the payment	your redirection URL
merchantAttributes.skipConfirmationPage	this will enable you to skip the confirmation page of the payment gateway and will automatically redirect to your URL.	True

 

 

Note: these are the mandatory minimum input parameters for creating an order using the N-Genius Online gateway APIs

 

Sample Request

 

 

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

 

Request payment from your customer

---

By this point, we have now successfully created an order in the N-Genius Online gateway, and our next step is to request payment from our customer.

To do so, you should redirect the customer to the order_paypage_url we obtained from the response from our request to create an order. The N-Genius Online payment page will take care of the 3-D Secure and authorization process for us.

This redirect can be executed as a full-page redirect, as a ‘Lightbox’ implementation, or within an HTML tag, according to your needs.

 

Getting the payment outcome

---

 

In order to receive the outcome of the payment, it is recommended that merchants using this integration type also configure their N-Genius Online gateway to send call-back/web-hook notifications, so that they may be received and interpreted.

Alternatively, you may also interrogate the ‘ref’ query parameter that will be added to the redirectUrl you have specified. This will contain the order reference value, which you may use (in conjunction with a new access_token value, if required) to query the outcome of a payment with a GET call to the N-Genius Online APIs.

 

Retrieve order status

---

You may query the N-Genius Online APIs to retrieve the status/outcome of any order, at any time. Doing so will provide you not only with a full breakdown of the order object, but it will also provide easy-to-use links to any follow-up request you may wish to execute.

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

Headers:

Header	Value
Authorization	Bearer [access_token]
Accept	application/vnd.ni-payment.v2+json

 

Sample Request:

JSON

{

  “_id”: “urn:order:[order-reference]”,

  “_links”: {

  “self”: { “href”: “[order resource URI]” },

  “tenant-brand”: { “href”: “[service provider brand resource URI]” },

  “payment”: { “href”: “[payment page resource URI]”},

  “merchant-brand”: { “href”: “[your branding resource URI]” }

   },

  “action”: “[action]”,

  “amount”: {

  “currencyCode”: “[amount.currencyCode]”,

  “value”: [amount.value]

  },

  “language”: “[language]”,

  “merchantAttributes”: {

  “redirectUrl”: “[your redirect URL]”

  },

  “reference”: “[order-reference]”,

  “outletId”: “[outlet-reference]”,

  “createDateTime”: “[timestamp]”,

  “paymentMethods”: {

  “card”: [available payment methods]

  },

  “formattedOrderSummary”: {},

  “formattedAmount”: “[formatted order amount, i.e. AED10.00]”,

  “_embedded”: {

  “payment”: [

  {

  “_id”: “urn:payment:[payment resource URI]”,

  “_links”: {

  “payment:card”: { “href”: “[direct card payment URI]” } },

  “outletId”: “[outlet-reference]”,

  “orderReference”: “[order-reference]”,

  “state”: “[state]”,

  “amount”: {

  “currencyCode”: “[amount.currencyCode]”,

  “value”: [amount.value]

  },

  “updateDateTime”: “[timestamp]”

  }

  ]

  }

  }

 

Consuming web-hooks (call-back)

---

Automate your N-Genius Online integration with rich, dependable web-hook data and eliminate manual order management effort in the process.

❗️Response to web-hook request

When you consume the web-hook you need to respond to N-Genius Online with either 200 or 201 for the POST request from N-Genius Online. N-Genius Online will timeout after 15        seconds if you do not respond to the web-hook request.

Web-hook data posted to your nominated URL will follow the standard order object model detailed in the The order object – (json response you have received from order) section, with one exception: the order object received will be enclosed in an ‘event’ JSON container/wrapper, as follows: { eventName: ‘AUTHORISED’, order { // order data } }

 

Example web-hook handling script (HTML, PHP + MySQL):

<?php

  $db = init_database();

  try {

    $json = file_get_contents(“php://input”);

    $order = json_decode($json);

    $sql = “INSERT INTO orders (  event,

                                  outlet,

                                  reference,

                                  email,

                                  currency,

                                  amount ) VALUES (  :event,

                                                          :outlet,

                                                          :ref,

                                                          :email,

                                                          :currency,

                                                          :amount );”;     

    $stmt = $db->prepare($sql);

    $stmt->bindParam(“:event”, $order->eventName);

    $stmt->bindParam(“:outlet”, $order->order->outletId);

    $stmt->bindParam(“:ref”, $order->order->reference);

    $stmt->bindParam(“:email”, $order->order->emailAddress);

    $stmt->bindParam(“:currency”, $order->order->amount->currencyCode);

    $stmt->bindParam(“:amount”, number_format($order->order->amount->value / 100, 2));

    $stmt->execute();

    echo ‘{“success”: true}’;

    $db = null;     

  }

  catch(PDOException $e)

  {

    $sql = “INSERT INTO orders() VALUES();”;

    $stmt = $db->prepare($sql);

    $stmt->execute();

    echo ‘{“error”:{“text”:’. $e->getMessage() .’}}’;

    $db = null;     

  }        

  die();

  function init_database() {

    $dbhost=”[your-db-host]”;

    $dbuser=”[your-db-user]”;

    $dbpass=”[your-db-pwd]”;

    $dbname=”[your-db-name]”;

    $dbh = new PDO(“mysql:host=$dbhost;dbname=$dbname;”, $dbuser, $dbpass);

    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    return $dbh;

  }

?>