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

Each transaction records a payment amount and links it to its payment and order. Optional payout and lifecycle timestamps are omitted until they are available.

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 associated with this balance movement.
Name
payout_id
Type
string
Description
Payout that claimed this transaction. Omitted until the transaction is assigned to a payout.
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.
amountobjectPayment amount that cleared settlement. Represents the actual spendable funds from this transaction in your available balance.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.
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
available_at
Type
timestamp
Description
When funds became available for payout. Omitted while the transaction is pending.
Name
claimed_at
Type
timestamp
Description
When a payout claimed this transaction. Omitted until the claim occurs.
Name
paid_at
Type
timestamp
Description
When the payout containing these funds completed. Omitted until the payout succeeds.

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 response, or when reconciling your books against platform records. The lookup now requires only transaction_id. Commerce resolves the record through the application-scoped balance-transaction ID index, so you no longer need to supply the originating payment or order IDs.

Request attributes

Name
transaction_id
Type
string
Description
Balance transaction ID from a previous API response or dashboard export. This is the only lookup key required.

Request

POST

/balance_transactions/lookup

curl https://api.zebo.dev/balance_transactions/lookup \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "bt_Md9cV6cRWj2W8dS5wU7fQxBb"
  }'

{
  "transaction": {
    "id": "bt_Md9cV6cRWj2W8dS5wU7fQxBb",
    "payment_id": "py_Qs1sYW5nJXw4QjV8EJr0FDAs",
    "order_id": "or_Jc5Tm1YkQq9n3Pb8Ls2F0Dhz",
    "amount": {
      "currency": "ghs",
      "value": 22000
    },
    "created_at": "2025-04-10T12:02:45.000Z",
    "available_at": "2025-04-10T12:03:17.000Z",
    "claimed_at": "2025-04-17T10:00:00.000Z"
  }
}

Page through balance transactions

Iterate through balance transactions in your Commerce account. Both pagination fields are required. Page numbering is 0-based.

Request attributes

Name
page_number
Type
integer
Description
Required 0-based page index between 0 and 10.
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 $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_number": 0,
    "page_size": 2
  }'

{
  "page": {
    "number": 0,
    "size": 2,
    "transactions": [
      {
        "id": "bt_Za2bL9kPxV1c4Gs7Ju0DrQhn",
        "payment_id": "py_mJ2nP8dLs4Rj7Xc1Bv6ThQw",
        "payout_id": "po_Xr8kQ4nLs2Fv9Mh1Pc6DtGjb",
        "order_id": "or_Lp9Fc4VsQm2n7Gx0Hd3WaTjy",
        "amount": {
          "currency": "ghs",
          "value": 12200
        },
        "created_at": "2025-04-11T09:34:40.000Z",
        "available_at": "2025-04-11T09:35:02.000Z",
        "paid_at": "2025-04-18T10:00:15.000Z"
      },
      {
        "id": "bt_Ps8wC1nDf5m9Qh2Vt6YkRgLb",
        "payment_id": "py_xR4kN1sDf7Lh2Pw9Vm3CtGb",
        "order_id": "or_Qs6Xv2NaLp9Fz1Md4KgRtBhj",
        "amount": {
          "currency": "ghs",
          "value": 8800
        },
        "created_at": "2025-04-10T21:17:05.000Z",
        "available_at": "2025-04-10T21:18:20.000Z"
      }
    ]
  }
}