Consuming web-hooks

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.

Configuring web-hooks

You may configure a web-hook at any time by logging in to the N-Genius Online portal and navigating to the Settings > Integrations > Webhooks section.

2735

Simply click on the 'New' button and enter the required details:

  • Name: a simple description for your web-hook (i.e. "My web-hook")
  • URL: the fully qualified (secure) URL on your server to which web-hook data will be posted
  • Header Key (optional): an optional header key you can use for additional security
  • Header Value (optional): the value of the defined header key, above.

Finally, click 'Add' to finalize your web-hook configuration.

📘

Web-hook white-listing

When you configure a web-hook in N-Genius Online, it will not immediately begin sending web-hook data to your nominated URL. A further process is required to check and white-list your URL, after which you will be notified that your web-hook is active.

Once your white-list is active, you will begin receiving order and event data to your nominated URL whenever a key event occurs.

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:

EventDescription
AUTHORISEDTriggered when a payment has been authorized
DECLINEDTriggered when the authorization for a payment has been declined by the card-holder's issuing bank
APM_PAYMENT_ACCEPTEDThis event is triggered when we get a success response from the APM system for a payment.
AUTHORISATION_FAILEDTriggered when the authorization process has failed
FULL_AUTH_REVERSEDTriggered 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_FAILEDTriggered when a request to reverse an authorization has failed. Note that, in this circumstance, the payment will remain in an AUTHORISED state.
PURCHASEDTriggered when the PURCHASE process has succeeded.
PURCHASE_DECLINEDTriggered when the PURCHASE process has been declined.
PURCHASE_FAILEDTriggered when the PURCHASE process has failed.
PURCHASE_REVERSEDTriggered when a previous PURCHASE has been reversed either through the N-Genius Online portal, or using the APIs.
PURCHASE_REVERSAL_FAILEDTriggered when the request above to reverse a PURCHASE request has failed.
CAPTUREDTriggered when an AUTHORISED payment has been CAPTURED, in full.
CAPTURE_FAILEDTriggered when the CAPTURE process has failed.
CAPTURE_VOIDEDTriggered 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_FAILEDTriggered when the request above to cancel/void a CAPTURE request has failed.
CANCELLATION_REQUESTEDThis event is triggered when we cancel the APM payment.
CANCELLATION_FAILEDWhen APM system, declines or fail for a payment, the event has been triggered
CANCELLEDOn success of a payment cancellation from the APM system, the event is triggered
PARTIALLY_CAPTUREDTriggered 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_FAILEDTriggered when a request to CAPTURE an AUTHORISED payment has failed.
REFUNDEDTriggered when a CAPTURED payment has subsequently been refunded.
REFUND_FAILEDTriggered when a REFUND request has failed.
PARTIALLY_REFUNDEDTriggered when a CAPTURED payment has been partially refunded (i.e. refunded for an amount less than the original CAPTURE request).
REFUND_REQUESTEDWhen we request refund for a transaction to APM system, this event is triggered
REFUND_REQUEST_FAILEDOn request to APM system for refund, if it fails the event is triggered
PARTIAL_REFUND_FAILEDTriggered when a PARTIAL_REFUND request has failed.
PARTIAL_REFUND_REQUEST_FAILEDOn request to APM system for partial refund, if it fails the event is triggered
PARTIAL_REFUND_REQUESTEDWhen we request partial refund for a transaction to APM system, this event is triggered
REFUND_VOIDEDTriggered when a REFUND has been cancelled/voided.
REFUND_VOID_FAILEDTriggered when a request to cancel/void a REFUND request has failed.
REFUND_VOID_REQUESTEDWhen cancel refund is requested to the APM system, this event is triggered
GATEWAY_RISK_PRE_AUTH_REJECTEDTriggered when a payment has been rejected by the N-Genius Online pre-authorization risk rules service.
PRE_AUTH_FRAUD_CHECK_REJECTEDTriggered when a payment has been rejected by a 3rd party pre-authorization fraud screening service.
POST_AUTH_FRAUD_CHECK_REJECTEDTriggered when a payment has been rejected by a 3rd party post-authorization fraud screening service.
POST_AUTH_FRAUD_CHECK_REVIEWWhen post auth check is pending, this event is triggered
POST_AUTH_FRAUD_CHECK_ACCEPTEDWhen 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.

🚧

Multiple web-hooks per order

It is important to note that, for orders processed in SALE mode (whereby a transaction is AUTHORISED and then immediately CAPTURED, ready for settlement) your nominated URL will receive multiple web-hooks at the same - one for the AUTHORISED event, and another for the CAPTURED event.

We recommend that, if you are processing payments exclusively in 'SALE' mode, you should ignore any AUTHORISED web-hook events posted to your nominated URL, and use only the CAPTURED events to drive your downstream processes.

If you are processing your orders in PURCHASE mode, which is recommended in most scenarios, only one web-hook for the payment outcome will be received (a 'PURCHASED' event).

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

  }

?>