Instant FX

Convert funds between wallets immediately using a pre-funded balance. This is the standard flow for automated payment workflows and Global Clearing payouts where funds are already on balance.

How it works

Get a live quote for your currency pair
Book the trade using the returned vfxToken — funds are debited from your wallet instantly at the locked rate

Step 1 — Get a quote

Call the Get FX Rate endpoint with paymentMode set to immediate. You must specify the amount, amount currency, and currencies.

{
  "paymentMode": "immediate",
  "currencyFrom": {
    "currencyName": "USD"
  },
  "currencyTo": {
    "currencyName": "KES"
  },
  "amount": 5000,
  "amountCurrency": "USD"
}

Field	Description	Mandatory
`paymentMode`	Must be `immediate` for Instant FX	Yes
`currencyFrom.currencyName`	The currency you are selling	Yes
`currencyTo.currencyName`	The currency you are buying	Yes
`amount`	The amount to convert	Yes
`amountCurrency`	The currency the amount refers to — either `currencyFrom` or `currencyTo`	Yes

The response returns a rate, an expiry time, and a vfxToken that locks the quote.

{
  "rate": 0.00167025,
  "vfxToken": "eyJhbGci...",
  "expiry": "2024-05-10T10:22:49.994Z",
  "success": true
}

⚠️
Quote expiry
Instant FX quotes are valid for 30 seconds. You must book the trade within this window or the quote will expire and a new one must be requested.
This can be extended in specific situations up to 120 seconds, reach out for more information.

Step 2 — Book the trade

Call the Create FX Trade endpoint with the vfxToken from Step 1. Your sourceWalletId must hold sufficient balance in the currencyFrom currency before booking.

{
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 11435,
  "sourceAmount": 5000,
  "purposeId": 14,
  "vfxToken": "eyJhbGci...",
  "customPaymentReference": "your-reference",
  "targetAccountId": 23181,
  "paymentId": "a7c01c2d-f677-41d8-a11c-4d66804669f4"
}

Field	Description	Mandatory
`paymentType`	Must be `convertWalletPayout`	Yes
`sourceWalletId`	Wallet ID to debit in `currencyFrom`	Yes
`sourceAmount`	Amount to convert — must match the amount from Step 1	Yes
`purposeId`	Purpose of payment code	Yes
`vfxToken`	Token returned from Step 1	Yes
`customPaymentReference`	Your own reference for the transaction	No
`targetAccountId`	Wallet or beneficiary ID to credit in `currencyTo`	Yes
`paymentId`	Unique UUID for idempotency	Yes

💡
Confirm your wallet balance before booking using the [Get Wallet](https://docs.verto.co/v1.1/update/reference/get_specific_wallet_details endpoint.

Payment statuses

API response states

State	Description
`confirmed`	Trade placed successfully and source wallet debited.
`inwardSettlementDone`	FX leg settled. Converted funds available in target wallet.
`outwardSettlementDone`	Trade fully complete.
`archived`	Trade cancelled.
`refunded`	Trade refunded and funds returned to source wallet.

Webhook transaction states

`transactionState`	Description
`inward_remittance_confirmed`	Source wallet debited and trade confirmed.
`outward_remittance_complete`	Converted funds settled into the target wallet.