--- title: "Understand balances" description: "Interpret balance classifications, operational holds, and freshness timestamps." canonical: "https://studio.inttegro.com/guides/understand-balances" format: inttegro-machine-docs/v1 language: "Java" sdk_version: "v8.3.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/java/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 465 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "curated" recommended_mcp_tools: ["get_integration_guide","check_integration_readiness","get_balances"] estimated_tokens: 4140 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Interpret the latest completed per-currency balance snapshot, then use transaction and payout records for line-level or current settlement evidence. ### Five questions #### Q1. Is the available balance a live ledger total? No. [Retrieve your balance](https://studio.inttegro.com/machine/java/api/balances.md#retrieve-your-balance) returns a completed snapshot. Its transaction cutoff tells you what activity is included; newer movements need line-level reads. #### Q2. Which balance buckets should be kept separate? Available, pending, reserved, and refund amounts classify funds at the snapshot cutoff. Amounts use the currency's smallest unit; do not sum or relabel buckets as if each were a new cash inflow. #### Q3. Can available balance predict the next payout exactly? No. Payout selection is a later transaction-level decision affected by aging, ceilings, claims, and unresolved refunds. Follow [How payouts use your balance](https://studio.inttegro.com/machine/java/guides/understand-payouts.md) for the selection and reconciliation model. #### Q4. Where is evidence for a surprising balance movement? Page [Balance transactions](https://studio.inttegro.com/machine/java/api/balance-transactions.md#page-through-balance-transactions) for line-level records, and compare the relevant [refund](https://studio.inttegro.com/machine/java/api/refunds.md) or payout IDs. An aggregate bucket alone cannot prove why money moved. #### Q5. Which MCP reads are useful? An authenticated client can use [get_balances](https://studio.inttegro.com/machine/java/inttegro-mcp/tools.md#get_balances) for the current snapshot and [list_balance_transactions](https://studio.inttegro.com/machine/java/inttegro-mcp/tools.md#list_balance_transactions) for recent records. The latter is bounded; page the API for a complete history. ## Document content # 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. > Mcp Guide Callout is interactive content. Use the canonical page to view it. ## Prerequisites - An application with an API key that can call [Retrieve your balance](https://studio.inttegro.com/machine/java/api/balances.md#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](https://studio.inttegro.com/machine/java/products/balance-transactions.md) when you need line-level evidence. ## Choose the field for your question Balances are grouped by currency. For GHS, use these fields: | Question | Field | Meaning | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | How much did the latest snapshot classify as available? | [`balances(…).ghs(…).available(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | Funds 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(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | Live funds held for in-flight or unresolved payouts. | | How much is committed to refunds? | [`balances(…).ghs(…).held(…).refund(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | Live funds held for in-flight or unresolved refunds. | | How much is still aging? | [`balances(…).ghs(…).pending(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | Funds recognized by the snapshot but not yet available. | | How much is earmarked for future refunds? | [`balances(…).ghs(…).refund(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | A deliberate refund balance classification. It is not the amount held for active refunds. | | How much is reserved by balance policy? | [`balances(…).ghs(…).reserved(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | A 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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), [`balances(…).ghs(…).pending(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), [`balances(…).ghs(…).refund(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), and [`balances(…).ghs(…).reserved(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html)—are classifications from one completed transaction snapshot. If you need the total represented by that snapshot, add those four buckets. [`balances(…).ghs(…).held(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) 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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) 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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) 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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) and [`balances(…).ghs(…).held(…).refund(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) 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: | Field | Applies to | Meaning | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [`balances(…).ghs(…).held(…).asOf(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | [`balances(…).ghs(…).held(…).payout(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) and [`balances(…).ghs(…).held(…).refund(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | When Inttegro successfully completed the strongly consistent read of the hold amounts. It is not the time the last hold changed. | | [`balances(…).ghs(…).includesTransactionsBefore(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) | The four root balance buckets | The 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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) is `2026-10-04T14:25:00Z` and [`balances(…).ghs(…).held(…).asOf(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) 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: - For [`balances(…).ghs(…).held(…).payout(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), [page through payouts](https://studio.inttegro.com/machine/java/api/payouts.md#page-through-payouts) and [look up the relevant payout](https://studio.inttegro.com/machine/java/api/payouts.md#lookup-a-payout). Its balance transaction contributions show which funds were selected and whether each contribution is `reserved`, `completed`, or `released`. - For [`balances(…).ghs(…).held(…).refund(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), [list refunds](https://studio.inttegro.com/machine/java/api/refunds.md#list-refunds) and [look up the relevant refund](https://studio.inttegro.com/machine/java/api/refunds.md#lookup-a-refund). - Use [balance transactions](https://studio.inttegro.com/machine/java/api/balance-transactions.md#page-through-balance-transactions) to trace the payment credits and later movements behind the aggregate balance. 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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), then check [payout settings](https://studio.inttegro.com/machine/java/guides/understand-payout-settings.md), the destination, and existing payouts for the same currency. Do not preemptively subtract [`balances(…).ghs(…).held(…).payout(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) or [`balances(…).ghs(…).held(…).refund(…).amount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) from the snapshot value. The amount selected by [Schedule a payout](https://studio.inttegro.com/machine/java/api/payouts.md#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](https://studio.inttegro.com/machine/java/guides/understand-payouts.md) for the selection model. ## Troubleshooting | Symptom | Check first | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | A recent transaction is missing from the root buckets | Compare its creation time with [`balances(…).ghs(…).includesTransactionsBefore(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), then inspect the balance transaction directly. | | A payout held amount is higher than expected | Note [`balances(…).ghs(…).held(…).asOf(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), then inspect in-flight or unresolved payouts and their balance transaction contributions. | | A refund held amount is higher than expected | Note [`balances(…).ghs(…).held(…).asOf(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html), then inspect pending or unresolved refund records. Do not use the root [`balances(…).ghs(…).refund(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/balances/BalanceSnapshot.html) bucket as a substitute. | | Available is lower than expected | Check 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 available | Check transaction eligibility, `maxAmount(…)`, payout limits, and other operations that committed funds before selection completed. | ## Related resources - [Retrieve your balance](https://studio.inttegro.com/machine/java/api/balances.md#retrieve-your-balance) - Exact request and response contract. - [Balance transactions](https://studio.inttegro.com/machine/java/products/balance-transactions.md) - Line-level money movement and reconciliation. - [How payouts use your balance](https://studio.inttegro.com/machine/java/guides/understand-payouts.md) - Eligibility, selection, and payout composition. - [Refunds](https://studio.inttegro.com/machine/java/products/refunds.md) - Refund lifecycle and its effect on merchant funds.