Switching your integration from SALE to PURCHASE

The 'SALE' transaction type in the N-Genius Online gateway transaction model uses a two-step authorization model, wherein the payment is first authorized, then immediately captured (or, sent for settlement). Whilst this method provides great flexibility in regards to how payments can then subsequently be managed, acquirers will - in some cases - charge more for accepting these transaction types.

It is for this reason that N-Genius Online has now introduced the 'PURCHASE' transaction type. Whilst this transaction type operates in much the same way as the 'SALE' type, it is a single-stage message that can be more cost effective in many cases.

Does the PURCHASE transaction type apply to me?

You should consider switching your integration to use the 'PURCHASE' transaction type if any one of the following conditions about your integration to N-Genius Online are true:

• You have integrated with the Hosted Payment Page (HPP) of N-Genius Online
• You have integrated with N-Genius Online using the Direct API integration method
• You have integrated with N-Genius Online using the Hosted Session (WebSDK) method or any of the mobile SDKs provided by Network International
• You are using the 'SALE' model of transaction processing

However, we recommend that you should not yet switch your integration to use 'PURCHASE' if any of the following conditions about your N-Genius Online integration are true:

• You are using the 'AUTH' and separate 'CAPTURE' model of transaction processing
• You processing payments exclusively via the Pay-by-Link or Virtual Terminal UIs

How do I know if am using the SALE model of transaction processing?

In order to identify whether you are using the 'SALE' model of transaction processing, you will need to look at your N-Genius Online integration code. In your API call to create an order, you will be sending JSON that looks something like this:

{  
  “action”: “SALE”,   
  “amount” : { “currencyCode” : “AED”, “value” : 100 } 
}

There may be more information in the JSON that you are sending than is shown in this example, but the key item to look for is the "action": "SALE" element. Here, your integration is telling N-Genius Online that you want to process your payment using the SALE workflow.

If your own JSON action element reads AUTH or PURCHASE then you do not need to do anything at this time.

I am using SALE, so what do I need to do to switch to PURCHASE?

If you are using the 'SALE' processing mode today, and your integration meets the criteria set out in the section above ("Does the PURCHASE transaction type apply to me?"), there are two parts of your N-Genius Online integration that you will need to change:

• The API call creating the order (as above), and...
• The part of your code that deals with obtaining the payment outcome

1. Changing the order creation API call to use PURCHASE

For this step, you simply need to change the action element in your order creation API call JSON to use the keyword PURCHASE instead of SALE, as below:

{  
  “action”: “PURCHASE”,   
  “amount” : { “currencyCode” : “AED”, “value” : 100 } 
}

Note that any other JSON elements you are also sending in this data structure today should remain the same.

2. Changing the order status/outcome retrieval code to use PURCHASE

There are a number of ways to obtain the outcome of a payment from N-Genius Online, and which you are using will depend on your integration type.

• For Hosted Payment Page (HPP) integrations, you may receive this via a web-hook notification sent to your nominated internal URL, or as a response to a direct query against the order
• For Direct API integrations, you will receive the order outcome as a response to the payment card

However, in all cases, if you are using the SALE processing model/workflow, your code will be looking for the order status CAPTURED.

In order for your code to now work correctly with the PURCHASE transacrion processing type, you should also make accommodation in your integration for a new status/event.

This new status/event is PURCHASED and will replace the CAPTURED event for orders processed using the PURCHASE transaction type.

Testing

It is highly recommended that these changes are made in the N-Genius Online sandbox/UAT environment before applying them to your live/production code base, in order to ensure that there is minimal disruption to your business in doing so.