Set up financial accounts

Connect your real-world bank accounts and mobile money wallets to Commerce so you can receive automatic payouts and withdraw funds from your balance. Financial accounts act as withdrawal destinations—when Commerce processes a payout, funds move from your balance to the account you've specified.

Why financial accounts matter

Your Commerce balance accumulates funds from successful payments, but those funds stay within the Commerce system until you move them out. Financial accounts are the bridge between your Commerce balance and your actual money—the bank account where you pay suppliers, the mobile wallet where you withdraw cash, or the Dosh account you use for business expenses.

Without a connected financial account, automatic payouts can't run. Commerce has nowhere to send the funds. You'll see your balance grow but won't be able to access the money until you connect at least one destination account.

Prerequisites

Before connecting a financial account:

• Verify you own the account - You'll need the account details (account number, network for mobile money)
• Ensure the account is active - Deactivated accounts will reject incoming transfers
• Know the account currency - New connections currently use ghs
• Have the account accessible - You may need to confirm ownership through SMS or bank verification

Account types

Commerce supports three types of financial accounts:

Mobile money wallets - MTN, Vodafone, Airtel, or Telecel mobile wallets.

Bank accounts - Traditional bank accounts at commercial banks. Suitable for large transfers, business accounts, and situations requiring formal banking infrastructure.

Dosh accounts - Dosh payment accounts. Alternative payment infrastructure with specific use cases.

Choose the account type that matches how you manage cash in your business. Most merchants start with a mobile money wallet for convenience, then add a bank account as transaction volumes grow.

Connect your account

Select the account type you want to connect:

curl https://api.zebo.dev/financial_accounts/connect \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet",
    "currency": "ghs",
    "label": "Primary MTN Wallet",
    "description": "Main business mobile money account",
    "reference": "WALLET-MTN-001",
    "wallet": {
      "type": "mobile_money",
      "mobile_money": {
        "account_number": "0241234567",
        "network": "mtn"
      }
    },
    "push_configuration": {
      "enabled": true
    }
  }'

Understanding the parameters

type - Account type: wallet, bank_account, or dosh_account. Determines which real-world account infrastructure Commerce uses for transfers.

currency - Lowercase ISO 4217 currency code. Financial-account connection currently accepts ghs.

label - Human-readable name for this account (5-40 characters). Shows up in your dashboard, reports, and payout records. Use something descriptive like "MTN Mobile Money" or "GCB Business Account".

description - Optional detailed description (0-200 characters). Add context that helps you remember what this account is for: "Primary withdrawal account" or "Vendor payment account".

reference - Your internal identifier (5-40 characters). Link this financial account to accounts in your own systems. Useful for reconciliation and internal reporting.

push_configuration.enabled - Whether Commerce can send funds to this account. Set to true for payout destinations. Set to false if you only want to pull funds from this account without allowing payouts to it.

pull_configuration.enabled - Whether the account is configured for debit flows. To provide authorization context, call Enable pulls with optional ip_address and user_agent fields.

Set as payout destination

After connecting a financial account, designate it as your payout destination for specific currencies using /payouts/set_destinations:

curl https://api.zebo.dev/payouts/set_destinations \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": {
      "ghs": "fa_abc123xyz789"
    }
  }'

Now automatic payouts for GHS will route to this account. The current destination contract accepts a GHS mapping.

Disconnect a financial account

When you no longer need a financial account or want to switch to a different one, use Disconnect a financial account to prevent future payouts. Disconnecting does not delete historical records—past payouts that went to this account remain in your transaction history.

Before disconnecting, make sure:

• No pending payouts are scheduled to this account
• You've updated payout destinations if this was your active payout account
• You have another verified account ready if you need continued payouts

Disconnecting preserves the same financial-account record for audit trails while blocking new use. If the relationship becomes valid again later, restore the same record with Reconnect a financial account instead of creating a duplicate account.

Related resources

• Manage payout destinations - Configure where automatic payouts go
• Understand payout settings - Learn how payout schedules and destinations work together
• Financial Accounts API Reference - Complete endpoint documentation