Balances

Last updated: 2026-07-17

Balance V2 exposes the current positions for the authenticated merchant and a separate movement history. Use the snapshot for payout planning and the history to explain how a position changed.

Select the correct position

GET /merchant/api/v2/balances returns all available merchant positions; it does not accept market filters. Treat a position as identified by the pair:

• currencyCode;
• countryCode when the position is market-scoped.

The same currency can therefore appear in more than one row. For example, XOF positions can be separated by country. Match both values from the payment flow instead of combining same-currency rows or falling back to a different country. If the API returns an unscoped row with an empty countryCode, keep that row separate from country-scoped positions.

Understand the snapshot

All monetary values are signed minor-unit integers encoded as JSON strings. Parse them with an integer type that preserves the full int64 range.

Field	What it answers
availableMinor	What is currently in the available bucket
pendingInMinor	How much is currently pending inbound
pendingOutMinor	How much is currently pending outbound
pendingMinor	Combined inbound and outbound pending amount
holdMinor	How much is currently held
currentMinor	Aggregate position across available, pending, and held buckets
payoutAvailableMinor	What the API currently exposes for a payout pre-check
version	Opaque version of this returned position snapshot

The returned aggregate fields follow these relationships:

pendingMinor = pendingInMinor + pendingOutMinor
currentMinor = availableMinor + pendingMinor + holdMinor

Do not derive payout eligibility from currentMinor or availableMinor. payoutAvailableMinor is the dedicated value for that decision and can be lower than the other aggregates.

Perform a payout pre-check

When your integration performs a pre-funding check:

1. Read Balance V2 immediately before creating the payout.
2. Select the row matching the payout currency and market country.
3. Compare the intended payout amount with payoutAvailableMinor.
4. Submit the payout and handle its actual response even when the comparison passed.
5. Reconcile the resulting payment order through status reads and verified webhooks.

A balance read does not reserve funds. Another transaction can change the position between the read and payout creation, so the payout response remains authoritative for request acceptance.

Reconcile changes with history

GET /merchant/api/v2/balances/history returns balance movements newest first. Start with the same currencyCode and countryCode used to select the snapshot, then add sourceType or sourceId only when you need to narrow the result to a known source.

Use the movement fields together:

• bucket identifies the changed balance bucket;
• direction identifies a credit or debit;
• amountMinor is the movement amount;
• balanceBeforeMinor and balanceAfterMinor show the recorded bucket values around the movement when available;
• operationId groups movements belonging to the same balance operation;
• sourceReference and description provide merchant-visible reconciliation context when returned.

History uses offset pagination. Keep paging until the returned page metadata shows the requested range is complete; do not assume the first page contains all movements.

Balance checks and payment status answer different questions: balances explain funds, while the latest payment status explains the business outcome of a pay-in or payout.

Use both Balance V2 operations together: the snapshot explains the current position and history explains its movements. See Balances API for complete fields, examples, filters, and pagination.