Enable FX payouts

Enable foreign exchange (FX) conversion to route payouts across currencies—send GHS balance to USD accounts, consolidate multiple currencies into a single operating currency, or hold funds in your preferred currency regardless of transaction origin.

FX-enabled payouts incur conversion fees and use market rates at execution time. Exchange rates may fluctuate between payout scheduling and execution. Not all currency pairs are supported—contact support for available conversions.

When to enable FX

Enable FX conversion when you need:

Multi-currency consolidation: Accept payments in GHS, USD, and EUR but hold all funds in USD
Single operating currency: Simplify accounting by converting all payouts to your base currency
Preferred currency holding: Keep funds in a stable foreign currency (e.g., USD) regardless of local transaction currency
Cross-border expansion: Accept local currencies in multiple markets while maintaining a single treasury account

Keep FX disabled (default) if you operate primarily in one currency or prefer to hold each currency separately to avoid conversion fees.

Enabling FX conversion

Call /payouts/enable_fx to enable foreign exchange conversion for your payouts. No request body required—Commerce uses your authentication context to identify your account and update the setting.

Enable FX conversion

POST

/payouts/enable_fx

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

The response includes your complete payout settings with fx_enabled set to true:

Response

{
  "settings": {
    "id": "ps_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
    "fx_enabled": true,
    "schedule": {
      "id": "payout_sched_weekly",
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
      "usd": "fa_A1bCdEf2G3HiJk4LmN5oPqRs6tUv7WxY8z9"
    }
  }
}

What happens when FX is enabled

With FX enabled, Commerce automatically converts payout funds when the destination account currency differs from the transaction currency:

Automatic mode: Sunday at midnight UTC, Commerce checks your available balance for each currency. For each currency with eligible balance, Commerce looks up the configured destination. If the destination account currency differs from the balance currency, Commerce converts the funds at the prevailing exchange rate and sends the converted amount.
Manual mode: When you call /payouts/schedule, Commerce checks the destination account currency. If it differs from the payout currency, Commerce converts the funds during execution.

Example: You have 5,000 GHS in available balance. Your destination for GHS is configured as fa_usd_account_123 (a USD account). With FX enabled, Commerce converts 5,000 GHS to approximately 400 USD (depending on exchange rate) and sends 400 USD to the account. With FX disabled, this payout would fail due to currency mismatch.

Understanding FX fees and rates

FX conversion incurs additional fees beyond standard payout fees. Conversion rates are determined by Commerce's financial partners at the time of payout execution—not when you schedule payouts. This means rates reflect current market conditions when the transfer actually happens.

For a complete explanation of how rates are determined, what fees apply, and when conversion happens, see the Payouts FX conversion guide.

Key points:

Conversion fee: Typically 0.5%–2% of the converted amount, depending on currency pair and volume
Exchange rate: Determined at payout execution time (not at scheduling time)
Rate fluctuation: Market rates may change between when you schedule a payout and when it executes

Because rates fluctuate, the amount received may differ from what you expect when scheduling a payout. For large amounts or sensitive timing, consider checking current rates before enabling FX or scheduling payouts.

Verifying FX is enabled

Call /payouts/settings to verify FX is enabled:

Get payout settings

POST

/payouts/settings

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

Check the fx_enabled field in the response:

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

If fx_enabled is true, Commerce will convert funds when destination account currency differs from payout currency.

Configuring cross-currency destinations

With FX enabled, you can configure destinations that don't match the currency key. For example, map GHS to a USD account:

curl https://api.zebo.dev/payouts/set_destinations \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": {
      "ghs": "fa_usd_account_123",
      "usd": "fa_usd_account_123"
    }
  }'

This configuration sends both GHS and USD payouts to the same USD account. GHS balance is automatically converted to USD during payout.

Without FX enabled: This configuration would be rejected—Commerce requires currency-matched destinations when FX is disabled.

Disabling FX later

To disable FX conversion and revert to currency-matched payouts only, call /payouts/disable_fx:

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

See the disable FX guide for complete instructions.