Exchange logic

Convert funds between wallets or into payout destinations with the merged Exchange service, then track each FX trade through settlement.

✅

Multi-Mode Execution

Use exchange flows for immediate execution or booked-rate settlement across the API-supported modes.

✅ Before you exchange funds

Complete these steps before you execute an FX trade:

1. Make sure the source wallet exists and has enough available balance.
2. Confirm the target currency and destination: another wallet or a beneficiary account.
3. Decide whether the trade should use immediate or later settlement pricing.
4. Request an FX rate, capture the returned vfx_token, and create the trade before the token expires.
5. Store your paymentId and the returned FX trade reference for reconciliation.

Send Exchange requests to the sandbox host: https://api-exchange-now-sandbox.vertofx.com.

📑 Table of Contents

1. Execution modes
2. Workflow: quote to execution
3. FX markup configuration
4. Track and reconcile trades

⚡ Execution Modes

Use paymentMode to choose the settlement option for the FX rate and trade.

immediate

Use immediate when you intend to settle instantly. For wallet-funded trades, funds are deducted from the source wallet.

later

Use later when you intend to settle Verto later, up to 24 hours after requesting the rate.

Confirm your operational process can settle within the expected window before using later settlement pricing.

🚀 Workflow: Quote to Execution

To minimize slippage, follow the quote-lock-execute pattern.

1. Fetch rate: Use Get FX rate to get the current rate for currencyFrom, currencyTo, and paymentMode.
2. Lock rate: Capture the returned vfx_token; it expires after approximately 30 seconds.
3. Execute trade: Use Create FX trade before the token expires.
4. Track status: Use Get FX trade details with the returned trade reference or paymentId.

{
  "paymentType": "convertWithinWallets",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "vfx_Token": "uciebcjdencijwnciqnq832982jhbj3eduh3",
  "targetWalletId": 23181,
  "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f"
}

If the token expires, request a fresh rate before retrying the conversion. Do not create a new trade with an expired vfx_token.

Use Get bulk FX rates when you need to compare multiple currency pairs before choosing a trade route.

🔬 Atlas Pricing Nuances

💹 FX Markup Functionality

Configure company-level FX markup rules for supported FX flows.

Use Set FX markup configuration to set a universal markup or a currency-pair-specific markup. Use Get FX markup configuration to inspect active markup rules.

The merged Exchange service supports these configuration types:

• Universal markup: Set a markup percentage that applies generally for the company.
• Currency-pair markup: Set a markup percentage for a specific currencyFrom and currencyTo pair.

📋 Prerequisites

Before integrating the FX Markup endpoints, ensure you possess:

1. A valid bearer token for the Exchange service.
2. Permission to set or retrieve FX markup configuration for the company.
3. The markup type you want to configure: universal or currency_pair.
4. A markupPerc value between 0 and 10.

🔧 Step-by-Step Implementation

All API requests require bearer authentication using your generated credentials.

Set a universal markup

Use markupType: "universal" when the markup should apply generally for the company.

curl --request POST \
  --url https://api-exchange-now-sandbox.vertofx.com/fx/markup/config \
  --header 'Authorization: Bearer <SECURE_REDACTED_API_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "markupType": "universal",
    "markupPerc": 1.5
  }'

Set a currency-pair markup

Use markupType: "currency_pair" when the markup should apply only to a specific source and target currency pair.

curl --request POST \
  --url https://api-exchange-now-sandbox.vertofx.com/fx/markup/config \
  --header 'Authorization: Bearer <SECURE_REDACTED_API_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "markupType": "currency_pair",
    "markupPerc": 2.5,
    "currencyFrom": "USD",
    "currencyTo": "NGN"
  }'

🔀 The Suggested Implementation Workflow

To ensure your customers see consistent pricing, use the quote-to-execution pattern:

1. Configure markup: Set the universal or currency-pair markup with Set FX markup configuration.
2. Verify configuration: Retrieve the current rule with Get FX markup configuration.
3. Quote: Call Get FX rate to fetch the rate and vfx_token for the customer’s currency pair.
4. Execute: Create the trade with Create FX trade before the vfx_token expires.

⚡ Convert and pay out

Use paymentType: "convertWalletPayout" when you want to convert wallet funds and send the converted funds to a beneficiary account.

curl --request POST https://api-exchange-now-sandbox.vertofx.com/fx/payments \
  -H "Authorization: Bearer <SECURE_REDACTED_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentType": "convertWalletPayout",
    "sourceWalletId": 11435,
    "sourceAmount": 4800,
    "purposeId": 45,
    "vfx_Token": "<YOUR_VFX_TOKEN>",
    "targetAccountId": 839,
    "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f"
  }'

Use paymentType: "convertWithinWallets" when you want to convert funds from one wallet into another wallet.

Track and reconcile trades

Store these values for reconciliation and support workflows:

Use List FX trades for operational reporting and Get FX trade details when you need the latest state for one trade. **

🎯 Next Steps