Payouts FX conversion

Foreign exchange (FX) conversion in Commerce payouts allows you to receive funds in a different currency than the one customers paid with. When enabled, Commerce automatically converts balance transactions from one currency to another during payout execution, letting you consolidate multiple currencies into a single operating account or hold funds in your preferred currency regardless of transaction origin.

How FX conversion works

FX conversion happens during payout execution—after balance transactions have aged and become eligible, but before the transfer reaches your financial account. The process is automatic and transparent.

Default behavior: Currency matching required

By default, Commerce enforces strict currency matching for all payouts. If customers pay you in GHS, those funds can only be paid out to a GHS financial account. If you've configured a USD account as the destination for GHS payouts, the payout will fail with a currency mismatch error.

This default behavior protects you from unexpected conversion fees and rate fluctuations. It keeps currencies separate throughout the payment lifecycle—GHS transactions stay GHS, USD transactions stay USD. For businesses operating primarily in one currency or those preferring to hold multiple currencies separately, this is the recommended configuration.

Opt-in FX: Cross-currency flexibility

When you enable FX conversion via /payouts/enable_fx, Commerce allows currency mismatches between balance transactions and destination accounts. If you have GHS balance transactions but configure a USD account as the destination, Commerce automatically converts the GHS to USD during payout execution and sends the converted amount.

This opt-in model gives you control. Enable FX when you need multi-currency consolidation or cross-border treasury management. Keep it disabled (default) when you want predictable, currency-matched payouts without conversion fees.

Conversion rates and pricing

Commerce determines exchange rates at the time of payout execution—not when you configure destinations or schedule payouts. This means the rate used for conversion reflects current market conditions when the transfer actually happens.

Rate determination

Conversion rates are determined by Commerce's financial partners—the banks, payment processors, and liquidity providers that facilitate cross-border transfers. Commerce does not set rates arbitrarily. Instead, we use mid-market rates (the midpoint between buy and sell prices on currency exchanges) plus a small spread to cover operational costs and partner fees.

Rates fluctuate continuously based on market conditions, trading volumes, and macroeconomic factors. A rate that was 15.2 GHS per USD when you configured your destinations might be 15.3 GHS per USD when the payout actually executes days later. This is normal foreign exchange behavior—rates move, sometimes significantly, in response to global events.

Conversion fees

FX conversion incurs additional fees beyond standard payout fees. The exact fee structure depends on the currency pair, conversion volume, and your Commerce plan. Typical fees range from 0.5% to 2% of the converted amount.

For specific pricing on your desired currency pairs, contact Commerce support at support@zebo.dev. Fees are disclosed before you enable FX, and you'll see the exact conversion fee on each payout record after execution.

Rate fluctuation considerations

Because rates are determined at execution time, the amount you receive may differ from what you expected when scheduling a payout. For large amounts or time-sensitive transfers, consider:

Check current rates before enabling FX: Understand typical rates for your currency pairs to set realistic expectations
Monitor rate trends: If rates are volatile, you might temporarily disable FX and wait for stability
Use manual mode for timing control: In manual mode, you can trigger payouts when rates are favorable rather than waiting for the automatic weekly schedule

Commerce does not offer rate locking or guaranteed rates. All conversions use the prevailing rate at execution time.

Enabling and disabling FX

FX conversion is controlled via two simple API endpoints. Changes take effect immediately for all future payouts.

Enabling FX

Call /payouts/enable_fx to enable foreign exchange conversion. No request body required:

curl https://api.zebo.dev/payouts/enable_fx \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The response includes your updated payout settings with fx_enabled: true. From this point forward, Commerce allows currency-mismatched destination configurations and automatically converts funds during payout execution.

See the Enable FX payouts guide for complete implementation instructions, code samples in all supported languages, and verification steps.

Disabling FX

Call /payouts/disable_fx to disable foreign exchange conversion and revert to currency-matched payouts only:

curl https://api.zebo.dev/payouts/disable_fx \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The response includes your updated payout settings with fx_enabled: false. From this point forward, Commerce enforces strict currency matching—GHS balance can only go to GHS accounts, USD balance only to USD accounts.

See the Disable FX payouts guide for complete instructions.

Supported currency pairs

Commerce supports FX conversion for the currency pairs actively traded by our financial partners. Availability depends on market liquidity, regulatory requirements, and partner capabilities.

Currently supported conversions include:

GHS to USD (Ghanaian cedi to US dollar)
USD to GHS (US dollar to Ghanaian cedi)

As Commerce expands to additional markets and currencies, we'll add support for more currency pairs. Each new pair is tested thoroughly before launch to ensure reliable conversion and competitive rates.

For the most current list of supported pairs or to request a specific conversion, contact Commerce support at support@zebo.dev.

When to use FX conversion

FX conversion is powerful but not right for every business. Consider these scenarios:

Good use cases for FX

Multi-currency consolidation: You accept payments in GHS, USD, and EUR across different markets, but want to hold all funds in USD for simplicity. Enable FX and configure all currency destinations to point to your USD account. Commerce automatically converts each currency to USD during payouts.

Stable currency holding: You operate primarily in a market with currency volatility and prefer to hold funds in a more stable foreign currency (e.g., USD or EUR). Enable FX and route local currency payouts to your foreign currency account.

Single treasury account: Your accounting system and financial workflows are built around a single operating currency. Rather than managing multiple currency accounts and manual conversions, enable FX to consolidate everything automatically.

Cross-border expansion: You're expanding to new markets and accepting local currencies, but don't want to open local bank accounts in each market. Enable FX to route all payouts to your existing accounts in your home currency.

When to keep FX disabled

Single currency operations: If you accept payments in only one currency and hold funds in that same currency, FX adds no value. Keep it disabled to avoid unnecessary conversion fees.

Fee sensitivity: Conversion fees typically range from 0.5% to 2%. For businesses with thin margins, keeping currencies separate eliminates these fees entirely.

Accounting preferences: Some accounting systems and workflows are designed to track each currency separately. If your team prefers currency-specific accounts and reporting, keep FX disabled and maintain separate accounts for each currency.

Rate volatility concerns: If you're uncomfortable with exchange rate fluctuations or need predictable amounts in your accounts, keep FX disabled and hold each currency separately.

Verifying FX status

Check whether FX is enabled by calling /payouts/settings and inspecting the fx_enabled field:

{
  "settings": {
    "fx_enabled": true,   // FX conversion is enabled
    // ...
  }
}

If fx_enabled is true, Commerce will convert funds when destination account currency differs from payout currency. If false, Commerce enforces currency-matched payouts only.

See the Understand payout settings guide for complete documentation on the fx_enabled field and all other settings response fields.