Understand balances

Balances show the latest completed snapshot of your funds. Use them to answer “how much is available now?” and “what still needs reconciliation?” without replaying every transaction yourself.

Use MCP to inspect balances

An authenticated AI agent can fetch the current balance snapshot and list recent balance transactions so finance or support users can investigate cashflow without writing API calls.

MCP tools: get_balances or list_balance_transactions

Use Retrieve your balance for the exact response. Use this guide to interpret the result.

Snapshot model

A balance is a point-in-time read model, grouped by currency.

Field	Meaning
`available.amount`	Amount classified as available at the snapshot cutoff. This is the main input for payout decisions.
`pending.amount`	Amount recognized but not yet available for payout.
`reserved.amount`	Amount held back from payout at the snapshot cutoff.
`refund.amount`	Amount assigned to refund activity at the snapshot cutoff.
`includes_transactions_before`	Cutoff timestamp for the snapshot. Later transactions are not represented.

Amounts are integers in the currency’s smallest unit, such as pesewas for GHS.

Freshness

The balance response is not a live ledger scan. It returns the latest completed snapshot, and the cutoff tells you exactly how fresh that snapshot is.

If includes_transactions_before is 2026-08-31T10:00:00Z, then:

transactions before that time are included in the snapshot;
transactions after that time are not included yet; and
balance transactions remain the right source when you need line-level evidence.

For a newly active application, the response can be zero-valued until enough balance activity has been recorded and snapshotted.

Reading the buckets

Use the buckets as a classification of funds at the cutoff, not as a complete explanation of every underlying event.

Bucket	How to read it
`available`	Funds currently classified as payout-ready. A payout can still require a valid destination, limits, and no conflicting open payout.
`pending`	Funds recognized by Inttegro but not yet payout-ready, usually because they are still aging.
`reserved`	Funds held back from payout. If this is unexpectedly high, compare balance transactions and contact support with concrete IDs.
`refund`	Funds assigned to refund activity. Use refund and balance-transaction records to explain the underlying movement.

Do not use a balance bucket alone to prove why money moved. Use Balance Transactions when you need the audit trail.

Refunds and payout availability

Refunds can change how much balance is available for payout. When a refund is accepted, Inttegro reserves the needed merchant funds and refundable line-item capacity so the same money cannot be paid out and refunded at the same time.

Depending on the refund lifecycle and snapshot timing, you may see the effect as lower available balance, refund activity, reserved funds, or balance transactions tied to the refund. A canceled pending refund can release its hold; a successful refund consumes the funds; and a failed refund should be checked against the current refund record before assuming what happened to capacity.

Available balance is an aggregate snapshot, not a promise that the same amount can be selected immediately. Payouts make a current, transaction-level decision, and the remainder of a payment involved in an unresolved refund can wait for that refund's outcome.

If a payout amount is lower than expected, compare the balance snapshot with recent refunds, balance transactions, and open payouts for the same currency. See How payouts use your balance for the complete selection model.

Balance vs balance transactions

Need	Use
Show a dashboard total	Balance snapshot
Decide whether a payout is possible	Balance snapshot plus payout settings
Explain why the total changed	Balance transactions
Reconcile a payout	Payout record plus balance transactions
Investigate a customer payment or refund	Order, refund, and balance transaction records

Payout planning

Before scheduling a payout, check:

available.amount for the relevant currency.
Payout settings for automatic mode and destination routing.
Recent balance transactions for entries that are still aging or already claimed.
Existing open payouts for the destination.

The final payout amount can still be lower than available balance if limits apply, another payout claims funds first, or funds become unavailable before execution.

Troubleshooting

Symptom	Check first
Balance looks stale	Compare `includes_transactions_before` with the activity you expect to see.
Available amount is lower than expected	Check pending funds, payout claims, refunds, holds, and recent payouts.
Pending amount is high	Confirm whether recent balance transactions have reached their `available_at` time.
A payout did not include all available funds	Check `max_amount`, configured limits, eligible transactions, and open payout claims.
You need transaction-level proof	Page through balance transactions instead of relying on aggregate buckets.

Balances API reference - Exact balance response contract.
Balance transactions - Line-level money movement records.
How payouts use your balance - Payout eligibility, selection, refund interactions, and reconciliation.
Payout settings - Automatic mode, destinations, and aging rules.