Financial Accounts

Financial accounts represent external wallets and bank accounts you connect to your Commerce balance for bi-directional money movement. Push funds out to settle vendors, disburse earnings, or process refunds. Pull funds in to top up your balance, collect recurring payments, or sweep from connected accounts. Each account tracks its own verification status, currency constraints, and push/pull capabilities—giving you granular control over how money flows through your system.

The financial account object

Every financial account captures the complete state needed for bi-directional transfers: account details (wallet or bank), currency constraints, push/pull configurations, mandate authorizations, and verification status. The type field determines which nested object contains the account-specific details.

Properties

Name
id
Type
string
Description
Unique identifier for this financial account—reference this when pushing funds out or pulling funds in.
Name
type
Type
enum
Description
Account type: wallet or bank. This discriminator determines which nested object holds the account-specific details.
Name
currency
Type
string
Description
ISO 4217 currency code in lowercase—must match a currency your Commerce account supports (like ghs, usd, eur). Enforces currency constraints for transfers involving this account.
Name
label
Type
string
Description
Human-readable display name (5–40 characters) like Primary settlement wallet, Balance top-up source, or Vendor disbursements - MTN. Shows up in dashboards and reconciliation reports.
Name
reference
Type
string
Description
Your internal identifier (5–40 characters) for this account—typically a SKU, vendor code, or reconciliation key from your system.
Name
description
Type
string
Description
Optional long-form text (up to 200 characters) describing how you use this account—useful for team context and audit trails.
Name
created_at
Type
timestamp
Description
When this financial account was created. Immutable once set.
Name
archived_at
Type
timestamp|null
Description
When this account was archived and made unavailable for new operations. null while the account is active.
push_configurationobjectControls push operations (sending funds from your Commerce balance to this account). Present when you've enabled outbound transfers—lets you disburse earnings, settle invoices, or process refunds.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Unique identifier for this push configuration.
- Name
  enabled_at
  Type
  timestamp
  Description
  When push capability was activated for this account.
pull_configurationobjectControls pull operations (debiting funds from this account into your Commerce balance). Present when you've enabled inbound transfers—lets you top up your balance, collect recurring payments, or sweep from connected accounts. Includes mandate details and transaction limits for regulatory compliance.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Unique identifier for this pull configuration.
- Name
  enabled_at
  Type
  timestamp
  Description
  When pull capability was activated.
- Name
  min_threshold
  Type
  integer
  Description
  Minimum amount (in smallest currency unit) that can be debited in a single pull operation.
- Name
  max_threshold
  Type
  integer
  Description
  Maximum amount (in smallest currency unit) allowed per pull operation.
- Name
  pull_mandate
  Type
  object|null
  Description
  Mandate authorization details capturing when and how the account holder granted debit permissions—required for regulatory compliance and dispute resolution.
  View pull_mandate attributesClick or tap to expand
  Name
  id
  Type
  string
  Description
  Unique mandate identifier for audit and dispute resolution.
  Name
  granted_at
  Type
  timestamp
  Description
  When the account holder authorized pull operations.
  Name
  user_agent
  Type
  string
  Description
  Browser or app user agent string captured during authorization.
  Name
  ip_address
  Type
  string
  Description
  IP address recorded at authorization time—used for fraud prevention and compliance.
Name
verification
Type
object|null
Description
Verification lifecycle metadata. When present, includes initiated_at, completed_at, and request details showing when and how the account was verified (via micro-deposits, manual review, or other proofing mechanisms). null for unverified accounts.
walletobjectPresent when type is wallet. Currently supports mobile money wallets—widely used for transfers in Ghana and other African markets.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Platform-generated wallet identifier for internal tracking.
- Name
  type
  Type
  enum
  Description
  Wallet subtype—either mobile_money or dosh. Future versions may support e-wallets and other digital payment accounts.
- Name
  mobile_money
  Type
  object
  Description
  Mobile money network details—everything needed to route funds to or pull from the correct provider and subscriber.
  View mobile_money attributesClick or tap to expand
  Name
  network
  Type
  string
  Description
  Mobile money provider: mtn, vodafone, airteltigo, or other supported networks. Must match your Commerce account's enabled networks.
  Name
  account
  Type
  string
  Description
  Subscriber phone number (MSISDN) in local or international format. The API normalizes format automatically.
- Name
  dosh
  Type
  object
  Description
  Dosh wallet details—everything needed to route funds to or pull from the correct wallet.
  View dosh attributesClick or tap to expand
  Name
  name
  Type
  string
  Description
  Account holder full name—must match bank records for regulatory compliance.
  Name
  account_number
  Type
  string
  Description
  Destination account number at the receiving bank.
  Name
  country
  Type
  string
  Description
  ISO 3166-1 alpha-2 country code where the bank operates (e.g., gh, us, gb).
  Name
  account_type
  Type
  string
  Description
  Account classification: checking, savings, or other bank-specific types.
