Using Multi-Currency Pricing with the Web SDK
Add multi-currency pricing (MCP) to your N-Genius Online Web SDK integration so customers can choose their payment currency.
Before you startIntegrate the Web SDK by following the Web SDK integration guide before adding MCP.
Step 1: Retrieve available currencies
Enable MCP for your integration. During testing, set isMCPEnabled to true to enable MCP or false to disable it in your server script:
const isMCPEnabled = true;Define the appendOptionInDropDown function:
function appendOptionInDropDown(currency) {
const option = document.createElement('option');
option.value = currency.currencyCode;
option.text = currency.currencyCode;
return option;
};Create a currency dropdown (select) in your user interface (UI). Bind the Network International Web SDK's getSupportedCurrencies() method to this input.
Example:
<select class="currency-list" id="currency-list">
<option value="" disabled>Select Currency</option>
</select>async 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 example inserts currencies from the N-Genius API response as option elements in the dropdown.
The following image shows a sample currency response:
Inspect the error handling in getSupportedCurrencies():
- Check the logged errors when the API call or subsequent processing fails.
- Use the merchant currency as the fallback when retrieval fails. This allows payment processing without foreign exchange (FX) conversion.
Step 2: Convert the payment amount
After retrieving the supported currencies, convert the customer's basket amount.
Use getConvertedAmountForCurrency() to retrieve the converted payment amount for the selected currency. This method calls the N-Genius FX lookup APIs through the Network International SDK.
Bind getConvertedAmountForCurrency() to the dropdown created in step 1:
<select
class="currency-list"
id="currency-list"
onchange="payment.getConvertedAmountForCurrency()">
<option value="" disabled>Select Currency</option>
</select>The onchange="payment.getConvertedAmountForCurrency()" handler runs each time the customer selects a currency.
The method sends the dropdown value to the N-Genius FX API. The API returns the converted amount value in the customer's chosen currency.
Add the display elements to index.html:
<div id="currency-conversion-value">
<span class="">Converted Amount</span>
<span class="" id="converted-amount-value"></span>
</div>Add the display styles to index.css:
#currency-conversion-value {
display: none;
flex-direction: row;
padding: 10px 0;
margin-bottom: 25px;
justify-content: space-between;
}Use the following function to retrieve and display the converted amount:
async function 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:
Handle minor unitsThe N-Genius APIs represent currency amounts in minor units. For example,
10000fils represents AED 100.00. Display amounts according to the customer's local conventions.AED uses two decimal places. Other currencies use different numbers of decimal places. Read
minorUnitsin each currency block to determine the correct number.Incorrect formatting can cause customers to pay more or less than expected, or cause the transaction to fail.
Step 3: Complete the payment in the chosen currency
Process the payment in the customer's chosen currency.
Always offer customers the option to pay in the default payment currency. For UAE integrations using AED, label AED and every alternative currency clearly at checkout.
Follow step 4 onwards in the Web SDK integration guide. Include the customer's chosen currency value in the API call from your server to N-Genius.
Add a payment block to the server request:
{
"action": "PURCHASE",
"amount": {
"currencyCode": "AED",
"value": 100
},
"payment": {
"currency": "USD"
}
}The original amount is 100 fils, or AED 1.00. The payment.currency value selects USD as the target currency.
Optional: Sample code
Replace API_KEY with the hosted session API key used by your Web SDK integration. Replace OUTLET_REF with your outlet reference from the N-Genius Online portal.
The sample uses GBP as the merchant currency. Its orderAmount value of 100 represents 100 pence, or GBP 1.00.
<!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>Updated 12 days ago

