Balances

Last updated: 2026-09-25

Use the balance API to see your current amounts and the history API to review individual changes. A balance response is a snapshot: it does not reserve funds or confirm that a payout will be accepted.

Can I use the returned amounts?

Check authorityState first. When it is MERCHANT_BALANCE_AUTHORITY_STATE_AUTHORITATIVE, the returned balance data is confirmed and can be used for a preliminary funding check.

For any other state, skip that comparison. Do not interpret the returned amounts as confirmed funds or assume that an empty response means a zero balance. Unconfirmed balance data does not itself mean that payouts are disabled. The payout endpoint decides whether a request is accepted. Handle its response, including an account-level refusal if one is returned. See Payout errors.

The Balances API explains each state. Contact support if you need confirmed balance data and it remains unavailable.

Which balance should I use?

Read GET /merchant/api/v2/balances. It returns the balances for the account and realm selected by your secret API key. Identify each balance by these three fields together:

• currencyCode: the currency;
• countryCode: the country, when one is assigned;
• scopeType: whether the balance is country-specific, global, or historically unassigned to a country.

For example, a country-specific XOF balance for CI and one for SN are separate balances. Use the one for the payout's country. A shared currency does not make the balances interchangeable.

A global balance and a historical unassigned balance can both have an empty countryCode. Use scopeType to distinguish them. Do not guess a country or combine entries because their currency matches.

What do the amounts mean?

All *Minor amounts are signed integers encoded as JSON strings. Read them without losing precision. minorUnit tells you how many decimal places to use for display: "1250" with minorUnit: 2 is 12.50; with minorUnit: 0 it is 1250. Preserve negative values if returned.

The three amounts used most often are:

• availableMinor: the available part of the balance;
• currentMinor: the total across available, pending and held amounts;
• payoutAvailableMinor: the amount to use for a preliminary payout funding comparison. It can be lower than the available balance.

The total includes amounts that are not available for payout. For example, a response can show availableMinor: "125000", combined pending amounts of "18000", and holdMinor: "2000". Its currentMinor is "145000", while payoutAvailableMinor might be only "100000".

The response field table defines every amount. Preserve the returned currency code exactly; do not infer its precision from the code's spelling.

How do I check funding before a payout?

This check is optional and advisory:

1. Read balances immediately before the payout.
2. If authorityState is not MERCHANT_BALANCE_AUTHORITY_STATE_AUTHORITATIVE, skip the amount comparison and handle the payout endpoint's response.
3. Otherwise, select the matching currency, country and scope.
4. Compare the full expected debit with payoutAvailableMinor: the payout amount plus any applicable payout fee charged to your account.
5. Submit the payout according to your integration's funding rules and handle the actual response. A passing comparison does not guarantee acceptance.
6. Reconcile the resulting payment through status reads and verified webhooks.

Example, all values in minor units:

Item	Amount
Requested payout	10000
Applicable payout fee	200
Full expected debit	10200
Returned payoutAvailableMinor	10100

The requested amount fits, but the full debit does not. The fee here is illustrative; use the fees agreed for your account. If you do not know the fee, an amount-only comparison cannot establish that the full debit is covered.

A balance read reserves nothing. Availability can change before the payout is submitted. Do not use version, payoutControlsRevision, or updatedAt as a promise that cached payout availability is still current; read it again for a new payout decision.

How do I reconcile history?

Read GET /merchant/api/v2/balances/history with the same currency, country and scope as the balance you are investigating. Check the response authorityState before relying on the returned amounts.

Use id to identify a movement, bucket to identify the balance amount it changed, and direction plus amountMinor to understand the change. Use sourceType to select the category. For payment movements, sourceId identifies the payment and sourceReference contains your payment reference. Treat description as display text, not a value for program logic.

For settlements, a debit records money paid to you and a credit records funding received from you. A settlement reversal corrects an earlier entry; it does not send another transfer. The history date is when the entry was recorded, which can differ from the external transfer date.

When present, balanceBeforeMinor and balanceAfterMinor describe that one movement. Adjacent rows do not guarantee a continuous running balance. A gap alone is not proof of a missing payment or duplicate charge. Use the latest confirmed balance for the current amount and reconcile a payment by its status.

Results are newest first. Request further pages using page.limit, offset and totalPages, and deduplicate movements by id. New movements can shift an offset-based page while you are reading history; avoid treating separately fetched pages as one frozen snapshot. See History pagination for examples.

Balance history explains changes to your funds. Payment status tells you the outcome of a particular pay-in or payout. Use both when investigating a payment; neither an instruction nor a balance movement alone is proof of customer payment completion.