Retrieve FX Rates

Using Network International's FX service can greatly enhance your shopper's experience by presenting payment currency options at checkout that are familiar and can feel more personalised

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/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.

Header

Value

Authorization

Bearer access_token

Content-Type

application/vnd.ni.forex.v1+json

Body:

Attribute

Description

Example Value

currencyCodeFrom

Base order currency

AED

payerIpAddress

IP address of shopper

127.0.0.1

amount

Order amount (in minor units)

100
(100 = 1.00 AED)

targetCurrency[]

Optional. Array of target currencies to also return (maximum of 2) conversion rates for.

['INR','USD']
(to also get rates for INR and USD).

Example:

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

Response Body:

Attribute

Description

Example Value

fromCurrency

Base order currency

AED

payerLocaleCurrency{}

Geolocation results for shopper IP

N/A

payerLocaleCurrency.currency

Geolocated currency matching supplied shopper IP address

INR

payerLocaleCurrency.convertedAmount

Amount (in minor units) for this transaction in geolocated currency

2165
( = 21.65 INR)

payerLocaleCurrency.conversionRate

Conversion rate applied to this currency exchange

Decimal

payerLocaleCurrency.minorUnit

Number of decimal points (or minor unit places) to apply to final display to the shopper *

2

targetCurrencies []

Array of target currency conversions as specified in the previous step

N/A

targetCurrencies[].currency

Currency matching supplied target currency

USD

targetCurrencies[].convertedAmount

Amount (in minor units) for this transaction in target currency

27

targetCurrencies[].conversionRate

Conversion rate applied to this currency exchange

Decimal

targetCurrencies[].minorUnit

Number of decimal points (or minor unit places) to apply to final display to the shopper *

2

🚧

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.