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
archived_at
Type
timestamp|null
Description
When this account was archived and made unavailable for new operations. null while the account is active.
Name
created_at
Type
timestamp
Description
When this financial account was created. Immutable once set.
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
custom_data
Type
object|null
Description
Arbitrary key-value pairs for storing additional information about this account. Useful for attaching metadata, internal references, or application-specific data.
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
disconnected_at
Type
timestamp|null
Description
When this account was disconnected and marked as unusable for payouts or charges. null for active accounts. Disconnected accounts remain visible in lookups and listings for historical reference but cannot be used for new transactions or configured as payout destinations.
Name
id
Type
string
Description
Unique identifier for this financial account—reference this when pushing funds out or pulling funds in.
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.
ownerobjectAccount owner information—name and address of the person or business that holds this financial account. Present when provided during account creation or update. Required for bank accounts, optional for wallets.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Account owner's full legal name.
- Name
  address
  Type
  object
  Description
  Owner's physical address.
  View address attributesClick or tap to expand
  Name
  city
  Type
  string
  Description
  City or town.
  Name
  country
  Type
  string
  Description
  Country.
  Name
  id
  Type
  string
  Description
  Address identifier (may not be present in all responses).
  Name
  line_1
  Type
  string
  Description
  First line of the street address.
  Name
  line_2
  Type
  string
  Description
  Second line of the address (optional).
  Name
  name
  Type
  string
  Description
  Address label (e.g., "Business Address", "Home Address").
  Name
  phone
  Type
  string
  Description
  Contact phone number (optional).
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code (optional).
  Name
  region
  Type
  string
  Description
  Region or state.
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 for regulatory compliance.Click or tap to expand
- Name
  enabled_at
  Type
  timestamp
  Description
  When pull capability was activated.
- Name
  mandate
  Type
  object
  Description
  Mandate authorization details capturing when and how the account holder granted debit permissions—required for regulatory compliance and dispute resolution.
  View mandate attributesClick or tap to expand
  Name
  created_at
  Type
  timestamp
  Description
  When the account holder authorized pull operations.
  Name
  id
  Type
  string
  Description
  Unique mandate identifier for audit and dispute resolution.
  Name
  ip_address
  Type
  string
  Description
  IP address recorded at authorization time—used for fraud prevention and compliance.
  Name
  user_agent
  Type
  string
  Description
  Browser or app user agent string captured during authorization.
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
  enabled_at
  Type
  timestamp
  Description
  When push capability was activated for this account.
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
type
Type
enum
Description
Account type: wallet, bank_account, or dosh_account. This discriminator determines which nested object holds the account-specific details.
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.
bank_accountobjectPresent when type is bank_account. Currently supports Ghana bank accounts. Note: Bank transfers are in beta.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Bank account type. Currently only ghana_bank_account is supported.
- Name
  ghana_bank_account
  Type
  object
  Description
  Ghana bank account details. Required when type is ghana_bank_account.
  View ghana_bank_account attributesClick or tap to expand
  Name
  branch
  Type
  string
  Description
  Bank branch name (optional, may be empty).
  Name
  name
  Type
  string
  Description
  Bank name (e.g., "GCB Bank", "Ecobank Ghana").
  Name
  number
  Type
  string
  Description
  Bank account number at the Ghanaian bank.
  Name
  sort_code
  Type
  string
  Description
  Six-digit bank sort code (may be empty if swift_code is provided).
  Name
  swift_code
  Type
  string
  Description
  SWIFT/BIC code (may be empty if sort_code is provided).
  Name
  holder
  Type
  object
  Description
  Account holder information—required for compliance and successful transfers.
  View holder attributesClick or tap to expand
  Name
  name
  Type
  string
  Description
  Account holder's full legal name—must match bank records exactly.
  Name
  address
  Type
  object
  Description
  Account holder's physical address for regulatory compliance.
  View address attributesClick or tap to expand
  Name
  city
  Type
  string
  Description
  City or town.
  Name
  country
  Type
  string
  Description
  Country.
  Name
  id
  Type
  string
  Description
  Address identifier (may not be present in all responses).
  Name
  line_1
  Type
  string
  Description
  First line of the street address.
  Name
  line_2
  Type
  string
  Description
  Second line of the address (optional).
  Name
  name
  Type
  string
  Description
  Address label (e.g., "Business Address", "Home Address").
  Name
  phone
  Type
  string
  Description
  Contact phone number (optional).
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code (optional).
  Name
  region
  Type
  string
  Description
  Region or state (e.g., "Greater Accra", "Ashanti").
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
  Wallet identifier.