bankobjectPresent when type is bank. Supports both local and international bank transfers. Note: The create endpoint accepts all fields below, but the response is currently empty as bank transfers are in beta.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Account holder full name—must match bank records for regulatory compliance.
- Name
  account_number
  Type
  string
  Description
  Destination account number at the receiving bank.
- Name
  routing_number
  Type
  string
  Description
  Routing identifier: ABA for US banks, SWIFT/BIC for international transfers, or sort code for UK banks.
- Name
  bank_code
  Type
  string
  Description
  Local bank identifier when different from routing number—used in some markets for domestic transfers.
- Name
  country
  Type
  string
  Description
  ISO 3166-1 alpha-2 country code where the bank operates (e.g., gh, us, gb).
- Name
  account_type
  Type
  string
  Description
  Account classification: checking, savings, or other bank-specific types.

POST/financial_accounts/connect

Connect a financial account

Connect an existing wallet or bank account for bi-directional money movement. Use this endpoint when the financial account already exists in the real world—you're just registering it in your Commerce account. Supply the account type (wallet or bank), currency constraints, type-specific details, and optionally enable push/pull capabilities in a single request. The API validates field lengths, currency support, and account-specific requirements automatically—if something's misconfigured, you'll get a clear error before any state is persisted.

Common use cases: Connect a mobile money wallet to disburse vendor payments (push) or collect subscription fees (pull). Link a bank account to sweep daily revenue into your operating account (pull) or process customer refunds (push). Connect your founder's wallet to inject working capital when your balance runs low (pull).

Validation rules

label and reference: Both must be 5–40 characters. Use label for human-readable names, reference for your internal identifiers.
currency: Must match a currency your Commerce account supports (check the dashboard for enabled currencies). Common values: ghs, usd, eur, ngn.
type: Determines which nested object is required. wallet needs a wallet object, bank needs bank. Sending multiple type objects in one request will fail validation.
Wallet-specific: When type is wallet, the wallet.type field must be either mobile_money or dosh. The nested object requires network/provider details and account identifiers.
Push/Pull config: Enable push_configuration to send funds out to this account. Enable pull_configuration (with proper mandate authorization) to debit funds from this account into your Commerce balance. You can enable both for bi-directional flow.

Required attributes

Name
label
Type
string
Description
Human-readable name for dashboards, reports, and team communication. 5–40 characters.
Name
reference
Type
string
Description
Your internal identifier for reconciliation and lookups. 5–40 characters. Use vendor codes, SKUs, or other stable references from your system.
Name
type
Type
enum
Description
Destination type: wallet or bank. This determines which type-specific object you must include in the request body.
Name
currency
Type
string
Description
Lowercase ISO 4217 currency code (e.g., ghs, usd, eur). Must be enabled for your Commerce account—the API will reject unsupported currencies.
walletobjectRequired when type is wallet. Describes a mobile money wallet or digital wallet for bi-directional transfers.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Wallet subtype—either mobile_money or dosh. Future versions will support additional digital wallet types.
- Name
  mobile_money
  Type
  object
  Description
  Mobile money network and subscriber details. Used for routing both push and pull operations.
  View mobile_money attributesClick or tap to expand
  Name
  network
  Type
  string
  Description
  Provider identifier: mtn, vodafone, airteltigo, or other supported networks. Check your Commerce account settings for enabled providers.
  Name
  account
  Type
  string
  Description
  Subscriber phone number (MSISDN). Accepts international format (+233...) or clean local format (024...). The API normalizes automatically.
bankobjectRequired when type is bank. Describes a bank account for wire transfers, ACH payments, and direct debits.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Account holder full name—must match bank records exactly for compliance and successful transfers (both push and pull).
- Name
  account_number
  Type
  string
  Description
  Bank account number at the institution.
- Name
  routing_number
  Type
  string
  Description
  Routing identifier: ABA routing number (US), SWIFT/BIC code (international), or sort code (UK).
- Name
  bank_code
  Type
  string
  Description
  Local bank code for domestic transfers in markets where routing number and bank code are separate.
- Name
  country
  Type
  string
  Description
  ISO 3166-1 alpha-2 country code (e.g., gh, us, gb) where the bank operates.
- Name
  account_type
  Type
  string
  Description
  Account classification: checking, savings, or other institution-specific type.

Optional attributes

