Overview

▶ Run in Postman

Nium's Foreign Exchange (FX) service helps you convert your funds from any of the Nium Payin currencies into any of the Nium Payout currencies at transparent and guaranteed FX rates. The converted funds can then be used to send payouts or spend through a card.

Before diving into the details of the FX service and the API endpoints, it's important to understand the main aspects of any FX conversion.

Rate

▶ Run in Postman

The FX rate for a given currency pair is the rate at which banks trade that currency pair in the interbank currency market. Nium provides these rates to you for informational purposes, for example, if you want to track general market trends. Nium retrieves FX rates for all supported currency pairs every five minutes. We also offer the ability for you to transparently track the historical minimum, maximum, and average FX rates for a currency pair within hourly or daily intervals.

Off-Market Rates

Some quotes and conversion requests made outside of normal business hours can trigger Off-market rates. This includes:

• Requests made outside the normal operating hours for the markets involved.
• Weekends
• Holidays

These off-market requests return a isOffMarket field in the response of our Quotes and Conversions endpoints. Specifically, the isOffMarket field can be found in the response of the following requests:

• Create Quote
• Fetch Quote by ID
• Create Conversion
• Fetch Conversion By Id

The isOffMarket field returns true if an off-market fee has been applied. Off-market requests are enabled if discussed with your Nium Account manager during onboarding. Please note, this field isn't returned unless off-market requests have been enabled by Nium. Off-market rates only apply to:

• Quotes with 5-minute lock periods
• Immediate Conversions

If you have any questions on what qualifies as off-market, please contact your Nium Account Manager or Nium Support for more information.

Quote

▶ Run in Postman

An FX quote is an offer Nium makes to convert money across two currencies at a locked FX rate within a limited time frame. The quote is generated by taking the latest interbank FX rate for the two currencies and adding a previously agreed markup to it. On holidays, Nium uses the last traded interbank FX rate from the previous close-of-business day as the baseline. An example would be a Friday closing rate, which becomes the quote generated on a Sunday after adding the Nium markup.

Lock Periods

All FX quotes can be locked for a period of time to allow you time to show the locked rate to your users (internal or external) and make a decision about making an FX conversion at that locked rate. We support different lock periods ranging from 5 minutes to 24 hours, and you can choose to select the required lock period every time you get a quote from Nium using the FX Quote API. The lock periods supported are as below.

📌

Important

The longer the rate lock period, the higher is the Nium markup.

• 5 minutes (default)
• 15 minutes
• 1 hour
• 4 hours
• 8 hours
• 24 hours

When you get an FX quote, you also need to separately select a conversion schedule, which identifies the time you will need to settle the FX conversion. This is explained in the sections below.

Conversion

▶ Run in Postman

Nium performs an FX conversion when funds are converted from the funding source currency to the destination currency in a customer's wallet. FX conversions can be performed using either locked or market FX rates.

Clients can use these converted funds to make payouts to external bank accounts depending on their business needs.

For example, a payroll provider in the US can pay their employees in Canada by converting their USD funds into CAD ahead of the payroll schedule. The US payroll provider can then make payouts to their Canadian employees from their CAD balance on the payroll date.

Clients can also execute scheduled FX conversions manually. Using manually scheduled FX conversions, clients can transfer funds from a source currency to a destination currency based on their settlement schedule needs. Manual conversions add more flexibility compared to timed conversions, which get executed at the settlement cut-off time.

At the same time, in the same payroll example, clients can also control the timing of an FX conversion and when the conversion from USD to CAD is executed based on the funds arriving in their wallet. Please note manual FX conversions only apply when the settlement schedule is not immediate.

Timed Conversions

By default, FX conversions are configured to execute at the conversionTime. The conversionTime is calculated based on the settlement cut-off time.

The conversionTime defines the time funds in the customer's wallet get converted from the source currency to the destination currency. This is helpful in instances where your internal workflow supports the automated processing of FX conversions at a predetermined schedule.

Manual Conversions

You can also manually execute FX conversions to control the timing of FX conversions to be settled in wallet. This is valuable in case of additional control of funds in wallet, where only the intended “source” funds are converted, and also the timing of conversions.

Use executionType#manual to execute an FX conversion; once executed, the conversion#status updates from created to processing. For more information, see Execute Conversion.

Conversions During Payouts

Nium can also perform an FX conversion during an individual payout, either using a locked or the market FX rate. You can instruct Nium to deduct funds from the wallet in the source currency and send the payout in the destination currency to your beneficiary’s account through Nium's payout network.

📌

