FX conversion settled immediately using locked rate

If you want to get a confirmation from your customer or an internal user for the FX rate before you complete the FX conversion using available funds in the customer wallet, you can first get the FX quote and then initiate the conversion using that quote as below:

Step 1: Get an FX quote

Get an FX quote with the lockPeriod required to confirm the conversion with your customer or user and the conversionSchedule as immediate and quoteType as balanceTransfer.

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": "immediate",
    "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_4VmJfRsR2ZMKbJKf4Po1CX",
    "netExchangeRate": 1.447457500,
    "expiryTime": "2023-06-15 14:47:38",
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "AUD",
    "quoteType": "balanceTransfer",
    "conversionSchedule": "immediate",
    "lockPeriod": "8hours",
    "exchangeRate": 1.469500000,
    "markupRate": 0.022042500,
    "sourceAmount": null,
    "destinationAmount": null,
    "destinationMarkupAmount": null,
    "createdTime": "2023-06-15 06:47:38"
}

Step 2: Create the conversion

Once you get the quote, create the conversion as follows before the expiryTime.

Send the quoteId obtained in the above API and one of the destinationAmount or sourceAmount depending on which side 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_4VmJfRsR2ZMKbJKf4Po1CX"
    "sourceAmount": "100",
    "comments": "Converting for AUD payroll"
}'

Step 3: Get the response

You get an initial response that shows the calculated destinationAmount or sourceAmount and the status as created.

{
    "id": "conversion_3YJoJvSsvPFZqlwsLhnnSc",
    "status": "processing",
    "conversionTime": "2023-06-15 06:48:56",
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "AUD",
    "sourceAmount": 100,
    "destinationAmount": 144.75,
    "quoteId": "quote_4VmJfRsR2ZMKbJKf4Po1CX",
    "netExchangeRate": 1.447457500,
    "exchangeRate": 1.469500000,
    "markupRate": 0.022042500,
    "destinationMarkupAmount": 2.2,
    "systemReferenceNumber": "WFT1968043576",
    "customerComments": "Transfering for AUD payroll",
    "createdTime": "2023-06-15 06:48:56",
    "updatedTime": "2023-06-15 06:48:56"
}

Step 4: Get the notification when the conversion is settled

Since this is a conversion that's settled immediately using the available balance, the balances in the wallet are updated and you immediately receive a webhook notification that shows the new status as completed.

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