- Name
  type
  Type
  enum
  Description
  Wallet subtype. Currently only mobile_money is supported.
- 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
  account
  Type
  string
  Description
  Subscriber phone number (MSISDN) in local or international format. The API normalizes format automatically.
  Name
  network
  Type
  string
  Description
  Mobile money provider: mtn, vodafone, airteltigo, or other supported networks. Must match your Commerce account's enabled networks.

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_account), 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_account needs bank_account. 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_account. The nested object requires network/provider details and account identifiers.
Bank account-specific: When type is bank_account, you must provide bank_account.type as ghana_bank_account with account details including number, either sort_code or swift_code, and full owner information with name and address.
Push/Pull config: Enable push_configuration to send funds out to this account. Enable pull_configuration to debit funds from this account into your Commerce balance. When you enable pull, Commerce automatically creates a mandate record from the request context (IP address and user agent) for regulatory compliance. 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, bank_account, or dosh_account. 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_account. 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.
bank_accountobjectRequired when type is bank_account. Describes a Ghana bank account for wire transfers and direct debits.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Bank account type. Currently only ghana_bank_account is supported.
- Name
  ghana_bank_account
  Type
  object
  Description
  Ghana bank account details. Required when type is ghana_bank_account.
  View ghana_bank_account attributesClick or tap to expand
  Name
  number
  Type
  string
  Description
  Bank account number at the Ghanaian bank.
  Name
  sort_code
  Type
  string
  Description
  Bank sort code (required if swift_code is not provided). Six-digit code identifying the bank branch.
  Name
  swift_code
  Type
  string
  Description
  Bank SWIFT/BIC code (required if sort_code is not provided). Eight or eleven character code identifying the bank internationally.
  Name
  holder
  Type
  object
  Description
  Account holder information—required for compliance and successful transfers.
  View holder attributesClick or tap to expand
  Name
  name
  Type
  string
  Description
  Account holder's full legal name—must match bank records exactly.
  Name
  address
  Type
  object
  Description
  Account holder's physical address for regulatory compliance.
  View address attributesClick or tap to expand
  Name
  city
  Type
  string
  Description
  City or town (required).
  Name
  country
  Type
  string
  Description
  Country code or name (required—e.g., "Ghana", "gh").
  Name
  line_1
  Type
  string
  Description
  First line of the street address (required).
  Name
  line_2
  Type
  string
  Description
  Second line of the address (optional—for apartment numbers, suite, etc.).
  Name
  name
  Type
  string
  Description
  Name or title of the address (required—e.g., "Home Address", "Business Address").
  Name
  phone
  Type
  string
  Description
  Contact phone number (optional).
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code (optional).
  Name
  region
  Type
  string
  Description
  Region or state (required—e.g., "Greater Accra", "Ashanti").

Optional attributes

Name
custom_data
Type
object
Description
Arbitrary key-value pairs for storing additional information about this account. Useful for attaching metadata, internal references, or application-specific data.
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.
ownerobjectAccount owner information—name and address of the person or business that holds this financial account. Required for bank accounts, optional for wallets. Useful for compliance, audit trails, and multi-beneficiary setups.Click or tap to expand
- Name
  name
  Type
  string
  Description
  Account owner's full legal name.
- Name
  address
  Type
  object
  Description
  Owner's physical address.
  View address attributesClick or tap to expand
  Name
  city
  Type
  string
  Description
  City or town (required).
  Name
  country
  Type
  string
  Description
  Country code or name (required).
  Name
  line_1
  Type
  string
  Description
  First line of the street address (required).
  Name
  line_2
  Type
  string
  Description
  Second line of the address (optional).
  Name
  name
  Type
  string
  Description
  Name or title of the address (required).
  Name
  phone
  Type
  string
  Description
  Contact phone number (optional).
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code (optional).
  Name
  region
  Type
  string
  Description
  Region or state (required).
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.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.
pull_configurationobjectEnable pull operations (debit funds from this account into your Commerce balance). Commerce automatically captures mandate authorization from the request context (IP address and user agent) when you enable this.Click or tap to expand
- Name
  enabled
  Type
  boolean
  Description
  Set true to enable pull operations. Commerce will create a mandate record automatically from the HTTP request context for regulatory compliance.

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_configuration": { "enabled": true },
    "pull_configuration": { "enabled": false }
  }'

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "label": "Konadu Tailoring Collections",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T10:22:11.745Z"
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account": "0242057831",
        "network": "mtn"
      }
    }
  }
}

