▶ 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:

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 - this field isn't returned unless off-market requests have been enabled by Nium. Please note 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 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.

StateDescription
CreatedAll conversions are initially in this state after you've initiated them. All conversions in this state can be canceled through the API.
ProcessingAt the scheduled time, conversions briefly go into this state while Nium settles them.
CompletedWhen conversions are successfully settled, and the wallet balances are updated, the conversions go into this state.
CancelledWhen conversions are canceled, either by Nium or by you, they go into the canceled state.

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.

A diagram showing the transfer using a prefunded balance.

A diagram showing the conversion using a prefunded balance.

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.

A diagram showing a scheduled FX transfer.

A diagram showing a scheduled FX conversion.

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.

Location — a regulatory region associated with the clientTime zoneSettlement cutoff — local time
Nium USUTC-85 PM
Nium HKUTC+85 PM
Nium SGUTC+85 PM
Nium EUUTC+15 PM
Nium AUUTC+115 PM
Nium UKUTC+15 PM

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.

Nium locationsSupportSource currenciesDestination currencies
USYesAll payin currencies supported for your account, as supported in this Nium locationAll payout currencies
UKYesAll payin currencies supported for your account, as supported in this Nium locationAll payout currencies
EUYesAll payin currencies supported for your account, as supported in this Nium locationAll payout currencies
AUYesAll payin currencies supported for your account, as supported in this Nium locationAll payout currencies
SGYesAll payin currencies supported for your account, as supported in this Nium locationAll payout currencies
HKYesAll payin currencies supported for your account, as supported in this Nium locationAll payout currencies

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:

HTTP methodAPI nameAction
GETExchange Rate V2This API fetches the interbank FX rate between a pair of currencies. This does not include the Nium markup.
GETAggregated Exchange RatesThis API fetches the historic interbank FX rates between a pair of currencies, for a specified date range within the last ninety days. This is set to provide daily aggregated interbank FX rates as the default, but can also be set to provide hourly aggregated data.

FX quotes:

HTTP methodAPI nameAction
POSTCreate QuoteThis API creates an FX quote for a pair of currencies based on your desired lock period and conversion schedule. The FX rate provided in this API includes the Nium markup and it can be used in any FX conversion within the quote's validity period.
GETFetch Quote by IDThis API fetches the details of an FX quote using the quoteId returned when the FX quote is created.

📌

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:

HTTP methodAPI nameAction
POSTCreate ConversionThis API converts funds within a customer's wallet from a source currency to a destination currency at either a market FX rate or a locked FX rate obtained using the FX Quote API.
GETFetch Conversion by IDThis API fetches the details of an FX conversion using the conversionId returned when the FX conversion was created.
POSTCancel ConversionThis API cancels an FX conversion that's in the created state and is yet to be settled.
POSTManual ConversionThis API executes an FX conversion and updates the state to processing.

Related Guides

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