Disable FX payouts

Disable foreign exchange (FX) conversion to enforce currency-matched payouts—GHS balance only goes to GHS accounts, USD balance only to USD accounts. This prevents unexpected conversion fees and ensures payouts maintain their original currency.

FX is disabled by default for all Commerce accounts. Only enable FX if you need cross-currency payout consolidation. Keeping FX disabled is the recommended configuration for most businesses.

When to disable FX

Disable FX conversion when you want:

No conversion fees: Avoid FX fees by keeping each currency separate
Original currency preservation: Maintain transaction currency throughout the payout flow
Predictable accounting: Simplify reconciliation with currency-matched payouts
Rate stability: Eliminate exposure to exchange rate fluctuations

This is the default and recommended configuration unless you specifically need multi-currency consolidation or cross-border treasury management.

Disabling FX conversion

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

Disable FX conversion

POST

/payouts/disable_fx

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

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

Response

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

What happens when FX is disabled

With FX disabled (default behavior), Commerce enforces strict currency matching:

Destination configuration: When you call /payouts/set_destinations, Commerce verifies that each financial account's currency matches the currency key you're mapping it to. Attempting to map GHS to a USD account is rejected with an error.
Automatic payouts: Sunday at midnight UTC, Commerce checks your available balance for each currency. For each currency with eligible balance, Commerce looks up the configured destination and verifies the account currency matches. Currency-mismatched destinations cause payout failure.
Manual payouts: When you call /payouts/schedule, Commerce verifies the destination account currency matches the payout currency. Mismatches are rejected immediately.

Example: You have 5,000 GHS in available balance. Your destination for GHS is configured as fa_ghs_account_456 (a GHS account). Commerce sends 5,000 GHS to the account without conversion. If the destination were fa_usd_account_789 (a USD account), the payout would fail due to currency mismatch.

Benefits of disabled FX

Keeping FX disabled provides several advantages:

No conversion fees

FX conversion typically costs 0.5%–2% of the converted amount. By keeping currencies separate, you avoid these fees entirely. For a business processing $100,000 USD and 500,000 GHS monthly, this can save $1,000–$4,000 per month in conversion fees.

Predictable amounts

Without conversion, the amount leaving your balance equals the amount arriving in your financial account (minus standard payout fees). No exchange rate fluctuations, no surprises. This simplifies accounting and cash flow forecasting.

Simpler reconciliation

Currency-matched payouts are easier to trace and reconcile. GHS transactions stay GHS, USD transactions stay USD. When reviewing payout records or investigating discrepancies, you don't need to account for conversion rates or FX fees—what went in is what came out.

Clearer reporting

Financial reports are cleaner when currencies don't mix. Your GHS balance reflects GHS activity, your USD balance reflects USD activity. No need to track which currencies were converted or when rates changed.

Verifying FX is disabled

Call /payouts/settings to verify FX is disabled:

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": false,   // ✓ FX is disabled (default)
    // ...
  }
}

If fx_enabled is false, Commerce will only accept currency-matched destinations and reject cross-currency payout attempts.

Configuring currency-matched destinations

With FX disabled, ensure each destination matches its currency key:

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_ghs_account_123",
      "usd": "fa_usd_account_456"
    }
  }'

This configuration sends GHS payouts to a GHS account and USD payouts to a USD account. No conversion occurs. Each currency maintains its identity throughout the payout flow.

Attempting mismatches: If you try to map GHS to fa_usd_account_456 while FX is disabled, Commerce rejects the request with an error explaining that currency-matched destinations are required.

Enabling FX later

To enable FX conversion and allow cross-currency payouts, call /payouts/enable_fx:

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

See the enable FX guide for complete instructions.