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 - Must match one of your Commerce supported currencies
• 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, or AirtelTigo mobile wallets. Best for daily operations, instant access to funds, and small to medium withdrawal amounts. Widely used in Ghana and other African markets.

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 $SECRET_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": "0241234567",
        "network": "mtn"
      }
    },
    "push_configuration": {
      "enabled": true
    }
  }'

Understanding the parameters

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

currency - ISO 4217 currency code (lowercase). Must match a currency you've enabled in your Commerce account. The account will only receive payouts in this currency.

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 charge customers from this account (pull funds in) without allowing payouts to it.

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 $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": {
      "ghs": "fa_abc123xyz789"
    }
  }'

Now automatic payouts for GHS will route to this account. You can map different currencies to different accounts—GHS to your MTN wallet, USD to your bank account.

Disconnect a financial account

When you no longer need a financial account or want to switch to a different one, disconnect it to prevent future payouts. Disconnecting doesn't 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

To disconnect, you'll mark the account as archived rather than deleting it entirely. This preserves the audit trail while preventing new payouts.

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