Before you start

To have the Forex API service made available to you, you will need to ensure that you have the MCP (Multi-Currency Pricing) option enabled for your N-Genius Online account. If you are unsure whether you have this service enabled, please consult with your relationship manager, or our E-Commerce Support team, for confirmation before you proceed.

Request an access token

In order to use the Forex API provided by Network International, you must first retrieve an access token from the identity APIs, establishing that you have permissions to access the resource.

An example of this can be found here: Request an access token.

Retrieve FX Rates for Geolocated and Target Currencies

Next, we can call the Forex API to request a specified transaction amount to be quoted in up to three different currencies per call:

• One geolocation-matched currency based on the shopper's IP address
• Up to two 'target' currencies of your choice

Where a match is found, the API will respond accordingly with the valid currency conversion rate and amounts quoted in the currency specified.

📘

Ensuring that your integration is 'fail safe'

Not all currency conversion pairs requested will be available on the Network International Forex API, and it may not always be possible to match a shopper's IP address with a relevant currency. As such, you should ensure that you construct your integration to this service in a manner that is fault/failure tolerant, paying particular attention to:

• scenarios where the IP geolocated currency cannot be matched
• scenarios where only one (or none) of the target currencies specified has an available currency pair conversion
• scenarios where no currency conversion options can be provided (for example where the shopper locale matches the order currency), or the service returns an error

In most cases, the above scenarios will manifest as a removal of the erroneous entry from the payload of the response from the Forex API.

By keeping your integration 'tolerant' of the above scenarios and falling back to a default transaction currency state (i.e. AED), you can further ensure that a failed/lost opportunity for currency conversion does not then result in a lost sale unnecessarily.

HTTP Request Method: POST
Resource (URI): https://api-gateway.sandbox.ngenius-payments.com/forex/outlets/<outlet_id>/forex-lookup

Headers:

Add these headers to your request, noting that you should replace access_token with the token you received in the previous step.

Body:

Example:

{
    “currencyCodeFrom”: “AED”,
    “payerIpAddress”: “127.0.0.1”,
    “amount”: 100,
    “targetCurrency"“[“INR”,”USD”]
}

Response Body:

🚧

Currency minor units versus major units

It is important to keep in mind that, when displaying currency choice options to your shopper, that all currency amount values on this Forex API are both input and output in minor units. Whilst most currencies have adopted the decimal standard of two minor units (i.e. 1.23 AED), not all currencies are the same - some currencies have more than two minor units, where others may not have adopted minor units at all.

It is therefore critical that, when sending amounts to this API, that the appropriate minor unit conversion is applied before requesting a currency conversion, and that this is reversed when displaying currency conversion rates back to your shopper.

All successful API conversion requests will specify the number of minor unit places each currency amount is quoted in.

Response Example:

{
	"fromCurrency": "AED",
	"payerLocaleCurrency": {
		"currency": "INR",
		"convertedAmount": 2966,
		"conversionRate": 20.6646769,
		"minorUnit": 2
	},
	"targetCurrencies": [{
		"currency": "USD",
		"convertedAmount": 8066,
		"conversionRate": 80.6646769,
		"minorUnit": 2
	}]
}

Confirming transaction currency choice (Direct API customers only)

Once your shopper has chosen a currency (or has otherwise declined the conversion offer), confirming this decision and processing the shopper's payment in the chosen currency is as simple as adding one additional attribute to the payment information block.

See here for a reminder of this step: Two stage payments.

Scenario 1: Shopper declines all Forex conversions

In this scenario, the shopper has declined the currency conversion options presented to them, and has instead decided to proceed in the base currency of the order (i.e. AED). In this scenario, you should not change the information you send in the payment information block:

{
  "pan": "411111111111111111111",
  "expiry": "2021-06",
  "cvv": "123",
  "cardholderName": "John Brown"
}

Scenario 2: Shopper accepts one of the Forex conversion options

In this scenario, the shopper has chosen to either pay in the geolocation-matched currency identified from their IP address, or one of the two target currencies that you may have chosen to also offer to them. In this scenario, you should add a single additional attribute (i.e. "currency":"USD") to the payment information block, as follows:

{
  "pan": "411111111111111111111",
  "expiry": "2021-06",
  "cvv": "123",
  "cardholderName": "John Brown",
  "currency": "USD"
}

The payment from the shopper will then be authorized and processed in the currency specified, according to the conversion rate returned in the previous step.