POST/financial_accounts/disconnect

Disconnect a financial account

Permanently disconnect a financial account—marks it as no longer usable for payouts or charges while preserving it for historical reference. Use this when closing a business relationship (vendor partnership ended, switching to a different provider) or when an external account has been closed at the financial institution.

Disconnected accounts remain visible in account lookups and listings so you can trace historical transactions, reconcile past payouts, and maintain audit trails. However, they cannot be used for new operations: you can't send payouts to them, pull funds from them, or configure them as payout destinations.

If the account is currently configured as a payout destination for any currency, the request fails unless you either remove it from payout destinations first or set unset_as_payout_destination to true. This prevents accidentally breaking automatic payouts.

This operation is idempotent—disconnecting an already-disconnected account succeeds without error. The disconnected_at timestamp marks when the account was first disconnected.

When to use each operation:

Disconnect: Permanent deactivation when the external account is closed or the relationship ends. Account remains visible but unusable.
Disable push/pull: Temporary suspension of specific capabilities. Can be re-enabled later without reconnecting.
Archive: Hide the account from default listings while keeping it retrievable by ID. Use for cleanup when you have many inactive accounts.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to disconnect. Required.
Name
unset_as_payout_destination
Type
boolean
Description
Optional. When true, automatically removes this financial account from all payout destinations before disconnecting. Defaults to false. Set this to true if you want to disconnect an account that's currently configured as a payout destination—the API will first unset it as a destination, then mark it as disconnected.

Request

POST

/financial_accounts/disconnect

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

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "currency": "ghs",
    "type": "wallet",
    "label": "Vendor settlement - MTN",
    "description": "Payout destination for marketplace vendor settlements",
    "disconnected_at": "2025-03-22T14:35:18.221Z",
    "created_at": "2025-01-15T09:12:33.445Z"
  }
}

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 a financial account to register existing accounts. Contact support to enable account creation capabilities for your Commerce account.

Request and response

The request structure and response format are identical to Connect a financial account. The difference is in what happens behind the scenes—Create provisions a new account with partner institutions, while Connect registers an existing account. See the Connect documentation for complete parameter descriptions and response structure.

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",
    "archived_at": null,
    "created_at": "2025-03-18T11:30:00.000Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Corporate account for vendor disbursements and payroll.",
    "label": "Ecobank - Operations",
    "owner": {
      "name": "TechFlow Industries Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "Independence Avenue",
        "line_2": "4th Floor, Tech Plaza",
        "name": "Corporate Office",
        "phone": "+233302567890",
        "post_code": "GA-187",
        "region": "Greater Accra"
      }
    },
    "reference": "TECHFLOW-ECOBANK-PAYROLL",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "1234567890",
        "name": "ECOBANK GHANA LTD",
        "branch": "Independence Avenue Branch",
        "swift_code": "ECOCGHAC",
        "sort_code": "130101",
        "holder": {
          "name": "TechFlow Industries Ltd",
          "address": {
            "city": "Accra",
            "country": "Ghana",
            "line_1": "Independence Avenue",
            "line_2": "4th Floor, Tech Plaza",
            "name": "Corporate Office",
            "phone": "+233302567890",
            "post_code": "GA-187",
            "region": "Greater Accra"
          }
        }
      }
    }
  }
}

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",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {
      "vendor_id": "VNDR-001",
      "region": "Greater Accra"
    },
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "label": "Konadu Tailoring Collections",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "pull_configuration": {
      "enabled_at": "2025-03-17T14:30:00.000Z",
      "mandate": {
        "id": "man_K3Lx9PqW7jZ2vN8mR5tY1hC6bF4dS0gA",
        "created_at": "2025-03-17T14:30:00.000Z",
        "ip_address": "102.176.95.12",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T10:22:11.745Z"
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account": "0242057831"
      }
    }
  }
}

POST/financial_accounts/update

Update a financial account

Update an existing financial account's label, description, reference, or custom data. Use this to keep account metadata in sync with your application state—rename accounts when business contexts change, attach updated internal references, or store additional metadata for reconciliation and reporting.

Unlike Connect or Create, Update doesn't modify the underlying financial account details (network, account number, bank details). It only changes the descriptive metadata and custom data stored in your Commerce account. To change capabilities (enable/disable push or pull), use the dedicated enable/disable endpoints.