IMPORTANT

The locked FX rate functionality for payouts is supported through the Exchange Rate Lock And Hold API. Refer to the Audit ID section of the Transfer Money guide for more information.

Conversion Schedule

You can select the preferred conversion schedule from the list below. This determines the time Nium waits to settle the conversion.

Immediate: An immediate conversion schedule is settled instantly using the available balance in the customer's wallet. This can be done 24 hours a day, seven days a week, regardless of whether it's a working day or not.

endOfDay: An end-of-day conversion schedule is settled at the end of the present day, regardless of whether the present day is a holiday or not. This is a slight variation from an immediate conversion schedule. It gives you some time to fund the source account.

nextDay: A next-day conversion schedule is settled one business day later. This excludes holidays in the country of either the source currency, the destination currency, or the Nium regulatory region where you have been onboarded. For example, if a next-day FX conversion is initiated on a Monday for USD-GBP, and Tuesday is a holiday in the UK, and Wednesday is a holiday in the US, the FX conversion settles on Thursday, which is the next business day for the given currency pair. In this case, it doesn't matter whether Monday itself is a holiday or not in any of the zones.

twoDays: A two-day conversion schedule is similar to a next-day conversion schedule, except that it settles two business days later, excluding holidays.

Based on the conversion schedule, Nium calculates the conversion time and provides it in the response to the conversion creation request, so you know exactly how much time you have to fund the source account.

Conversion Lifecycle

FX conversions have the following states.

See the following diagram for an overview of the states an FX conversion typically goes through.

Settlement

All FX conversions need to be settled when the source funds are available. This is the last step in the FX conversion process. Nium performs the conversion and updates the balances in the customer's wallet.

Immediate Settlement

If you already have the source funds in the customer's wallet, then FX conversions can be settled immediately using the pre-funded balance. Such conversions are done at any time, 24 hours a day, seven days a week, on demand. These are usually done using a market FX rate.

Scheduled Settlement

If you want to fund the source amount in the customer's wallet after first getting a locked FX rate, then it's possible to settle FX conversions later on a scheduled date. This gives time to deposit the source funds into the customer's wallet.

You need to first get an FX quote for the specific conversion schedule. The times are the end of the day, the next business day, or two business days. This is necessary to allow you time to deposit the source funds. This depends on the funding method such as Direct Debit from your external account, a wire transfer to a Nium virtual account, or an Automated Clearing House (ACH) credit to a Nium virtual account.

Settlement Cut-Off Time

The settlement is done on the scheduled date—calculated according to the conversion schedule—at a specific cut-off time that's based on the Nium regulatory region that you have been onboarded with. This gives you until the end of the business day to fund the source funds.

Key Features

To summarize, here are the key features of Nium's FX service:

• Transparency: Nium bases all of its FX quotes on the live interbank FX rate and adds a transparent mutually agreed-upon FX markup.
• 24 hours a day, seven days a week availability: Nium's FX service is available daily around the clock with no downtime on bank holidays or weekends.
• Flexibility: You can choose to convert and hold currencies within your wallet to enable payouts or card spending, or perform conversion across currencies dynamically as a part of the individual payout or card spend transaction.
• Locked rates: Get locked FX rates to give your customers time to review and confirm the rate.
• Multiple settlement options: Choose between converting funds in real-time using pre-funded balances, or converting on a future scheduled date, at a locked FX rate. This helps you know the exact source amount to fund and get the time to send the funds.

Prerequisites

These are the requirements for using the FX service:

• Create a corporate customer and a multicurrency wallet for yourself, if you're a direct client, or for each one of your customers, if you're a platform.
• Set up the wallets to support the required currencies.
• Work with your account representative to ensure that your account is setup with the agreed FX markups for the lock periods and conversion schedules that you need to support for your business model.

Availability

The Nium FX service is available to clients onboarded with the following Nium locations.

API Server URLs

Use the following host names to distinguish the API calls between the different working environments.

• Sandbox: https://gateway.nium.com
• Production: https://api.spend.nium.com

FX API Endpoints

FX rate:

FX quotes:

📌

IMPORTANT

The Create Quote API is only enabled for FX conversions within a customer's wallet. In the near future, the same API is planned to also support quotes for payouts. Until then, use the Exchange Rate Lock And Hold API to lock FX rates for payouts.

FX Conversions:

Related Guides

See the following for more details on using our FX service:

• FX conversion settled immediately using market rate
• FX conversion settled immediately using locked rate
• FX conversion scheduled for later settlement
• Scheduled FX conversion cancelled before settlement