Skip to main content
View as Markdown

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.

Use MCP for balance investigation

An authenticated AI agent can compare balance snapshots with recent balance transactions, orders, and payouts while keeping the investigation read-only.

MCP tools: get_balances, list_balance_transactions, get_order or get_payout

Use this page to understand the product model. Use the Balance Transactions API reference 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.

FieldMeaning
idBalance transaction ID. Store it as the reconciliation key for this line.
typeWhy the entry exists, currently payment or refund. It is not a debit/credit direction.
amountUnsigned amount in minor units. Use type and related IDs to understand the movement.
order_idOrder associated with the source payment or refund.
payment_idPresent when type is payment.
refund_idPresent when type is refund.
available_atWhen payment funds become eligible for payout. Omitted when it does not apply.
available_amountPayment amount still available for a refund or payout.
pending_amountPayment amount reserved by unresolved refund or payout allocations.
spent_amountPayment amount permanently consumed by completed allocations.
allocationsEvery current pending or completed refund and payout allocation. Released allocations are omitted.
claimed_at, payout_id, paid_atDeprecated 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 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 for the refund-specific operating model.

Balance transactions vs balances

Use both views together.

NeedUse
Show current totalsBalances
Explain why totals changedBalance transactions
Decide whether payout is possibleBalance snapshot, payout settings, and recent balance transactions
Reconcile a payoutPayout record and matching nested payout allocations on its source balance transactions
Investigate a refundRefund record and refund-linked balance transactions
Support a customer questionOrder, 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.