Using Multi-Currency Pricing with the Web SDK

📘
Before you start
This guide assumes you have already integrated the Web SDK component for N-Genius Online. If you haven't, please refer to the Web SDK Integration Guide before proceeding with the MCP feature integration.

Step 1: Retrieve available currencies

First, ensure that MCP is enabled for your integration. During testing, you can toggle it on or off by setting the relevant constant in your merchant server script.

const isMCPEnabled = true|false 		// set to 'true' to enable MCP

You need to define the appendOptionInDropDown function.

Example:
1.	function appendOptionInDropDown(currency) {
2.	  const option = document.createElement('option');
3.	  option.value = currency.currencyCode;
4.	  option.text = currency.currencyCode;
5.	  return option;
};

Next, create a currency drop-down (select) in your UI with an appropriate input identifier and bind the getSupportedCurrencies() method from the NI Web SDK to this currency dropdown input.

Example:

<select class="currency-list" id="currency-list">
  <option value="" disabled>Select Currency</option>
</select>

function getSupportedCurrencies() 
{
const currencyInput = document.getElementById('currency-list');
let defaultCurrencyValue = merchantCurrency; // set merchant currency value
let isCurrencyListNull = true;
try {
  const {
    response: currencyListResponse,
    error
  } = await window.NI.handleGetSupportedCurrencies('currency-input', {
    style,
    apiKey,
    outletRef: testOutletRef,
    merchantCurrency
  });
  if (currencyListResponse.currencyList) {
    const { currencyList } = currencyListResponse;
    currencyList.forEach(currency => {
      const currencyOption = appendOptionInDropDown(currency);
      currencyInput.append(currencyOption);
    });
    defaultCurrencyValue = currencyList[0].currencyCode;
    isCurrencyListNull = false;
  }
  if (
    (currencyListResponse.currencyList &&
      currencyListResponse.currencyList.length === 0) ||
    !currencyListResponse.currencyList ||
    error
  ) {
    const currencyOption = appendOptionInDropDown(defaultCurrenyOption);
    currencyInput.append(currencyOption);
    if (error) console.error('===currency list error', error);
  }
} catch (e) {
  console.error('===currency list error', e);
  const currencyOption = appendOptionInDropDown(defaultCurrenyOption);
  currencyInput.append(currencyOption);
}
document.getElementById('currency-list').value = defaultCurrencyValue;
if (!isCurrencyListNull) {
  getConvertedAmountForCurrency(); // call forex currency conversion when currency list been shown
}
}

The above example provides the logic to bind the currency list from the N-Genius Online API response, and insert these as option elements list in the currency dropdown.

A sample of the currency response from the N-Genius Online API is below.

Error exemption has been handled when the API call fails or any other subsequent calls fail inside the getSupportedCurrencies() method, and should be interrogated from there.
If the API call or logic fails, getSupportedCurrencies() method will append the merchant currency code (only) in the select dropdown input, to ensure that payment processing falls back to the default (non-FX) mode.

Step 2: Convert the payment amount

Assuming no API or logic failures are present from the above step, the next step is to execute the currency conversion on the basket amount for the shopper/card-holder.

The method getConvertedAmountForCurrency()should be used to retrieve the MCP converted value for the card-holder's total payment amount in the currencies available from the previous step. This method calls the N-Genius Online FX lookup APIs to get the currency conversion response from the NI SDK.

As such, you should bind the getConvertedAmountForCurrency()method to the dropdown input component we created in the previous step:

<select
  class="currency-list"
  id="currency-list"
  onchange="payment.getConvertedAmountForCurrency()">
  <option value="" disabled>Select Currency</option>
</select>

The inclusion of the onchange="payment.getConvertedAmountForCurrency()"instruction will trigger the currency conversion method as described above, and will execute each time the user selects a new option from this dropdown input.

When the getConvertedAmountForCurrency() method is executed, it will fetch the currency dropdown input value and send it to the N-Genius OnlineFX API to retrieve the converted amountvalue in the user's chosen currency.

<!----HTML------!>
<div id="currency-conversion-value">
  <span class="">Converted Amount</span>
  <span class="" id="converted-amount-value"></span>
</div>


{* Style *}
#currency-conversion-value {
  display: none;
  flex-direction: row;
  padding: 10px 0;
  margin-bottom: 25px;
  justify-content: space-between;
}

