Payouts FX Control (Experimental)

Overview

Payout FX Control enables you to provide end users with an exact preview of the local currency amount they will receive before executing a payout. When sending funds from your wallet currency (such as USD, EUR, or GBP) to end users in local currencies across Latin America, you can now lock in the exchange rate and all associated fees, ensuring complete transparency and predictability.

Key Benefits

Guaranteed Payout Amounts: Lock FX rates and fees for 5 minutes, ensuring the exact amount quoted is what your end user receives
Complete Transparency: Show end users the precise local currency amount before they confirm the payout
Simplified Reconciliation: Detailed breakdown of exchange rates, spreads, and fees for accurate accounting
Improved User Experience: Eliminate surprises by providing certainty on payout amounts upfront

How It Works

Payout FX Control uses a two-step process to guarantee accurate payout amounts:

Step 1: Create a Payout Quote

Request a quote that locks in the current FX rate, spreads, and applicable fees. The quote is valid for 5 minutes and provides the exact local currency amount the end user will receive.

Step 2: Execute the Payout

Execute the payout using the quote ID. The system applies the exact rates and fees from the quote, guaranteeing the quoted amount.

Important: All fees, spreads, and taxes are deducted from your payout amount. The net payout amount is what gets debited from your wallet, and the local amount shown is what the end user will receive.

API Workflow

Step 1: Create a Payout Quote

Endpoint: POST /v2/payouts/quote

Create a quote to lock in FX rates and calculate the exact payout amount:

POST /v2/payouts/quote
{
  "amount": 1000.00,
  "currency": "USD",
  "country": "BR",
  "merchantSpreadPercent": 1.5
}

Request Parameters:

amount (required, decimal): The amount in your wallet currency
currency (required, string): Your wallet currency (ISO code)
country (required, string): Destination country (ISO code)
merchantSpreadPercent (optional, decimal): Your desired spread percentage

Response:

{
  "payoutQuoteId": "3a9e2f81-371d-40f0-b234-3a4d57f54a77",
  "createdAt": "2025-12-15T14:16:17.693008+00:00",
  "expiresAt": "2025-12-15T14:21:17.693008+00:00",
  "expiresInSeconds": 299,
  "country": "BR",
  "requestAmount": 1000,
  "requestCurrency": "USD",
  "targetCurrency": "BRL",
  "payoutChannel": "TRANSFER",
  "merchantSpreadPercent": 1.5,
  "fxBreakdown": {
    "exchangeRate": 5.39485,
    "components": {
      "merchantSpreadPercent": 1.5,
      "pspSpreadPercent": 2,
      "localTaxPercent": 0.38,
      "operationFeePercent": 0.5
    },
    "contexts": {
      "base": {
        "currency": "USD",
        "payoutAmount": 1000,
        "merchantSpreadAmount": 15,
        "pspSpreadAmount": 20,
        "localTaxAmount": 3.8,
        "operationFee": 5,
        "netPayoutAmount": 956.2
      },
      "local": {
        "currency": "BRL",
        "payoutAmount": 5394.85,
        "merchantSpreadAmount": 80.92,
        "pspSpreadAmount": 107.9,
        "localTaxAmount": 20.5,
        "operationFee": 26.97,
        "netPayoutAmount": 5158.56
      }
    }
  }
}

Key Fields:

payoutQuoteId: Unique identifier for the quote (use this in Step 2)
expiresAt: Quote expiration timestamp (5 minutes from creation)
fxBreakdown: Complete breakdown of the payout calculation

Step 2: Execute the Payout

Endpoint: POST /v2/payouts

Execute the payout using the locked quote by sending the new parameter payoutQuoteId

POST /v2/payouts
{
  "payoutQuoteId": "a24e2589-883a-45a2-93b4-e086b735c0c8",
  "amount": 1000.00,
  "currency": "USD",
  "country": "BR",
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "1",
  "documentNumber": "12345678901",
  "email": "[email protected]",
  "bankName": "341",
  "accountAgencyNumber": "0001",
  "accountNumber": "8585",
  // ... other beneficiary details
}

Important: The amount, currency, and country must match exactly with the values used in the quote request. If they don't match or if the quote has expired, the payout will be rejected.

Retrieving Payout Details

Endpoint: GET /v2/payouts/{externalReference}

Retrieve the complete payout details including the FX breakdown:

