---
title: "Balance transactions"
description: "Understand the line-level money movement behind balances, refunds, and payouts."
canonical: "https://studio.inttegro.com/products/balance-transactions"
format: inttegro-machine-docs/v1
language: "PHP"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/php/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: 366
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "general"
recommended_mcp_tools: []
estimated_tokens: 2635
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Understand the line-level money movement behind balances, refunds, and payouts. This PHP representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. When should the reader use Balance transactions?

Use this product guide to understand behavior, boundaries, and lifecycle before choosing API operations.

#### Q2. What is authoritative on this page?

This page is authoritative for product behavior and lifecycle intent. Linked API references define exact operations and data shapes.

#### Q3. What page-specific constraint matters most?

Keep product behavior separate from transport details and confirm current capabilities before hard-coding market or lifecycle assumptions.

#### Q4. Can Inttegro MCP materially help with this task?

No catalog ability is sufficiently specific to recommend for this page. Use the documentation directly; consult the MCP catalog only if the task later requires governed live account context or a supported operation.

#### Q5. How should the reader verify the answer and continue?

Confirm the chosen behavior against the linked guide and API operation, then verify the resulting resource state rather than relying only on UI presentation. Continue with [Orders](https://studio.inttegro.com/machine/php/products/orders.md) and [Refunds](https://studio.inttegro.com/machine/php/products/refunds.md) when those concerns enter scope.

## Document content

# Balance transactions

Balance transactions are the line-level records behind your Inttegro balance. Use them to explain why a balance changed, which payments became payout-eligible, which refunds consumed funds, and which transactions were included in a payout.

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

Use this page to understand the product model. Use the [Balance Transactions API reference](https://studio.inttegro.com/machine/php/api/balance-transactions.md) for exact fields, pagination, lookup behavior, and examples.

## What balance transactions are for

A balance snapshot tells you the current aggregate amounts. Balance transactions explain the movement behind those amounts.

Use them when you need to answer:

- which payment created this balance movement;
- which refund reduced available funds;
- when a payment becomes eligible for payout;
- how much of a payment funded each refund or payout;
- why a payout included less than an operator expected; or
- what line-level evidence supports a finance or support investigation.

Do not treat balance transactions as a complete general ledger. They are Inttegro’s product-level money movement evidence for payments, refunds, availability, and payout reconciliation.

## The transaction model

Each balance transaction has a semantic source. Payment transactions also show how their original amount is divided among available, pending, and permanently spent capacity.

| Field | Meaning |
| --- | --- |
| `id` | Balance transaction ID. Store it as the reconciliation key for this line. |
| `type` | Why the entry exists, currently `payment` or `refund`. It is not a debit/credit direction. |
| `amount` | Unsigned amount in minor units. Use `type` and related IDs to understand the movement. |
| `order_id` | Order associated with the source payment or refund. |
| `payment_id` | Present when `type` is `payment`. |
| `refund_id` | Present when `type` is `refund`. |
| `available_at` | When payment funds become eligible for payout. Omitted when it does not apply. |
| `available_amount` | Payment amount still available for a refund or payout. |
| `pending_amount` | Payment amount reserved by unresolved refund or payout allocations. |
| `spent_amount` | Payment amount permanently consumed by completed allocations. |
| `allocations` | Every current pending or completed refund and payout allocation. Released allocations are omitted. |
| `claimed_at`, `payout_id`, `paid_at` | Deprecated whole-transaction payout fields retained only for historical records. New integrations should inspect `allocations`. |

For a payment transaction, `amount = available_amount + pending_amount + spent_amount`. Allocation-specific fields are omitted from refund transactions because they are consumers of payment capacity rather than allocation sources.

Each allocation includes a stable `bta_...` ID, `type`, public `status`, investigation timestamps, and one matching nested object:

- `type: refund` includes `refund: { id, amount }`;
- `type: payout` includes `payout: { id, amount }`;
- `status: pending` means the amount is reserved but its outcome is unresolved; and
- `status: completed` means the amount has been permanently consumed and includes `completed_at`.

Inttegro intentionally does not expose internal reservation, retry, reconciliation, group, or storage states in this response.

## Payments, availability, and payouts

Payment balance transactions usually move through availability and payout stages.

1. A successful payment creates balance activity for the order.
2. The transaction has an `available_at` timestamp when it must age before payout.
3. Before `available_at`, the funds can appear as pending in the balance snapshot.
4. After `available_at`, the funds can become payout-eligible if no other rule blocks them.
5. Refund and payout selection can reserve some or all of the available amount with pending allocations.
6. A completed consumer moves its allocation amount from `pending_amount` to `spent_amount`; a safely released consumer returns its amount to `available_amount` and is omitted from current allocations.

This is why balance transactions are essential for payout debugging. A balance can look high while transactions are still aging, already allocated to pending work, or not matched to the destination currency being paid out.

The balance transactions attached to a payout identify its source payments, but their original amounts do not necessarily add up to the payout. On each source transaction, use the nested amount of the `payout` allocation whose ID matches the payout. Treat the payout amount as authoritative and use [How payouts use your balance](https://studio.inttegro.com/machine/php/guides/understand-payouts.md#why-original-source-amounts-may-not-sum-to-the-payout) when reconciling the difference.

## Refunds and balance movement

Refund balance transactions connect returned money back to a refund and order. They help explain why available balance changed after support or operations accepted a refund.

When a refund is pending, Inttegro reserves the merchant funds and refundable line-item capacity needed for that refund. A successful refund consumes those funds and leaves refund-linked balance transaction evidence. A canceled pending refund can release the hold for future payout consideration.

See [How refunds affect balances and payouts](https://studio.inttegro.com/machine/php/products/refunds.md#how-refunds-affect-balances-and-payouts) for the refund-specific operating model.

## Balance transactions vs balances

Use both views together.

| Need | Use |
| --- | --- |
| Show current totals | [Balances](https://studio.inttegro.com/machine/php/guides/understand-balances.md) |
| Explain why totals changed | Balance transactions |
| Decide whether payout is possible | Balance snapshot, payout settings, and recent balance transactions |
| Reconcile a payout | Payout record and matching nested `payout` allocations on its source balance transactions |
| Investigate a refund | Refund record and refund-linked balance transactions |
| Support a customer question | Order, payment or refund, then related balance transactions |

The balance snapshot has a cutoff. If a transaction happened after `includes_transactions_before`, it is not represented in that snapshot yet.

## Where MCP helps

MCP is useful for read-only investigation:

- fetch current balances;
- list recent balance transactions;
- inspect returned rows' available, pending, and spent amounts plus current allocations;
- look up the related order or payout when available; and
- explain differences without estimating missing history.

MCP balance-transaction listing is bounded. Use the API reference when you need exact pagination or a specific balance transaction lookup by `bt_...` ID.

## Implementation checklist

Before relying on balance transactions in production:

- store returned `bt_...` IDs where reconciliation needs line-level evidence;
- normalize currency codes before comparing amounts;
- keep amounts in integer minor units;
- do not infer debit or credit direction from `amount.value` alone;
- treat missing optional timestamps as absent, not zero;
- compare `available_at` with payout timing before explaining eligibility;
- reconcile completed payouts through matching `payout` allocations and their nested amounts;
- use `refund_id` to explain refund impact; and
- keep balances and balance transactions together in finance/support tooling.

## Related resources

- [Balance Transactions API reference](https://studio.inttegro.com/machine/php/api/balance-transactions.md) - Exact lookup and pagination contract.
- [Understand balances](https://studio.inttegro.com/machine/php/guides/understand-balances.md) - Aggregate balance snapshots and cutoff semantics.
- [How payouts use your balance](https://studio.inttegro.com/machine/php/guides/understand-payouts.md) - How eligible transactions are selected and reconciled.
- [Refunds](https://studio.inttegro.com/machine/php/products/refunds.md) - How refunds reserve, consume, or release balance.
- [Orders](https://studio.inttegro.com/machine/php/products/orders.md) - Original commercial records that create payment and refund activity.