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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 client||Time zone||Settlement cutoff — local time|
|Nium US||UTC-8||5 PM|
|Nium HK||UTC-8||5 PM|
|Nium SG||UTC-8||5 PM|
|Nium EU||UTC+1||5 PM|
|Nium AU||UTC+1||5 PM|
|Nium UK||UTC+1||5 PM|
A conversion typically goes through the following states:
|Created||All conversions are initially in this state after you've initiated them. All conversions in this state can be canceled through the API.|
|Processing||At the scheduled time, conversions briefly go into this state while Nium settles them.|
|Completed||When conversions are successfully settled, and the wallet balances are updated, the conversions go into this state.|
|Cancelled||When conversions are canceled, either by Nium or by you, they go into the canceled state.|
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.
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.
The Nium FX service is available to clients onboarded with the following Nium locations.
|Nium locations||Support||Source currencies||Destination currencies|
|US||Yes||All payin currencies supported for your account, as supported in this Nium location||All payout currencies|
|UK||Yes||All payin currencies supported for your account, as supported in this Nium location||All payout currencies|
|EU||Yes||All payin currencies supported for your account, as supported in this Nium location||All payout currencies|
|AU||Yes||All payin currencies supported for your account, as supported in this Nium location||All payout currencies|
|SG||Yes||All payin currencies supported for your account, as supported in this Nium location||All payout currencies|
|HK||Yes||All payin currencies supported for your account, as supported in this Nium location||All payout currencies|
Use the following host names to distinguish the API calls between the different working environments.
|HTTP method||API name||Action|
|GET||Exchange Rate V2||This API fetches the interbank FX rate between a pair of currencies. This does not include the Nium markup.|
|HTTP method||API name||Action|
|POST||Create Quote||This 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.|
|GET||Fetch Quote by ID||This API fetches the details of an FX quote using the |
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.
|HTTP method||API name||Action|
|POST||Create Conversion||This 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.|
|GET||Fetch Conversion by ID||This API fetches the details of an FX conversion using the |
|POST||Cancel Conversion||This API cancels an FX conversion that's in the |
Use the following related guides to implement some of the common use cases using the FX APIs:
Updated 2 months ago