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.

Connect, create, update, disconnect, reconnect, enable pull, disable pull, enable push, and disable push support idempotency. A successful response can be replayed with the same idempotency key and request body for 24 hours. Lookup and page do not opt in to idempotent replay.

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
Description
When this account was archived and made unavailable for new operations. Omitted 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. Financial-account create and connect currently accept ghs.
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
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
Description
When this account was disconnected and marked as unusable for payouts or charges. Omitted for connected accounts. Reconnecting the account removes this field again.
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 when it was provided during creation, connection, or update.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
Description
Verification lifecycle metadata when available. Omitted when no verification record exists.
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. For bank-account requests, Commerce fills missing holder name or address fields from the top-level owner when available.
  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_number
  Type
  string
  Description
  Subscriber phone number (MSISDN) in local or international format. The API normalizes format automatically.
  Name
  network
  Type
  string
  Description
  One of airtel, mtn, telecel, or vodafone.

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: Currently ghs.
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, wallet.type must be mobile_money. A Dosh account uses the top-level dosh_account type and a dosh_account object.
Bank account-specific: When type is bank_account, provide bank_account.type as ghana_bank_account, an account number, and at least one of sort_code or swift_code. holder and top-level owner are optional.
Push/Pull config: push_configuration.enabled and pull_configuration.enabled are optional booleans. The connect request does not accept authorization context fields for pull; use Enable pull capability when you need to submit them.

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. Currently ghs.
dosh_accountobjectRequired as an empty object when type is dosh_account.Click or tap to expand
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. Currently mobile_money.
- 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
  One of airtel, mtn, telecel, or vodafone.
  Name
  account_number
  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
  Optional account holder information.
  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 code or name.
  Name
  line_1
  Type
  string
  Description
  First line of the street address.
  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.
  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.

Optional attributes

Name
custom_data
Type
object
Description
Arbitrary string key-value pairs for application-specific needs. Attach reconciliation identifiers, internal classifications, accounting codes, or any metadata your system requires. Maximum size when serialized: 25 KB. See the Custom Data guide for best practices.
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.
ownerobjectOptional account owner information. All nested owner and address fields are optional when the object is provided.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 code or name.
  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
  Name or title of the 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.
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_configurationobjectSet whether pull operations are enabled on creation. To record authorization context, call Enable pull after creating the account.Click or tap to expand
- Name
  enabled
  Type
  boolean
  Description
  Set true to enable pull operations.

Request

POST

/financial_accounts/connect

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

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Primary settlement wallet for Konadu 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_number": "0242057831",
        "network": "mtn"
      }
    }
  }
}

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: Account-level deactivation that keeps the record for history. Use this when you need to stop all new use immediately.
Reconnect: Clears disconnected_at and restores local usability on the same account record. This does not rerun provider authorization.
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 $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "unset_as_payout_destination": true
  }'

{
  "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"
  }
}

Reconnect a financial account

Restore a previously disconnected financial account to active local state. Use this when the same external account relationship is valid again and you want to keep using the original Commerce financial-account record instead of creating a new one.

Reconnect only clears the account-level disconnected_at state. It preserves the same account ID, historical payouts or charges, and any existing push or pull configuration already stored on the record. If you removed this account from payout destinations during disconnect, set those destinations again separately.

This endpoint does not perform provider-side authorization. If your account type requires provider authorization for pull or push capability, that authorization happens separately in later capability flows.

This operation is idempotent—reconnecting an already-active account succeeds without error.

Request attributes

Name
account_id
Type
string
Description
Unique identifier of the account to reconnect. Required.

Request

POST

/financial_accounts/reconnect

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

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

Create a financial account

Create and register a financial-account resource for supported Commerce flows. The operation does not guarantee that a new external wallet or bank account is provisioned.

Request and response

The request structure and response format match Connect a financial account. See that operation for the complete discriminated request shape.

Request

POST

/financial_accounts/create

curl https://api.zebo.dev/financial_accounts/create \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -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_number": "0244123456"
      }
    }
  }'

