Balances

Each currency you have ever collected in has three buckets. pending holds captured collections (net of fees) that have not yet been released by settlement. available is money released to you: payouts and refunds draw on it. locked is money held by reserves in flight, for example a refund that has been created but has not yet settled.

Money moves between the buckets only through balanced ledger journals: a completed collection captures its net amount into pending; the settlement engine releases pending into available on your settlement schedule; creating a payout or refund reserves out of available. Because both endpoints read the same ledger, the balance you see always equals the sum of its balance transactions.

Amounts are decimal strings in each row currency. Zero-decimal currencies such as XAF and XOF are whole numbers, so 194,000 XAF reads "194000", never "194000.00" and never 19400000.

Your API key environment selects the ledger you read: sandbox keys see sandbox balances, live keys see production balances. The two never mix.

One row per currency, covering every currency your account has ever touched in this environment. No parameters.

The balances:read scope is required.

Example request

curl https://api.capayglobal.com/v1/balances \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa"

Example response

{
  "status": "success",
  "data": {
    "object": "list",
    "data": [
      {
        "currency": "XAF",
        "available": "194000",
        "pending": "45000",
        "locked": "3000",
        "livemode": false
      },
      {
        "currency": "NGN",
        "available": "150000.00",
        "pending": "0.00",
        "locked": "0.00",
        "livemode": false
      }
    ],
    "has_more": false
  },
  "request_id": "b1e2c3d4-5f60-4a71-8b92-c0d1e2f3a4b5"
}

Each row of the list carries:

Every ledger movement that touched one of your balance buckets, newest first. Each row is one leg of a balanced journal: a settlement release, for example, appears twice, once leaving pending and once arriving in available, both sharing the same journal_reference.

The balances:read scope is required.

Query parameters

Example request

curl "https://api.capayglobal.com/v1/balance_transactions?currency=XAF&limit=3" \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa"

Example response

{
  "status": "success",
  "data": {
    "object": "list",
    "data": [
      {
        "id": "txn_1042",
        "object": "balance_transaction",
        "amount": "45000",
        "currency": "XAF",
        "account": "available",
        "journal_reference": "stl:0f9a2c34-6b1d-4e8a-9c21-7d2f5a1b3c4d:release",
        "journal_kind": "settlement_release",
        "posted_at": "2026-08-31T17:00:01.000Z",
        "livemode": false,
        "settlement_payout": null,
        "fx": null
      },
      {
        "id": "txn_1041",
        "object": "balance_transaction",
        "amount": "-45000",
        "currency": "XAF",
        "account": "pending",
        "journal_reference": "stl:0f9a2c34-6b1d-4e8a-9c21-7d2f5a1b3c4d:release",
        "journal_kind": "settlement_release",
        "posted_at": "2026-08-31T17:00:01.000Z",
        "livemode": false,
        "settlement_payout": null,
        "fx": null
      },
      {
        "id": "txn_987",
        "object": "balance_transaction",
        "amount": "4900",
        "currency": "XAF",
        "account": "pending",
        "journal_reference": "col:7d2f5a1b-3c4d-4e8a-9c21-0f9a2c346b1d:capture",
        "journal_kind": "collection_capture",
        "posted_at": "2026-08-29T12:35:11.000Z",
        "livemode": false,
        "settlement_payout": null,
        "fx": null
      }
    ],
    "has_more": false
  },
  "request_id": "c2d3e4f5-6a71-4b82-9c03-d1e2f3a4b5c6"
}

Each balance transaction carries:

has_more is true when the page is full, meaning older movements exist beyond it. This list is paged by limit only, with no cursor yet: to reach further back, narrow with the currency filter, or reconcile against the collection, payout and refund resources whose ids the journal references carry.

Movements posted by a manual settlement payout carry settlement_payout and, when the payout crossed currencies, fx: Capay Global settles by hand and converts nothing automatically, so the fx line reports the executed rate, never a promise. The How you get paid guide walks through it.

journal_kind tells you why money moved. The vocabulary is additive: new kinds may appear as the platform grows, so treat unknown values as "other movement" rather than an error.

• collection_capture - A completed collection captured its net amount into pending.
• settlement_release - A settlement batch released pending into available.
• payout_reserve - A payout was created and reserved its amount out of available.
• payout_settle - A payout completed and its reserve settled.
• payout_reverse - A payout failed or was reversed and its reserve returned to available.
• refund_reserve - A refund was created and reserved its amount.
• refund_settle - A refund completed and its reserve settled back to the payer.
• refund_reverse - A refund failed and its reserve was released.
• settlement_payout - A manual settlement payout debited available; the row carries settlement_payout and, for stablecoin payouts, fx.
• settlement_payout_reverse - A manual settlement payout failed or was cancelled and its amount returned to available.
• simfund - Sandbox only: test funds added by the sandbox funding endpoint.

Errors use the standard envelope: a machine-readable code, a human message, and a next_step. Every error carries the request_id to quote to support.