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.


Your service account API key and outlet reference

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


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/
Authorization Basic your_api_key


Sample Request

$apikey = [your api key goes here]; 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, “”);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        “accept: application/”,
        “authorization: Basic “.$apikey,
        “content-type: application/”
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  
    curl_setopt($ch, CURLOPT_POST, 1);
   $output = json_decode(curl_exec($ch));
    $access_token = $output->access_token;
Sample Response
   {“access_token”: “eyJhbGciOiJSUzI1N…0eDloZnVRI”,
    “expires_in”: 300,
    “refresh_expires_in”: 1800,
    “refresh_token”: “eyJhbGciOi…eDloZnVRIn0”,     
    “token_type”: “bearer” }

Note: you will require the access_token value for any subsequent calls to the N-Genius Online platform APIs.

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:// /transactions/outlets/[your-outlet-reference]/orders


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/
Accept application/



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
Your Reference (optional) customer-unique-number
billingAddress { }
Address Block (optional)  N/A
billingAddress.firstName (optional) Payer first name
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

      $postData = new StdClass();
    $postData->action = “PURCHASE”;
    $postData->amount = new StdClass();
    $postData->amount->currencyCode = “USD”;
    $postData->amount->value = 9*100;
    $postData->emailAddress = “”;
    $postData->merchantOrderReference = “customer-unique-number”;
    $postData->billingAddress  = new StdClass();
    $postData->billingAddress->firstName = ‘John’;
    $postData->billingAddress->lastName = ‘doe’;
          $postData->merchantAttributes = new StdClass();
    $postData->merchantAttributes->redirectUrl = ‘[put your redirection URL after payment]’; 
    $postData->merchantAttributes->skipConfirmationPage = true;
    $outlet = [your outletID which have already given to];
    $token = $access_token; // to get this access token you have first call get access token API.
    $json = json_encode($postData);
    $ch1 = curl_init();
    curl_setopt($ch1, CURLOPT_URL, “”.$outlet.”/orders”);
    curl_setopt($ch1, CURLOPT_HTTPHEADER, array(
        “Authorization: Bearer “.$token,
        “Content-Type: application/”,
        “Accept: application/”));
        curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);  
        curl_setopt($ch1, CURLOPT_POST, 1);
        curl_setopt($ch1, CURLOPT_POSTFIELDS, $json);
    $output = json_decode(curl_exec($ch1));
    $order_reference = $output->reference;
    $order_paypage_url = $output->_links->payment->href;
    curl_close ($ch1);
Sample Response :


amount{currencyCode: “USD”, value: 900}



billingAddress{firstName: “john”, lastName: “doe”}





formattedAmount“USD 9”







paymentMethods{card: [“MASTERCARD”]}






_embedded{payment: [,…]}


0{_id: “urn:payment:1bb11398-5175-445d-899e-82bfed82aad0”, _links: {self: {,…}, payment:card: {,…},…},…}


amount{currencyCode: “USD”, value: 900}










_links{self: {,…}, payment:card: {,…},…}

curies[{name: “cnp”, href: “{rel}”,…}]

0{name: “cnp”, href: “{rel}”,…}









_links{cancel: {,…}, cnp:payment-link: {,…},…}




payment{href: “”}

payment-authorization{href: “”}





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://[outlet-reference]/orders/[order-reference]


Header Value
Authorization Bearer [access_token]
Accept application/


