FX Markup Functionality

The FX Markup API empowers Partners to effortlessly automate revenue sharing. By applying a structured margin to the base Verto exchange rate for your Sub-Accounts, you gain programmatic control over your profitability.

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

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

💡 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.

🛰️ The Suggested Implementation Workflow

To ensure your customers see consistent pricing, we recommend this two-step "Quote-to-Execution" pattern:

1. The 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. The Execution Stage: Pass that same fxMarkup percentage into the /fx/payments execution call. Verto will perform the same calculation on our backend, ensuring the final settled amount matches exactly what your customer was shown.

🛠️ Step-by-Step Implementation

All API requests require robust 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 automatically pads every sub-account foreign exchange request behind the scenes.

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. You can dynamically execute custom markups at the exact moment of execution by passing an explicit fxMarkup object directly inside your /fx/payments execution payload.

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
    }
}'

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

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

• To Fix Source (Fix Sell): Populate sourceAmount. You define what you want to spend; the recipient receives the remainder after fees and markup.
• To 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.

✅ 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.

⏭️ Next Configuration Steps