Note: The type field and account-type-specific objects (wallet, bank_account, dosh_account) are immutable and cannot be updated. Attempts to modify these fields will be rejected with a validation error. If you need to change the account type or underlying account details, create a new financial account instead.

The response includes the full account object with updated fields, plus owner, custom_data, and any enabled push_configuration or pull_configuration. This is the most comprehensive response of all FA endpoints.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to update. Required.
Name
label
Type
string
Description
New human-readable name (5–40 characters). Optional—omit to keep current value.
Name
description
Type
string
Description
New long-form description (up to 200 characters). Optional—omit to keep current value.
Name
reference
Type
string
Description
New internal identifier (5–40 characters). Optional—omit to keep current value.
Name
custom_data
Type
object
Description
Key-value pairs to merge into existing custom data. Optional—omit to keep current custom data unchanged.

Request

POST

/financial_accounts/update

curl https://api.zebo.dev/financial_accounts/update \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "label": "Konadu Tailoring - Primary",
    "custom_data": {
      "vendor_id": "VNDR-001",
      "region": "Greater Accra"
    }
  }'

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {
      "vendor_id": "VNDR-001",
      "region": "Greater Accra"
    },
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "label": "Konadu Tailoring - Primary",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T10:22:11.745Z"
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account": "0242057831",
        "network": "mtn"
      }
    }
  }
}

POST/financial_accounts/enable_pull

Enable pull capability

Enable pull operations on an existing financial account—allows you to debit funds from this account into your Commerce balance. Use this for balance top-ups, subscription renewals, recurring payments, or sweeping funds from connected accounts.

When you enable pull, Commerce automatically creates a mandate record from the HTTP request context (IP address and user agent) for regulatory compliance and dispute resolution. This mandate is captured once and persists for the lifetime of the pull configuration.

The response returns the full account object including all account details, the newly enabled pull_configuration with mandate, and any other configurations or account-type-specific details.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to enable pull for. Required.

Request

POST

/financial_accounts/enable_pull

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

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Operations account for collections and transfers.",
    "label": "GCB Bank - Collections",
    "owner": {
      "name": "QuickPay Solutions Ltd",
      "address": {
        "city": "Kumasi",
        "country": "Ghana",
        "line_1": "Adum Commercial Street",
        "line_2": "Building 12",
        "name": "Regional Office",
        "phone": "+233322098765",
        "post_code": "AK-039",
        "region": "Ashanti"
      }
    },
    "pull_configuration": {
      "enabled_at": "2025-03-18T11:45:22.103Z",
      "mandate": {
        "id": "man_K3Lx9PqW7jZ2vN8mR5tY1hC6bF4dS0gA",
        "created_at": "2025-03-18T11:45:22.103Z",
        "ip_address": "102.176.95.12",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
      }
    },
    "reference": "QUICKPAY-GCB-COLLECTIONS",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "0123456789",
        "name": "GCB BANK LTD",
        "branch": "Adum Branch",
        "swift_code": "GHCBGHAC",
        "sort_code": "040211",
        "holder": {
          "name": "QuickPay Solutions Ltd",
          "address": {
            "city": "Kumasi",
            "country": "Ghana",
            "line_1": "Adum Commercial Street",
            "line_2": "Building 12",
            "name": "Regional Office",
            "phone": "+233322098765",
            "post_code": "AK-039",
            "region": "Ashanti"
          }
        }
      }
    }
  }
}

POST/financial_accounts/disable_pull

Disable pull capability

Disable pull operations on a financial account—prevents future debits from this account into your Commerce balance. Use this when you no longer need to pull funds (subscription cancelled, balance source retired) or when temporarily suspending pull capability for security or compliance reasons.

Disabling pull retains the existing mandate record and enabled_at timestamp for audit trails—the configuration remains visible but operations are blocked. To fully remove pull capability history, archive the account.

The response returns the full account object including all account details and the current pull_configuration with the original enabled_at and mandate details preserved.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to disable pull for. Required.

Request

POST