Sample Request:

  $access_token = $output->access_token; // get this from authentication API
  $token = $access_token;
  $outlet = [your outlet];
  $curl = curl_init();
  curl_setopt_array($curl, [
  CURLOPT_URL => “”.$outlet.”/orders/”.$order_reference,
    “Authorization: Bearer “.$token,
    “Accept: application/”
 $response = curl_exec($curl);
 $err = curl_error($curl);
Sample Response



  “_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.

N-Genius Online supports the integration of web-hooks (sometimes referred to as call-backs). When web-hooks are enabled on your account, whenever a key event occurs against one of your orders, a message is posted to a secure URL on your server/environment providing you with information about what happened.

You can benefit from the web-hooks service no matter how you are using the N-Genius Online payment gateway. If they are enabled, you will be notified of any key update to your customers’ orders. However, they are particularly useful in the following scenarios:

  • When you want to discover the outcome of any Hosted Payment Page transaction, even if your customer has closed their browser window before redirecting back to your site.
  • When you are operating an invoicing service (whether via API or manually via the N-Genius Online portal), and you want to be notified when your customer has made the payment.
  • When you want to more closely link the N-Genius Online gateway service to your back-end systems, without having to implement inefficient polling operations.
Key events triggering web-hooks

Below is a list of key events that, when they occur against one of your orders, will trigger a web-hook post to your nominated URL:

Event Description
AUTHORISED Triggered when a payment has been authorized
DECLINED Triggered when the authorization for a payment has been declined by the card-holder’s issuing bank
APM_PAYMENT_ACCEPTED This event is triggered when we get a success response from the APM system for a payment.
AUTHORISATION_FAILED Triggered when the authorization process has failed
FULL_AUTH_REVERSED Triggered when an authorization has been reversed, either automatically following a post-authorization fraud screening rejection, or manually following an API or portal-based request to reverse the authorization.
FULL_AUTH_REVERSAL_FAILED Triggered when a request to reverse an authorization has failed. Note that, in this circumstance, the payment will remain in an AUTHORISED state.
PURCHASED Triggered when the PURCHASE process has succeeded.
PURCHASE_DECLINED Triggered when the PURCHASE process has been declined.
PURCHASE_FAILED Triggered when the PURCHASE process has failed.
PURCHASE_REVERSED Triggered when a previous PURCHASE has been reversed either through the N-Genius Online portal, or using the APIs.
PURCHASE_REVERSAL_FAILED Triggered when the request above to reverse a PURCHASE request has failed.
CAPTURED Triggered when an AUTHORISED payment has been CAPTURED, in full.
CAPTURE_FAILED Triggered when the CAPTURE process has failed.
CAPTURE_VOIDED Triggered when a previous CAPTURE has been cancelled/voided either through the N-Genius Online portal, or using the APIs. Note that the payment will then return to an AUTHORISED state.
CAPTURE_VOID_FAILED Triggered when the request above to cancel/void a CAPTURE request has failed.
CANCELLATION_REQUESTED This event is triggered when we cancel the APM payment.
CANCELLATION_FAILED When APM system, declines or fail for a payment, the event has been triggered
CANCELLED On success of a payment cancellation from the APM system, the event is triggered
PARTIALLY_CAPTURED Triggered when an AUTHORISED payment has been partially captured (i.e. for any value that does not meet or exceed the original authorization amount).
PARTIAL_CAPTURE_FAILED Triggered when a request to CAPTURE an AUTHORISED payment has failed.
REFUNDED Triggered when a CAPTURED payment has subsequently been refunded.
REFUND_FAILED Triggered when a REFUND request has failed.
PARTIALLY_REFUNDED Triggered when a CAPTURED payment has been partially refunded (i.e. refunded for an amount less than the original CAPTURE request).
REFUND_REQUESTED When we request refund for a transaction to APM system, this event is triggered
REFUND_REQUEST_FAILED On request to APM system for refund, if it fails the event is triggered
PARTIAL_REFUND_FAILED Triggered when a PARTIAL_REFUND request has failed.
PARTIAL_REFUND_REQUEST_FAILED On request to APM system for partial refund, if it fails the event is triggered
PARTIAL_REFUND_REQUESTED When we request partial refund for a transaction to APM system, this event is triggered
REFUND_VOIDED Triggered when a REFUND has been cancelled/voided.
REFUND_VOID_FAILED Triggered when a request to cancel/void a REFUND request has failed.
REFUND_VOID_REQUESTED When cancel refund is requested to the APM system, this event is triggered
GATEWAY_RISK_PRE_AUTH_REJECTED Triggered when a payment has been rejected by the N-Genius Online pre-authorization risk rules service.
PRE_AUTH_FRAUD_CHECK_REJECTED Triggered when a payment has been rejected by a 3rd party pre-authorization fraud screening service.
POST_AUTH_FRAUD_CHECK_REJECTED Triggered when a payment has been rejected by a 3rd party post-authorization fraud screening service.
POST_AUTH_FRAUD_CHECK_REVIEW When post auth check is pending, this event is triggered
POST_AUTH_FRAUD_CHECK_ACCEPTED When post auth check is success, this event is triggered


Note: that you may receive a number of web-hook messages in quick succession to your nominated URL. It is your responsibility to filter these as best meets the needs of your business, and to drive your downstream processes accordingly.

Please also note that only a single web-hook message will be sent to your nominated URL, per event, with no retries.

Interpreting web-hook data

❗️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):


  $db = init_database();

  try {

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

    $order = json_decode($json);

    $sql = “INSERT INTO orders (  event,





                                  amount ) VALUES (  :event,





                                                          :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));


    echo ‘{“success”: true}’;

    $db = null;     


  catch(PDOException $e)


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

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


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

    $db = null;     



  function init_database() {





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


    return $dbh;