Using MCP (Multi-Currency Pricing) with the WebSDK

📘
Before you start
This guide assumes that you have already integrated with the WebSDK component for N-Genius Online. If this is not the case, you should refer to Web SDK Integration Guide before attempting to further integrate the MCP feature of this service.

Step 1: Retrieve Available Currencies:

First, ensure that MCP is enabled for your integration, and can be switched on/off during testing by setting the relevant constant in your merchant server script:

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

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

Example:

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

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 drop down.

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: Currency Conversion

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.


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
Since the N-Genius Online APIs typically handle all currency amounts in minor units (i.e. 100.00 AED becomes a value of 10000, it is important to ensure that your UI can handle minor units effectively, and to the local conventions of the shopper.
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.
Failure to accommodate this in your UI is likely to result in shoppers paying more/less than expected for any given transaction, or in transaction failure altogether.

Step 3: Complete Payment with Chosen Currency

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

It is important to note, at this stage, that you must always provide an option for the card-holder to pay in the default merchant currency (likely AED for merchants operating in the UAE), and that all alternative currency payment options are clearly marked as such in your chosen UI design.

To complete the payment, please refer to Step 4 (onwards) from the Web SDK Integration Guidearticle, 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
      }
    }

Using MCP (Multi-Currency Pricing) with the WebSDK

📘
Before you start

Step 1: Retrieve Available Currencies:

Step 2: Currency Conversion

🚧
Handling Minor Units

Step 3: Complete Payment with Chosen Currency

📘Before you start

Step 1: Retrieve Available Currencies:

Step 2: Currency Conversion

🚧Handling Minor Units

Step 3: Complete Payment with Chosen Currency

📘
Before you start

🚧
Handling Minor Units