{
  "account": {
    "id": "fa_X1Y2Z3A4B5C6D7E8F9G0H1I2J3K4L5M6N7O8P9Q",
    "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"
          }
        }
      }
    }
  }
}

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 $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
  }'

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "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 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_number": "0242057831"
      }
    }
  }
}

Update a financial account

Update an existing financial account's custom data, description, label, owner, or reference.

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
custom_data
Type
object
Description
Application-specific metadata. Keys are merged into the existing object; a key sent as null is deleted. Maximum size: 25 KB when serialized.
Name
description
Type
string
Description
New description. The update parser does not apply a length bound; omit it to keep the current value.
Name
label
Type
string
Description
New human-readable name. The update parser does not apply a length bound; omit it to keep the current value.
Name
owner
Type
object
Description
Replacement owner object. name and all nested address fields are optional.
Name
reference
Type
string
Description
New reference. The update parser does not apply a length bound; omit it to keep the current value.

Request

POST

/financial_accounts/update

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

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "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 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_number": "0242057831",
        "network": "mtn"
      }
    }
  }
}

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.

You can optionally send the authorization request's ip_address and user_agent. Omit either field when it is unavailable; the API does not derive these values automatically for this operation.

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.
Name
ip_address
Type
string
Description
IP address associated with the authorization, when available.
Name
user_agent
Type
string
Description
User agent associated with the authorization, when available.

Request

POST

/financial_accounts/enable_pull

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

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "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"
          }
        }
      }
    }
  }
}

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 $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
  }'

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "created_at": "2025-03-18T10:22:11.745Z",
    "currency": "ghs",
    "custom_data": {},
    "description": "Primary settlement wallet for Konadu 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_number": "0242057831",
        "network": "mtn"
      }
    }
  }
}

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 $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
  }'

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "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"
          }
        }
      }
    }
  }
}

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 removes push_configuration from the response. If you need to send funds to this account again later, re-enable push capability with Enable push capability.

The response returns the full account object without push_configuration.

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 $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
  }'

{
  "account": {
    "id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
    "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"
          }
        }
      }
    }
  }
}

Page through financial accounts

Retrieve a paginated list of your financial accounts sorted by creation time in descending order. Page 1 always contains the most recently created accounts, with subsequent pages stepping back in time. Use this to build account selection interfaces, export account data, or audit account configurations.

Request attributes

Name
page_number
Type
integer
Description
1-based page index to fetch. Must be between 1 and 10 inclusive.
Name
page_size
Type
integer
Description
Number of accounts per page. Must be between 1 and 256 inclusive. Defaults to 256 when omitted. The response echoes the actual count returned—the last page may contain fewer accounts than requested.

Response shape

Top-level page object contains number, size, and an accounts array
Each account includes all configuration: id, type, currency, label, description, reference, custom_data, created_at, and archived_at (when applicable)
Type-specific details are nested under wallet, bank_account, or dosh_account
Push/pull configurations are included when enabled: push_configuration and pull_configuration
Archived accounts are included in results—filter on archived_at if you need active accounts only

Request

POST

/financial_accounts/page

curl https://api.zebo.dev/financial_accounts/page \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_number": 1,
    "page_size": 50
  }'

{
  "page": {
    "number": 1,
    "size": 50,
    "accounts": [
      {
        "id": "fa_abc123xyz",
        "type": "wallet",
        "currency": "ghs",
        "label": "Primary Mobile Money",
        "description": "Main MTN wallet for customer payouts",
        "reference": "mtn_primary",
        "custom_data": {
          "region": "greater_accra",
          "purpose": "payouts"
        },
        "created_at": "2025-11-23T10:00:00Z",
        "push_configuration": {
          "enabled_at": "2025-11-23T10:05:00Z"
        },
        "wallet": {
          "id": "wa_xyz789",
          "type": "mobile_money",
          "mobile_money": {
            "network": "mtn",
            "account_number": "024205****"
          }
        }
      },
      {
        "id": "fa_def456uvw",
        "type": "bank_account",
        "currency": "ghs",
        "label": "Settlement Account",
        "created_at": "2025-11-20T14:30:00Z",
        "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",
                "region": "Ashanti"
              }
            }
          }
        }
      }
    ]
  }
}