Overview

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 amount can then be used to send payouts or spend through a card.

Key concepts

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

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 historic minimum, maximum and average FX rates for a currency pair within hourly or daily intervals.

Quote

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

Nium performs an FX conversion when funds are converted from the funding source currency to the destination currency within the customer’s wallet using locked or market FX rates. You can use these converted funds to make payouts to external bank accounts as needed. For example, a payroll provider in the US that wants to pay employees in Canada may first convert their USD funds into CAD ahead of the payroll schedule. Then, they could make payouts to all employee accounts from the CAD balance on the payroll date.

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.

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.

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.

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

Conversion life cycle

A conversion typically goes through 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.

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.

Related guides

Use the following related guides to implement some of the common use cases using the FX APIs: