Held Rate

Lock an FX rate for an extended window of 20–30 minutes, allowing you to display a guaranteed local currency price to an end customer before payment is collected. Designed for e-commerce checkout flows where there is a gap between the customer confirming a price and funds being received.

⚠️

Custom setup required

Held Rate is a pre-agreed commercial feature and is not available by default. Contact your account manager or sales representative to enable this for your account before integrating into sandbox or production

How it works

1. At checkout, call the Quote API to get a locked rate for your agreed window (20 or 30 minutes)
2. Display the guaranteed local currency price to your end customer
3. Customer completes payment
4. Once payment is confirmed, book the trade using the stored vfxToken
5. Fund the trade — Verto executes the conversion and settles into your wallet

The API flow is the same regardless of whether payment is collected via card authorisation or bank transfer — get the quote, hold the rate, book once payment is confirmed.

📘

Pricing

A transparent risk premium is applied based on the agreed rate hold duration:

• 20-minute hold: 0.2% premium
• 30-minute hold: 0.3% premium

This is pre-agreed as part of your commercial setup. Speak to your sales/account manager for details.

Step 1 — Get a quote

Call the Get FX Rate endpoint. Your account will be pre-configured with the agreed quote duration. You must specify the amount, amount currency, and currencies.

{
  "paymentMode": "later",
  "currencyFrom": {
    "currencyName": "USD"
  },
  "currencyTo": {
    "currencyName": "NGN"
  },
  "amount": 500,
  "amountCurrency": "USD"
}

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

⚠️

Retain the vfxToken — it must be used to book the trade within the agreed window.

Once expired, a new quote must be requested and the customer must be shown an updated price.

Step 2 — Display the guaranteed price to your customer

Using the locked rate from Step 1, calculate and display the exact local currency amount your customer will pay. This price is guaranteed for the duration of the rate window.

Step 3 — Book the trade

Once your system confirms the customer's payment is successful, immediately call the Create FX Trade endpoint with the stored vfxToken.

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

⚠️

Important

Only book the trade after you have confirmed the customer's payment. Once a trade is booked it cannot be cancelled. Do not book speculatively before payment is confirmed.

Step 4 — Fund and settle

Ensure the collected funds reach Verto within the agreed rate window. Once received, Verto will execute the conversion and settle the hard currency amount into your wallet.

This can be done via either instant, or later methods. For more details check Instant Settlement and Firm Orderfor more details.

Payment statuses

API response states

Webhook transaction states