{
  "payoutId": 2101122,
  "payoutBatchId": 23,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "1",
  "documentNumber": "12345678901",
  "email": "[email protected]",
  "currencyCode": "BRL",
  "country": "BR",
  "bankName": "341",
  "accountAgencyNumber": "0001",
  "accountNumber": "8585",
  "amount": "1000.00",
  "address": "Address 1",
  "city": "City 1",
  "paymentReason": "Reason 2",
  "statusTypeCode": "PENDING",
  "payoutAccountTypeCode": "0001",
  "externalReference": "Reference 1",
  "notificationUrl": "https://yournotification.url.com",
  "phone": "55123456789",
  "payoutChannel": "ONLINE",
  "payoutQuoteId": "a24e2589-883a-45a2-93b4-e086b735c0c8",
  "fxBreakdown": {
    "exchangeRate": 5.38891,
    "components": {
      "merchantSpreadPercent": 1.5,
      "pspSpreadPercent": 2,
      "localTaxPercent": 0,
      "operationFeePercent": 0
    },
    "contexts": {
      "base": {
        "currency": "USD",
        "payoutAmount": 991.28,
        "merchantSpreadAmount": 14.87,
        "pspSpreadAmount": 19.83,
        "localTaxAmount": 0,
        "operationFee": 0,
        "netPayoutAmount": 956.58
      },
      "local": {
        "currency": "BRL",
        "payoutAmount": 5341.92,
        "merchantSpreadAmount": 80.13,
        "pspSpreadAmount": 106.86,
        "localTaxAmount": 0,
        "operationFee": 0,
        "netPayoutAmount": 5154.93
      }
    }
  }
}

Understanding the FX Breakdown

The fxBreakdown object provides a complete view of the payout calculation:

Exchange Rate

exchangeRate: The locked exchange rate applied for this payout (from your wallet currency to local currency)

Components (percentages applied)

merchantSpreadPercent: Your configured merchant spread
pspSpreadPercent: PayRetailers' processing spread
localTaxPercent: Applicable local taxes (varies by country)
operationFeePercent: Payout processing fee

Contexts (amounts in each currency)

Base Context (your wallet currency):

currency: Your wallet currency (e.g., USD, EUR, GBP)
payoutAmount: Initial payout amount before deductions
merchantSpreadAmount: Your spread amount deducted
pspSpreadAmount: PSP spread amount deducted
localTaxAmount: Tax amount deducted (if applicable)
operationFee: Processing fee deducted
netPayoutAmount: Amount debited from your wallet

Local Context (end user's receiving currency):

currency: Local payout currency (e.g., BRL, MXN, COP)
payoutAmount: Converted amount before deductions
merchantSpreadAmount: Your spread in local currency
pspSpreadAmount: PSP spread in local currency
localTaxAmount: Tax in local currency (if applicable)
operationFee: Processing fee in local currency
netPayoutAmount: Exact amount the end user will receive

Quote Expiration and Validation

Quote Lifespan

Quotes are valid for 5 minutes from creation
After expiration, you must create a new quote
Each quote can only be used once (it's consumed when the payout is executed)

Validation Rules

The system will reject a payout execution if:

The quote has expired
The quote ID doesn't exist or has already been used
The amount, currency, or country don't match the original quote
The quote was created by a different merchant account

Use Cases

Transparent Payout Display

Show end users the exact local currency amount they'll receive before they confirm the payout:

Create a quote when the user initiates a payout
Display the netPayoutAmount from the local context
Show the exchange rate and any applicable fees
Allow the user to confirm
Execute the payout with the quote ID

Multi-Currency Payout Calculator

Build a calculator that lets users:

Enter the amount they want to send
See real-time quotes for different destination countries
Compare payout amounts across currencies
Lock in their preferred rate

Reconciliation and Reporting

Use the FX breakdown for:

Accurate financial reconciliation
Understanding the true cost of each payout
Reporting on FX spreads and fees
Auditing payout transactions

Webhooks

Payout webhook notifications will include the complete FX breakdown, allowing you to track and reconcile payouts automatically:

{
  "event": "payout.completed",
  "payoutId": 2101122,
  "payoutQuoteId": "a24e2589-883a-45a2-93b4-e086b735c0c8",
  "fxBreakdown": {
    // Complete FX breakdown as shown above
  }
}

Best Practices

Create quotes at the right time: Generate quotes when users are ready to confirm, not during browsing
Monitor expiration: Display a countdown or refresh the quote before it expires
Handle errors gracefully: If a quote expires, automatically create a new one and show the updated rates
Store quote IDs: Keep the payoutQuoteId with your payout records for reconciliation
Communicate clearly: Show end users the exact local amount they'll receive and the locked exchange rate
Validate before execution: Ensure the payout details match the quote before submission

Enabling Payout FX Control

To start using Payout FX Control:

Contact Your Account Manager: Reach out to your PayRetailers account manager to enable this feature
Configuration: Your account will be configured with appropriate FX spread settings and country-specific rules
Integration: Once enabled, you can immediately start creating quotes and executing payouts with locked rates

Support

For questions about Payout FX Control or to enable this feature on your account:

Contact: Your dedicated PayRetailers account manager
Documentation: Review our complete API documentation at Create Payout Quote and Create Payout
Support: Reach out to [email protected]