To show the converted currency value in the screen add the above code in index.html and index.css.

<!----HTML------!>
<div id="currency-conversion-value">
  <span class="">Converted Amount</span>
  <span class="" id="converted-amount-value"></span>
</div>


{* Style *}
#currency-conversion-value {
  display: none;
  flex-direction: row;
  padding: 10px 0;
  margin-bottom: 25px;
  justify-content: space-between;
}
To show the converted currency value in the screen add the above code in index.html and index.css

 

When getConvertedAmountForCurrency() method triggered, it will fetch the currency dropdown input value and send it to the api to get the converted amount data.

funtion getConvertedAmountForCurrency() 
{
document.getElementById('currency-conversion-value').style.display = 'none';
const selectedCurrencyCode = document.getElementById('currency-list').value;

// To avoid forex currency conversion when selected currency value is same as merchant currency
if (merchantCurrency === selectedCurrencyCode) {
  console.info(
    '=====Target currency is same as Merchant currency. So currency conversion is not needed'
  );
  return null;
}

try {
  const {
    response: convertedAmountResponse,
    error
  } = await window.NI.handleForexCurrencyConversion('currency-conversion', {
    style,
    apiKey,
    outletRef: testOutletRef,
    orderAmount: {
      value: orderAmount,
      currencyCode: merchantCurrency
    },
    targetCurrencyCode: selectedCurrencyCode
  });
  if (error) {
    console.error('===forex converted amount error', error);
    return null;
  }
  
  // bind converted currency value in html code
  document.getElementById('currency-conversion-value').style.display = 'flex';
  document.getElementById(
    'converted-amount-value'
  ).innerHTML = convertedAmountResponse;

  return convertedAmountResponse;
} catch (e) {
  console.error('===forex converted amount error', e);
  return null;
}
}

This response contains the final converted amount data for the selected currency, along with the order amount.

Sample response:

🚧
Handling Minor Units
The N-Genius Online APIs handle all currency amounts in minor units—for example, 100.00 AED is represented as 10000. Your UI must properly handle minor units and display them according to the shopper's local conventions.
For example, whilst most currencies use two decimal points to represent sub-unit values (i.e. AED, GBP, USD, etc.), other currencies may use more than two decimal points, only one or none at all. The number of minor units a currency expects is denoted by the minorUnitselement of each currency block.
Incorrect formatting may cause shoppers to pay more or less than expected, or cause the transaction to fail.

Step 3: Complete the payment in the chosen currency

The third and final step will be to process the payment in the currency chosen by the shopper.

Always offer cardholders the option to pay in the default payment currency (typically AED for UAE merchants). Label every alternative currency clearly at checkout.

To complete the payment, please refer to Step 4 (onwards) from the Web SDK Integration Guide, ensuring that the card-holder's chosen currency value from the previous steps in this guide is reflected in the API call from your server to N-Genius Online, as below.

Note the addition of a paymentblock to the server request:

{
      "action": "PURCHASE",
      "amount": {
        "currencyCode": "AED",			// original currency
        "value": 100								// original amount
      },
      "payment": {
        "currency": "USD"						// target currency
      }
    }

