FX conversion scheduled for later settlement

In scenarios where you prefer to fund the FX conversion later and want to know the amount to be funded upfront, you can get a locked FX rate using the desired lockPeriod and conversionSchedule. Using this locked FX rate, you can calculate the source amount that's needed to fund into your customer’s wallet.

Step 1: Get an FX quote

Get an FX quote with quoteType as balanceTransfer, the desired lockPeriod required to confirm the conversion with your customer or user and the conversionSchedule as one of endOfDay, nextDay, or twoDays, depending on how long it takes for your wallet to be funded with the source currency.

curl -X POST "https://apisandbox.nium.com/api/v1/client/{clientHashId}/quotes" \ 
-H "accept: application/json" \ 
-H "Content-Type: application/json" \ 
-d
'{
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "AUD",
    "conversionSchedule": "2Days",
    "lockPeriod": "8hours",
    "quoteType": "balanceTransfer"    
}'

In response, you get an FX quote with the netExchangeRate as the quoted exchange rate. This is calculated by getting the latest interbank rate for that currency pair—exchangeRate—and reducing the total markupRate that's configured for your account for the combination of the currency pair, lock period, and conversion schedule.

{
    "id": "quote_1GYLNle0hw37IkPDAuwOFQ",
    "netExchangeRate": 1.437366600,
    "expiryTime": "2023-06-15 14:52:54",
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "AUD",
    "quoteType": "balanceTransfer",
    "conversionSchedule": "2Days",
    "lockPeriod": "8hours",
    "exchangeRate": 1.469700000,
    "markupRate": 0.032333400,
    "sourceAmount": null,
    "destinationAmount": null,
    "destinationMarkupAmount": null,
    "createdTime": "2023-06-15 06:52:54"
}

Step 2: Initiate the conversion

Once you get the quote, you can create the conversion as follows within the expiryTime. Send the quoteId you received in the above API and either the destinationAmount or sourceAmount depending on which one you want to be fixed. Nium calculates the other amount using the quoted FX rate.

curl -X POST "https://apisandbox.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/conversions" \ 
-H "accept: application/json" \ 
-H "Content-Type: application/json" \ 
-d
'{
    "quoteId: "quote_1GYLNle0hw37IkPDAuwOFQ"
    "sourceAmount": "100",
    "comments": "Converting for AUD payroll"
}'

Step 3: Get the response

Get an initial response that shows the calculated destinationAmount or sourceAmount, the calculated conversionTime, and the status as created.

{
    "id": "conversion_1xVFhcSSdFLAyoKb9bKofR",
    "status": "created",
    "conversionTime": "2023-06-21 01:00:00",
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "AUD",
    "sourceAmount": 100,
    "destinationAmount": 143.74,
    "quoteId": "quote_1GYLNle0hw37IkPDAuwOFQ",
    "netExchangeRate": 1.437366600,
    "exchangeRate": 1.469700000,
    "markupRate": 0.032333400,
    "destinationMarkupAmount": 3.23,
    "systemReferenceNumber": "WFT3169755752",
    "customerComments": "Converting for AUD payroll",
    "createdTime": "2023-06-15 06:53:32",
    "updatedTime": "2023-06-15 06:53:32"
}

Step 4: Fund the conversion

You need to fund the source amount into the customer's wallet before the conversionTime.

📌

IMPORTANT

Become familiar with the time it takes for funds to be available in the customer wallet. Nium can only complete an FX conversion when the funds are available. This includes the time it takes for the bank to settle the funds to Nium and any risk hold period set up for your account. Refer to the Fund Wallet guide to learn about funding methods and the time it takes for funds to be available.

Step 5: Get the conversion settlement notification

Nium converts the funds in your wallet at the settlement cut-off time according to the local time in the Nium entity that you have been onboarded for. Once Nium completes the conversion, you receive a webhook notification that shows the status as completed.

{
"customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250",
"template":"FX_CONVERSION_COMPLETED_WEBHOOK",
"systemReferenceNumber":"WFT3169755752",
"walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358",
"conversionId":"conversion_1xVFhcSSdFLAyoKb9bKofR",
"clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a",
"status":"completed"
}

Step 6: Handle a cancellation scenario

Alternatively, in case the funds are not in the customer's wallet at the conversionTime, Nium cancels the conversion and deducts the cancellation fee in the source currency from the wallet. Refer to the Scheduled FX conversion cancelled before settlement guide to understand how the cancellation fee is calculated.

You get the following webhook notification that shows the new status of the transfer as cancelled. The cancellationReason is always insufficient_funds in this scenario.

{
"customerHashId":"e9f74ac0-8fc5-4879-8ace-6ca2084ba250",
"template":"FX_CONVERSION_CANCELLED_WEBHOOK",
"cancellationFeeCurrencyCode":"USD",
"cancellationReason":"insufficient_fund",
"systemReferenceNumber":"7526349341F",
"cancellationComment":"Insufficient Funds",
"cancellationFee":5.82",
"walletHashId":"ebc26772-2d3e-4ab0-916a-3a7706a0c358",
"conversionId":"conversion_1xVFhcSSdFLAyoKb9bKofR",
"clientHashId":"8bf73eb1-99e7-4a76-8ef2-cdeac938593a",
"status":"cancelled"
}