Skip to main content
GET
Get wallet balances
Fetch wallet balances associated with the product tied to your token (e.g., Collections, Payouts). Optionally filter by a specific currency (e.g., KES). If omitted, all balances for the product are returned.

Environments


Endpoint


Example request


Authentication

This endpoint requires a Bearer token that is scoped to the product you are querying (e.g., a Collections token can only view Collections balances; a Payouts token can only view Payouts balances).
If the token is invalid, expired, or not authorized for the requested product, you’ll receive 401 Unauthorized.

Query parameters


Successful responses

200 OK - All balances (no filter)

200 OK - Specific currency present

  • actual_balance is the total ledger balance.
  • available_balance is the spendable amount after holds/reserves.
  • alert_limit is your configured low-balance threshold, if any.
  • status reflects wallet state, for example ACTIVE, INACTIVE, or SUSPENDED.

Error responses

404 Not Found - Currency not provisioned for this product

401 Unauthorized - Bad/expired token or wrong scope


Behavior & constraints

  • Product scoping: The Bearer token determines which product’s wallets are visible (e.g., Collections vs Payouts).
  • Filtering: currency is optional; when omitted, all provisioned wallets for the token’s product are returned.
  • Idempotency: This is a GET and does not change state; no idempotency key required.
  • Caching: Avoid caching balances client-side if you need real-time accuracy.
  • Rate limits: Standard platform rate limits apply. Handle 429 with retries and backoff.
  • Currency codes: Must be ISO 4217 uppercase; unrecognized codes return 404 or an empty list depending on provisioning.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

currency
string

ISO currency code to filter the balance (e.g., KES, UGX, USD).

Example:

"KES"

Response

Balances fetched successfully

code
integer
required
Example:

200

status
string
required
Example:

"SUCCESS"

description
string
required
Example:

"Request processed successfully"

results
object[]
required