FX Markup Functionality

💹 FX Markup Functionality

Use FX markups to define the customer-facing exchange rate for sub-account flows and apply your margin on top of the base Verto rate.

✅ Before you start

Complete these steps before you configure FX pricing:

1. Confirm you are operating an Atlas account with markup access enabled.
2. Make sure you already understand the core quote and conversion flow in FX Conversion Guide.
3. Decide whether your pricing model should be global, corridor-specific, or per-trade.
4. Define how your application will store and audit the configured markup used for each customer-facing rate.

The FX Markup API lets partners apply a structured margin to the base Verto exchange rate for downstream customer flows so pricing and margin capture can be managed programmatically.

We offer three integration paths to accommodate your exact commercial model:

• Universal Markup Model: Set a static margin percentage across all transactions statefully.
• DynamicMargin Model (currency_pair): Inject custom spreads per individual currency route statefully.
• Trade-by-Trade Execution: Pass an explicit fxMarkup object dynamically per transaction payload for absolute precision.

Choose the markup model that fits your pricing strategy

💡 Core Value Proposition

• Automated Profitability: Systematically capture the spread without delayed manual reconciliation.
• Absolute Flexibility: Switch between continuous state models and trade-by-trade overrides instantly.
• Real-Time Calculation: Client Rates are instantly generated upon request, guaranteeing zero latency.

📐 How Markup Revenue is Calculated

When a margin is applied to a currency exchange, a new Client Rate is dynamically executed.

📋 Prerequisites

Before integrating the FX Markup endpoints, ensure you possess:

1. An active Atlas for Platforms production account.
2. A valid, secure API Key provisioned with Markup Control scoping.

Use sandbox to validate your pricing logic first, then move the same model into production only after the account-level capability is approved.

🔧 Step-by-Step Implementation

All API requests require Bearer authentication using your generated credentials.

Option 1: Stateful Universal & Dynamic Configurations

Ideal for standard marketplace deployments. You push a configuration payload to the /fx/markup/config endpoint, and Verto applies that markup automatically to matching downstream FX requests.

# Stateful Universal Configuration
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
  }'

Option 2: Trade-by-Trade Execution (Granular Overrides)

Ideal for high-precision brokerage or custom-priced flows. Pass an explicit fxMarkup object directly inside the /fx/payments execution payload when one transaction should override the default pricing model.

# Per-Trade Explicit Payload Modifier
curl --request POST \
  --url https://api-exchange-now-sandbox.vertofx.com/fx/payments \
  --header 'Authorization: Bearer <SECURE_REDACTED_API_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "paymentType": "convertWalletPayout",
    "sourceWalletId": 11435,
    "sourceAmount": 4800,
    "vfxToken": "<YOUR_VFX_TOKEN>",
    "targetAccountId": 23181,
    "fxMarkup": {
      "markupType": "currency_pair",
      "markupPerc": 2.5
    }
  }'

🔀 The Suggested Implementation Workflow

To ensure your customers see consistent pricing, use the Quote-to-Execution pattern:

1. Quote Stage: Call the Get Rate (New) API to fetch the authoritative Verto rate token. On your own system, calculate your final "Client Rate" by adding your desired margin to the Verto rate, then display it in your checkout UI.
2. Execution Stage: Pass that same fxMarkup percentage into the /fx/payments execution call. Verto will perform the same calculation on their backend, ensuring the final settled amount matches exactly what your customer was shown.

If you support customer-visible quoting, keep the quote and execution paths aligned so the final trade reflects the price shown in your UI.

✝️ Controlling the "Fix Side" (Buy vs. Sell)

The Exchange Service API handles "Fixing" based on which volume parameter you populate in the payload:

• Fix Source (Fix Sell): Populate sourceAmount. You define what you want to spend; the API calculates the recipient amount accordingly.
• Fix Target (Fix Buy): Populate targetAmount. The API ensures the recipient receives exactly this volume (e.g., exactly 1,000 EUR) and calculates the necessary wallet deduction accordingly.

📌 Markup Hierarchy & Precedence

To ensure absolute flexibility, Verto uses a "Specific-Wins" logic:

1. Global/Corridor Levels: Used as the DEFAULT base for all sub-account trades.
2. Trade-Level Override: If you pass an fxMarkup object in your /fx/payments call, it overrides any existing defaults. This allows you to differentiate pricing for specific high-value trades or promotional cohorts.

In practice, this means your application should always know whether the current trade is using inherited markup or an explicit override.

✅ Verifying Transaction Margins

Once a trade is created, the 200 OK response from the Create FX Trade endpoint includes clear auditing fields to simplify your reconciliation.

Troubleshooting

Next steps