Sample Code Snippet

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta http-equiv="X-UA-Compatible" content="ie=edge" />
        <!--SDK url with rest of your scripts-->
        <script
            src="https://paypage.sandbox.ngenius-payments.com/hosted-sessions/sdk.js"></script>
    </head>
    <body>
        <!--Your website code goes here-->
        <div style="width: 500px; height: 220px;" id="mount-id"></div>
        <div style="width: 100%; height: 20px;" id="currency-input"></div>
        <div style="width: 100%; height: 20px;" id="currency-conversion"></div>
        <select class="currency-list" id="currency-list"
            onchange="getConvertedAmountForCurrency()">
            <option value disabled>Select Currency</option>
        </select>
        <div id="currency-conversion-value">
            <span class>Converted Amount</span>
            <span class id="converted-amount-value"></span>
        </div>
    </body>
    <script>
    // variables required
    const isMCPEnabled = true
    const orderAmount = 100
    const style = {
      input: {
        borderStyle: 'solid',
        borderWidth: '1px',
        padding: '10px 5px',
        borderColor: 'black',
        borderRadius: '10px'
      }
    }
    const apiKey =
      'API_KEY'
    const outletRef = 'OUTLET_REF'
    const merchantCurrency = 'GBP'
    const defaultCurrenyOption = {
      currencyCode: merchantCurrency
    }

    // functions required
    function appendOptionInDropDown (currency) {
      const option = document.createElement('option')
      option.value = currency.currencyCode
      option.text = currency.currencyCode
      return option
    }

    async function getConvertedAmountForCurrency () {
      document.getElementById('currency-conversion-value').style.display = 'none'
      const selectedCurrencyCode = document.getElementById('currency-list').value

      if (merchantCurrency === selectedCurrencyCode) {
        console.info(
          '=====Target currency is same as Merchant currency. So currency conversion is not needed'
        )
        return null
      }

      try {
        const { response: convertedAmountResponse, error } =
          await window.NI.handleForexCurrencyConversion('currency-conversion', {
            style,
            apiKey,
            outletRef,
            orderAmount: {
              value: orderAmount,
              currencyCode: merchantCurrency
            },
            targetCurrencyCode: selectedCurrencyCode
          })
        if (error) {
          console.error('===forex converted amount error', error)
          return null
        }
        if (convertedAmountResponse === 'FAILED') {
          console.error('===forex convertion failed', error)
          document.getElementById('currency-conversion-value').style.display =
            'flex'
          document.getElementById(
            'converted-amount-value'
          ).innerHTML = `<span style="display: block; text-align: end;">${convertedAmountResponse}</span>
            <span style="display: block; text-align: end; width: 120px; margin-top: 10px;">
              Please select a different currency.
            </span>`
          return null
        }
        if (
          convertedAmountResponse &&
          !convertedAmountResponse.includes(selectedCurrencyCode)
        ) {
          console.error(
            '===forex converted amount is different than selected amount'
          )
          document.getElementById('currency-conversion-value').style.display =
            'flex'
          document.getElementById(
            'converted-amount-value'
          ).innerHTML = `<span style="display: block; text-align: end;">${convertedAmountResponse}</span>
            <span style="display: block; text-align: end; width: 120px; margin-top: 10px;">
              Couldn't convert to selected currency, Showing converted amount in your local currency. Please select a different currency.
            </span>`
          return null
        }
        document.getElementById('currency-conversion-value').style.display = 'flex'
        document.getElementById('converted-amount-value').innerHTML =
          convertedAmountResponse
        return convertedAmountResponse
      } catch (e) {
        console.error('===forex converted amount error', e)
        return null
      }
    }

    async function getSupportedCurrencies () {
      const currencyInput = document.getElementById('currency-list')
      let defaultCurrencyValue = merchantCurrency // define merchantCurrency - 1
      let isCurrencyListNull = true
      try {
        const { response: currencyListResponse, error } =
          await window.NI.handleGetSupportedCurrencies('currency-input', {
            style, 
            apiKey, 
            outletRef,
            merchantCurrency
          })
        if (currencyListResponse.currencyList) {
          const { currencyList } = currencyListResponse
          currencyList.forEach(currency => {
            const currencyOption = appendOptionInDropDown(currency)
            currencyInput.append(currencyOption)
          })
          defaultCurrencyValue = currencyList[0].currencyCode
          isCurrencyListNull = false
        }
        if (
          (currencyListResponse.currencyList &&
            currencyListResponse.currencyList.length === 0) ||
          !currencyListResponse.currencyList ||
          error
        ) {
          const currencyOption = appendOptionInDropDown(defaultCurrenyOption)
          currencyInput.append(currencyOption)
          if (error) console.error('===currency list error', error)
        }
      } catch (e) {
        console.error('===currency list error', e)
        const currencyOption = appendOptionInDropDown(defaultCurrenyOption)
        currencyInput.append(currencyOption)
      }
      document.getElementById('currency-list').value = defaultCurrencyValue
      if (!isCurrencyListNull) {
        getConvertedAmountForCurrency() // call forex currency conversion when currency list been shown
      }
    }

    // mount card and fetch  all the supported currencies
    window.onload = function () {
      window.NI.mountCardInput('mount-id' /* the mount id*/, {
        style, // Style configuration you can pass to customize the UI
        apiKey, // // Hosted Session Key which is used to generate Session ID
        outletRef, // outlet reference from the portal
        onSuccess: getSupportedCurrencies, // Success callback if hostedSessionApiKey validation succeeds
        onFail: () => {},
        onChangeValidStatus: () => {}
      })
    }
    </script>
</html>