Name
description
Type
string
Description
Long-form description (up to 200 characters) of how you use this account. Examples: Vendor disbursement wallet, Balance top-up source - owner's MTN, Customer refund processing. Useful for team context, compliance documentation, and audit trails.
push_configurationobjectEnable push operations (send funds from your Commerce balance to this account). Use this for vendor disbursements, customer refunds, earnings payouts, or settlement transfers. To make this account the default destination for automatic payouts in a specific currency, enable push and then set it using /payouts/set_destinations.Click or tap to expand
- Name
  enabled
  Type
  boolean
  Description
  Set true to enable push operations immediately. Set false (or omit) to create the account without push capability—you can enable it later via update.
pull_configurationobjectEnable pull operations (debit funds from this account into your Commerce balance). Use this to top up your balance, collect recurring payments, or sweep revenue from connected accounts. Requires proper mandate authorization from the account holder for regulatory compliance.Click or tap to expand
- Name
  enabled
  Type
  boolean
  Description
  Set true only when you have explicit authorization (mandate) from the account holder to debit funds. Set false (or omit) to disable pull operations. Required for balance top-ups and recurring collections.

Request

POST

/financial_accounts/connect

curl https://api.zebo.dev/financial_accounts/connect \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Konadu Tailoring Collections",
    "reference": "KONADU-MOMO-SETTLEMENT",
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "type": "wallet",
    "currency": "ghs",
    "wallet": {
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account": "0242057831"
      }
    },
    "push_config": { "enabled": true },
    "pull_config": { "enabled": false }
  }'

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "currency": "ghs",
    "type": "wallet",
    "label": "Konadu Tailoring Collections",
    "reference": "KONADU-MOMO-SETTLEMENT",
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "created_at": "2025-03-18T10:22:11.745Z",
    "archived_at": null,
    "verification": null,
    "push_configuration": null,
    "pull_configuration": null,
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account": "0242057831"
      }
    }
  }
}

POST/financial_accounts/create

Create a financial account

Create a new financial account at a partner bank or mobile money provider, then register it in your Commerce account. Use this endpoint when you need Commerce to provision the account for you—we'll create it with our partner institutions and handle the setup. This differs from Connect, which registers accounts that already exist.

When to use Create vs Connect: Use Connect for accounts your customers or vendors already own (existing mobile money wallets, bank accounts). Use Create when you need Commerce to provision new accounts on your behalf—typically for specialized use cases like creating sub-accounts for marketplace sellers or setting up dedicated collection accounts.

Note: Account creation is currently in beta and requires partner integration setup. Most users should use Connect to register existing accounts. Contact support to enable account creation capabilities for your Commerce account.

Request attributes

The request structure matches Connect but includes additional partner-specific parameters for account provisioning. See the Connect documentation for detailed parameter descriptions.

Request

POST

/financial_accounts/create

curl https://api.zebo.dev/financial_accounts/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Marketplace Seller Sub-Account",
    "reference": "SELLER-001-COLLECTION",
    "description": "Dedicated collection account for seller 001.",
    "type": "wallet",
    "currency": "ghs",
    "wallet": {
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account": "0244123456"
      }
    }
  }'

Response

{
  "account": {
    "id": "fa_X1Y2Z3A4B5C6D7E8F9G0H1I2J3K4L5M6N7O8P9Q",
    "currency": "ghs",
    "type": "wallet",
    "label": "Marketplace Seller Sub-Account",
    "reference": "SELLER-001-COLLECTION",
    "description": "Dedicated collection account for seller 001.",
    "created_at": "2025-03-18T11:30:00.000Z",
    "archived_at": null,
    "verification": null,
    "push_configuration": null,
    "pull_configuration": null,
    "wallet": {
      "id": "wal_Y9Z0A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R",
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account": "0244123456"
      }
    }
  }
}

POST/financial_accounts/lookup

Lookup a financial account

Retrieve the current state of a financial account by its ID. This returns the full account object including any configuration changes, verification status updates, or archive timestamps since creation. Use this to confirm account details before initiating transfers, check if push/pull capabilities have been modified, or inspect mandate authorization status for pull operations.

The response structure matches what you received when creating the account, with all the same nested objects and timestamps. If the account has been archived, archived_at will be populated.

Request attributes

Name
account_id
Type
string
Description
Unique identifier returned from /financial_accounts/create or found in transfer records. Must be non-empty and match an account in your Commerce account.

Request

POST

/financial_accounts/lookup

curl https://api.zebo.dev/financial_accounts/lookup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
  }'

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "currency": "ghs",
    "type": "wallet",
    "label": "Konadu Tailoring Collections",
    "reference": "KONADU-MOMO-SETTLEMENT",
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "created_at": "2025-03-18T10:22:11.745Z",
    "archived_at": null,
    "verification": null,
    "push_configuration": null,
    "pull_configuration": null,
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account": "0242057831"
      }
    }
  }
}