Balance Transactions

Balance transactions record how funds flow from customer payments into your available balance. Each transaction captures the lifecycle of a payment's funds: when they're recognized, when they settle and become available, and when they're included in a payout. Think of them as ledger entries that bridge the gap between a successful payment and money you can actually move—essential for reconciliation, financial reporting, and understanding your cash flow in real time.

The Balance Transaction object

Every transaction is born when a payment succeeds. It tracks two critical amounts: the gross payment value you expect to receive (amount_expected) and the net funds that actually cleared after settlement (amount_available). The transaction links back to its originating payment and order, carries timestamps for creation and availability, and gets tagged with payout information once those funds leave your balance. This structure lets you trace every dollar from customer checkout through to bank transfer.

Properties

Name
id
Type
string
Description
Unique identifier for this balance transaction—use it as the primary key in lookups and as your reconciliation anchor when matching transactions to external records.
Name
payment_id
Type
string
Description
Payment that generated this balance movement. Every balance transaction maps 1:1 with a successful payment—use this ID to retrieve the complete payment context.
Name
order_id
Type
string
Description
Order associated with the payment. Helpful when you need to trace funds back to the original customer purchase, line items, or invoice.
amount_expectedobjectGross payment amount before settlement—the full value the customer paid. This number stays constant and represents your initial revenue recognition.Click or tap to expand
- Name
  currency
  Type
  string
  Description
  ISO 4217 currency code in lowercase (e.g., ghs, usd, eur)—matches the payment currency.
- Name
  value
  Type
  integer
  Description
  Amount in the smallest currency unit: pesewas for GHS, cents for USD/EUR, yen for JPY, etc.
amount_availableobjectNet funds that cleared settlement and are ready for payout. May differ from expected amount due to processing fees, chargebacks, or adjustments. null until the transaction settles.Click or tap to expand
- Name
  currency
  Type
  string
  Description
  Always matches the payment currency—no cross-currency settlements within a single transaction.
- Name
  value
  Type
  integer
  Description
  Actual spendable amount in the smallest currency unit—this is what you can include in payouts.
Name
available_at
Type
timestamp|null
Description
When funds settled and became available for payout. null while the transaction is pending—typically moves from null to a timestamp within minutes to hours of payment success, depending on the payment method and provider settlement times.
Name
created_at
Type
timestamp
Description
When we recorded this transaction—usually within milliseconds of the payment succeeding. Use this for chronological ordering and audit trails.
Name
payout_id
Type
string|null
Description
Set once this transaction's funds are included in a payout batch. null means funds are still in your available balance and haven't been transferred out yet. Use /payouts/lookup with this ID to see where the funds went and when the transfer completed.
Name
paid_at
Type
timestamp|null
Description
When the payout containing these funds completed and money left your balance. null until the payout executes—after this timestamp, the funds are no longer part of your available balance.

POST/balance_transactions/lookup

Look up a balance transaction

Fetch the current state of a specific balance transaction. You'll typically use this after receiving a transaction ID from an order or payment webhook, or when reconciling your books against platform records. The lookup requires all three identifiers—transaction, payment, and order—to ensure you're retrieving the exact record you expect, even in edge cases where IDs might collide across different contexts.

Request attributes

Name
transaction_id
Type
string
Description
Balance transaction ID from a previous API response, webhook payload, or dashboard export. This is your primary lookup key.
Name
payment_id
Type
string
Description
Payment that created this transaction. Required for scoping—ensures the transaction belongs to the payment you're expecting.
Name
order_id
Type
string
Description
Order that initiated the payment. Completes the lookup context and prevents ambiguity in multi-payment scenarios.

Request

POST

/balance_transactions/lookup

curl https://api.zebo.dev/balance_transactions/lookup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "bal_txn_Md9cV6cRWj2W8dS5wU7fQxBb",
    "payment_id": "pay_Qs1sYW5nJXw4QjV8EJr0FDAs",
    "order_id": "ord_Jc5Tm1YkQq9n3Pb8Ls2F0Dhz"
  }'

Response

{
  "transaction": {
    "id": "bal_txn_Md9cV6cRWj2W8dS5wU7fQxBb",
    "payment_id": "pay_Qs1sYW5nJXw4QjV8EJr0FDAs",
    "order_id": "ord_Jc5Tm1YkQq9n3Pb8Ls2F0Dhz",
    "amount_expected": {
      "currency": "ghs",
      "value": 22000
    },
    "amount_available": {
      "currency": "ghs",
      "value": 22000
    },
    "available_at": "2025-04-10T12:03:17.000Z",
    "created_at": "2025-04-10T12:02:45.000Z"
  }
}

POST/balance_transactions/page

Page through balance transactions

Iterate through all balance transactions in your Commerce account, ordered from newest to oldest. This is your workhorse for building internal dashboards, running nightly reconciliation jobs, or exporting transaction history for accounting systems. Transactions are returned in reverse chronological order by created_at, so page 1 always shows your most recent activity. Use reasonable page sizes (10–50 for UI, 100+ for batch processing) to balance response time against number of round trips.

Request attributes

Name
page_number
Type
integer
Description
Which page to retrieve, starting at 1 for the first page. Increment this to walk through your entire transaction history.
Name
page_size
Type
integer
Description
How many transactions to return per page. Minimum 1, maximum 256. Pick larger values for bulk exports, smaller for real-time UI updates.

Request

POST

/balance_transactions/page

curl https://api.zebo.dev/balance_transactions/page \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "page_number": 1,
    "page_size": 2
  }'

Response

{
  "page": {
    "page_number": 0,
    "page_size": 2,
    "transactions": [
      {
        "id": "bal_txn_Za2bL9kPxV1c4Gs7Ju0DrQhn",
        "payment_id": "pay_mJ2nP8dLs4Rj7Xc1Bv6ThQw",
        "order_id": "ord_Lp9Fc4VsQm2n7Gx0Hd3WaTjy",
        "amount_expected": { "currency": "ghs", "value": 12200 },
        "amount_available": { "currency": "ghs", "value": 12200 },
        "available_at": "2025-04-11T09:35:02.000Z",
        "created_at": "2025-04-11T09:34:40.000Z"
      },
      {
        "id": "bal_txn_Ps8wC1nDf5m9Qh2Vt6YkRgLb",
        "payment_id": "pay_xR4kN1sDf7Lh2Pw9Vm3CtGb",
        "order_id": "ord_Qs6Xv2NaLp9Fz1Md4KgRtBhj",
        "amount_expected": { "currency": "ghs", "value": 8800 },
        "amount_available": null,
        "available_at": null,
        "created_at": "2025-04-10T21:17:05.000Z"
      }
    ]
  }
}