/financial_accounts/disable_pull

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

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Primary settlement wallet for Konadu's B2C operations.",
    "label": "Konadu Tailoring Collections",
    "owner": {
      "name": "Konadu Tailoring Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "123 High Street",
        "line_2": "Suite 4",
        "name": "Business Address",
        "phone": "+233242057831",
        "post_code": "GA-123",
        "region": "Greater Accra"
      }
    },
    "reference": "KONADU-MOMO-SETTLEMENT",
    "type": "wallet",
    "wallet": {
      "id": "wal_TJPFxX9C3651K6Sb5RXjc9gIH4KjzqZIiD0WQsZ",
      "type": "mobile_money",
      "mobile_money": {
        "account": "0242057831",
        "network": "mtn"
      }
    }
  }
}

POST/financial_accounts/enable_push

Enable push capability

Enable push operations on an existing financial account—allows you to send funds from your Commerce balance to this account. Use this for vendor disbursements, customer refunds, earnings payouts, marketplace settlements, or any scenario where you need to transfer funds out of your balance.

The response returns the full account object including all account details and the new push_configuration object with the enabled_at timestamp.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to enable push for. Required.

Request

POST

/financial_accounts/enable_push

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

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Business account for payroll and vendor settlements.",
    "label": "Stanbic Bank - Payroll",
    "owner": {
      "name": "TechFlow Ghana Ltd",
      "address": {
        "city": "Accra",
        "country": "Ghana",
        "line_1": "Airport City",
        "line_2": "Building 5",
        "name": "Head Office",
        "phone": "+233302456789",
        "post_code": "GA-234",
        "region": "Greater Accra"
      }
    },
    "push_configuration": {
      "enabled_at": "2025-03-18T11:52:07.845Z"
    },
    "reference": "TECHFLOW-STANBIC-PAYROLL",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "5678901234",
        "name": "STANBIC BANK GHANA LTD",
        "branch": "Airport City Branch",
        "swift_code": "SBICGHAC",
        "sort_code": "190102",
        "holder": {
          "name": "TechFlow Ghana Ltd",
          "address": {
            "city": "Accra",
            "country": "Ghana",
            "line_1": "Airport City",
            "line_2": "Building 5",
            "name": "Head Office",
            "phone": "+233302456789",
            "post_code": "GA-234",
            "region": "Greater Accra"
          }
        }
      }
    }
  }
}

POST/financial_accounts/disable_push

Disable push capability

Disable push operations on a financial account—completely removes push capability and prevents future transfers from your Commerce balance to this account. Use this when you no longer need to send funds (vendor relationship ended, payout destination changed) or when suspending push capability for security or compliance reasons.

If the financial account is configured as a payout destination for any currency, the request fails unless you either remove it from payout destinations first or set unset_as_payout_destination to true. This safety check prevents accidentally breaking automatic payouts by disabling push on accounts that are actively receiving settlements.

Disabling push clears the push configuration entirely—the push_configuration object becomes null in the response. If you need to send funds to this account again later, you'll need to re-enable push capability with Enable push capability, which creates a new configuration with a fresh enabled_at timestamp. For permanent deactivation that prevents all future use, see Disconnect a financial account.

The response returns the full account object with push_configuration set to null.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to disable push for. Required.
Name
unset_as_payout_destination
Type
boolean
Description
Optional. When true, automatically removes this financial account from all payout destinations before disabling push. Defaults to false. Set this to true if you want to disable push on an account that's currently configured as a payout destination—the API will first unset it as a destination, then disable push capability.

Request

POST

/financial_accounts/disable_push

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

Response

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "archived_at": null,
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Settlement account for marketplace operations.",
    "label": "Fidelity Bank - Settlement",
    "owner": {
      "name": "MarketHub Ghana Ltd",
      "address": {
        "city": "Kumasi",
        "country": "Ghana",
        "line_1": "Adum High Street",
        "line_2": "Floor 2",
        "name": "Regional Office",
        "phone": "+233322567890",
        "post_code": "AK-123",
        "region": "Ashanti"
      }
    },
    "reference": "MARKETHUB-FIDELITY-SETTLEMENT",
    "type": "bank_account",
    "bank_account": {
      "type": "ghana_bank_account",
      "ghana_bank_account": {
        "number": "4567890123",
        "name": "FIDELITY BANK GHANA",
        "branch": "High Street Branch",
        "swift_code": "FIDEGHAC",
        "sort_code": "240103",
        "holder": {
          "name": "MarketHub Ghana Ltd",
          "address": {
            "city": "Kumasi",
            "country": "Ghana",
            "line_1": "Adum High Street",
            "line_2": "Floor 2",
            "name": "Regional Office",
            "phone": "+233322567890",
            "post_code": "AK-123",
            "region": "Ashanti"
          }
        }
      }
    }
  }
}