Guides
Support
Start typing to search…

Payins FX Control (Experimental)

Overview

Merchant FX Control allows you to manage foreign exchange costs when accepting payments in local currencies while settling in a different wallet currency (such as USD, EUR, or GBP). This feature provides complete transparency of FX rates, spreads, and applicable fees, enabling you to make informed decisions about passing these costs to your customers.

Key Benefits

  • Transparent FX Breakdown: Get a complete, itemized view of exchange rates, spreads, and fees for each transaction
  • Flexible Cost Management: Choose whether to absorb FX costs or pass them to customers
  • Simplified Reconciliation: Clear breakdown of all components from local currency to your wallet currency
  • Real-time Calculations: Receive synchronous FX breakdowns at the moment of transaction creation

How It Works

When you create a transaction, you can now specify your desired merchant spread percentage. The system will:

  1. Apply the current exchange rate to convert from the local currency to your wallet currency
  2. Calculate and apply your merchant spread, PSP spread, and applicable local taxes
  3. Return a detailed breakdown showing all components in both currencies
  4. Credit the net deposit amount to your wallet in your declared currency

Important: All fees, spreads, and taxes are deducted from the customer's payment amount. The net deposit you receive is the amount after these deductions.

API Usage

Request Parameter

Add the merchantSpreadPercent parameter to your transaction creation request:

POST /transactions
{
  "amount": 5000.00,
  "currency": "BRL",
  "merchantSpreadPercent": 1.00,
  // ... other transaction parameters
}

Parameter Details:

  • merchantSpreadPercent (decimal): Your desired spread percentage (e.g., 1.00 for 1%)
  • This parameter is optional; if not provided, the transaction will proceed without merchant spread

Response Structure

When FX breakdown is enabled for your account, you'll receive detailed FX information in the response:

{
  "uid": "49d9e769-a36d-4e94-9aaf-fb03e32ed843",
  "type": "payment",
  "status": "PENDING",
  "fxBreakdown": {
    "exchangeRate": 0.1883,
    "components": {
      "merchantSpreadPercent": 1.00,
      "pspSpreadPercent": 1.00,
      "localTaxPercent": 1.10,
      "operationFeePercent": 1.50
    },
    "contexts": {
      "base": {
        "currency": "USD",
        "topUpAmount": 941.50,
        "merchantSpreadAmount": 9.42,
        "pspSpreadAmount": 9.42,
        "localTaxAmount": 10.36,
        "operationFee": 74.25,
        "netDepositAmount": 898.83
      },
      "local": {
        "currency": "BRL",
        "topUpAmount": 5000.00,
        "merchantSpreadAmount": 50.00,
        "pspSpreadAmount": 50.00,
        "localTaxAmount": 55.00,
        "operationFee": 74.25,
        "netDepositAmount": 4770.75
      }
    }
  }
}

Understanding the Response

The fxBreakdown object contains three main sections:

1. Exchange Rate

  • exchangeRate: The base exchange rate used for conversion (local to wallet currency)

2. Components (percentages applied)

  • merchantSpreadPercent: Your configured merchant spread
  • pspSpreadPercent: PayRetailers' processing spread
  • localTaxPercent: Applicable local taxes (e.g., IOF in Brazil)
  • operationFeePercent: Payment processing fee

3. Contexts (amounts in each currency)

Base Context (your wallet currency):

  • currency: Your wallet currency (e.g., USD, EUR, GBP)
  • topUpAmount: Initial amount after FX conversion
  • merchantSpreadAmount: Your spread amount deducted
  • pspSpreadAmount: PSP spread amount deducted
  • localTaxAmount: Tax amount deducted
  • operationFee: Processing fee deducted
  • netDepositAmount: Final amount credited to your wallet

Local Context (customer's payment currency):

  • currency: Local payment currency (e.g., BRL, MXN, COP)
  • topUpAmount: Customer's payment amount
  • merchantSpreadAmount: Your spread in local currency
  • pspSpreadAmount: PSP spread in local currency
  • localTaxAmount: Tax in local currency
  • operationFee: Processing fee in local currency
  • netDepositAmount: Net amount in local currency terms

Enabling FX Breakdown

To start receiving FX breakdown information in your transaction responses:

  1. Contact Your Account Manager: Reach out to your PayRetailers account manager to request FX breakdown enablement
  2. Configuration: Your account will be configured with the appropriate shop-level settings
  3. Integration: Once enabled, you can immediately start using the merchantSpreadPercent parameter and receiving detailed breakdowns

The following settings will be configured based on your business needs:

  • Whether to include fees in customer amount calculations
  • Whether to include taxes in customer amount calculations
  • Whether to include FX rate markup in customer amount calculations

Use Cases

Pass-Through Pricing

Display the complete cost breakdown to customers at checkout, allowing them to see exactly what they're paying for:

  • Exchange rate applied
  • All applicable fees and taxes
  • Final amount you'll receive

Cost Absorption

Use the breakdown internally for accounting while absorbing FX costs for customers, maintaining transparent reconciliation on your end.

Hybrid Approach

Absorb certain costs while passing others to customers based on your business model and competitive positioning.

Best Practices

  1. Always specify your spread: Include merchantSpreadPercent in requests to maintain consistent pricing
  2. Monitor exchange rates: FX rates can fluctuate; review the exchangeRate field in responses
  3. Reconcile regularly: Use the detailed breakdown to match deposits with customer payments
  4. Communicate clearly: If passing costs to customers, ensure they understand the FX breakdown before payment

Support

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


Updated 1 day ago