Skip to main 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.

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;
  • which payout claimed or paid a transaction;
  • 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 and optional lifecycle fields.

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.
claimed_atWhen payout selection claimed the transaction.
payout_idPayout assigned to this transaction.
paid_atWhen the transaction’s payout lifecycle completed.

Optional lifecycle fields are omitted until they exist. Treat omission as “not applicable yet” rather than a zero or empty value.

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. Payout selection can claim the transaction and set claimed_at plus payout_id.
  6. When the payout completes, paid_at records that the transaction has finished its payout lifecycle.

This is why balance transactions are essential for payout debugging. A balance can look high while transactions are still aging, already claimed by another payout, reserved for another flow, 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 always add up to the payout amount after refunds. 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 balance transactions with that payout_id
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;
  • identify returned rows that reference orders, refunds, or payouts;
  • 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;
  • use payout_id and paid_at to reconcile completed payouts;
  • use refund_id to explain refund impact; and
  • keep balances and balance transactions together in finance/support tooling.