Skip to main content
View as Markdown

Understand balances

A balance response answers two related questions: how Inttegro classified your funds in the latest completed transaction snapshot, and how much is currently committed to payout or refund operations. Keeping those views separate helps you plan money movement without counting the same funds twice.

Use MCP to inspect balances

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

MCP tools: get_balances or list_balance_transactions

Prerequisites

  • An application with an API key that can call Retrieve your balance.
  • An understanding that every amount is an integer in the currency's smallest unit, such as pesewas for GHS.
  • Access to balance transactions when you need line-level evidence.

Choose the field for your question

Balances are grouped by currency. For GHS, use these fields:

QuestionFieldMeaning
How much did the latest snapshot classify as available?balances.ghs.available.amountFunds classified as available at the transaction snapshot cutoff. Use this for planning, not as a guarantee that a new operation will succeed.
How much is committed to payouts?balances.ghs.held.payout.amountLive funds held for in-flight or unresolved payouts.
How much is committed to refunds?balances.ghs.held.refund.amountLive funds held for in-flight or unresolved refunds.
How much is still aging?balances.ghs.pending.amountFunds recognized by the snapshot but not yet available.
How much is earmarked for future refunds?balances.ghs.refund.amountA deliberate refund balance classification. It is not the amount held for active refunds.
How much is reserved by balance policy?balances.ghs.reserved.amountA deliberate reserve for policy, risk, or remediation. It is not an operational payout or refund hold.

Keep classifications and holds separate

The four root buckets—balances.ghs.available, balances.ghs.pending, balances.ghs.refund, and balances.ghs.reserved—are classifications from one completed transaction snapshot. If you need the total represented by that snapshot, add those four buckets.

balances.ghs.held is different. It overlays the live amounts committed to operations; it does not represent additional funds. Do not add it to the snapshot total.

Do not subtract holds from balances.ghs.available to calculate a new "current available" amount either. A completed snapshot may already reflect a hold that existed when the snapshot was taken, while a newer hold can have been created afterward. Keep the values side by side:

  • use the root buckets to describe the latest completed snapshot;
  • use balances.ghs.held to disclose current operational commitments; and
  • let a payout or refund request perform the authoritative capacity check when money is about to move.

This distinction also keeps balances.ghs.refund and balances.ghs.held.refund unambiguous. The first is an intentional earmark; the second is money committed to specific refund operations.

Read freshness correctly

The response contains two timestamps because the snapshot classifications and live holds are read differently:

FieldApplies toMeaning
balances.ghs.held.asOfbalances.ghs.held.payout and balances.ghs.held.refundWhen Inttegro successfully completed the strongly consistent read of the hold amounts. It is not the time the last hold changed.
balances.ghs.includesTransactionsBeforeThe four root balance bucketsThe transaction cutoff for the latest completed snapshot. Transactions created at or after this time are not represented in those buckets yet.

For example, if balances.ghs.includesTransactionsBefore is 2026-10-04T14:25:00Z and balances.ghs.held.asOf is 2026-10-04T14:30:00Z, the root buckets cover transactions before 14:25, while the hold amounts were read at 14:30.

Preserve both timestamps when storing a balance response. Replacing either timestamp with the time your application received the HTTP response would lose its meaning.

Explain a held amount

The balance response gives you the aggregate commitment. Use the underlying resources to explain it:

A hold remains present while its operation is in flight or unresolved. When the operation reaches a definitive outcome, the hold is either consumed or released. The payout or refund record is the source for that operation's lifecycle; the balance response is the source for the aggregate amount held when it was read.

Plan a payout

Start with balances.ghs.available.amount, then check payout settings, the destination, and existing payouts for the same currency. Do not preemptively subtract balances.ghs.held.payout.amount or balances.ghs.held.refund.amount from the snapshot value.

The amount selected by Schedule a payout can still be lower than the snapshot's available amount. Selection uses the current eligibility of individual balance transactions and accounts for concurrent commitments, the requested maximum, and payout limits. See How payouts use your balance for the selection model.

Troubleshooting

SymptomCheck first
A recent transaction is missing from the root bucketsCompare its creation time with balances.ghs.includesTransactionsBefore, then inspect the balance transaction directly.
A payout held amount is higher than expectedNote balances.ghs.held.asOf, then inspect in-flight or unresolved payouts and their balance transaction contributions.
A refund held amount is higher than expectedNote balances.ghs.held.asOf, then inspect pending or unresolved refund records. Do not use the root balances.ghs.refund bucket as a substitute.
Available is lower than expectedCheck the snapshot cutoff, pending funds, deliberate refund and reserved buckets, and recent balance transactions. Review live holds separately rather than subtracting them again.
A payout selected less than the snapshot showed as availableCheck transaction eligibility, maxAmount, payout limits, and other operations that committed funds before selection completed.