How payouts use your balance

A payout does not simply withdraw the number shown as available balance. Inttegro selects eligible balance transactions for one currency and destination at execution time, then records the amount it can safely transfer. Use this guide when a payout is lower than expected or when you need to reconcile it with payments and refunds.

Use MCP for payout investigation

An authenticated AI agent can compare a payout with its balance snapshot, settings, source transactions, and related refunds while you reconcile or troubleshoot settlement.

MCP tools: list_payouts, get_payout, get_payout_settings, list_balance_transactions or get_balances

Keep these amounts separate

Several correct amounts can exist at the same time because they answer different questions.

Amount	What it tells you
`available.amount`	Aggregate funds classified as available at the balance snapshot cutoff.
`max_amount`	Optional ceiling authorized for one payout. It is not a requested exact amount.
Payout `amount`	Final amount selected for that payout. Treat this as authoritative for reconciliation.
Balance transaction `amount`	Original amount of one source payment or refund record. It is not necessarily that transaction's net contribution to a payout.

A payout can therefore be lower than both available.amount and max_amount without either value being incorrect.

When a balance transaction is eligible

Payout selection happens when the payout executes, not when an operator last viewed the balance.

A payment balance transaction can be selected only when:

it belongs to the same application;
its currency matches the destination currency;
it has reached its available_at time;
it has not already been claimed or paid out;
its payment funds are not being resolved by an unsettled refund; and
its payout configuration is compatible with the destination.

The default automatic schedule uses a 7-day aging window. The aging timestamp is exact: a transaction that becomes available on Monday at 15:00 UTC can be considered by the first payout selection after that time.

Whole-transaction FIFO selection

Inttegro evaluates eligible payment balance transactions from oldest to newest. Each transaction contributes its whole remaining payout-eligible amount. Payout selection does not split that remaining amount, and it does not skip an older transaction to fit a newer, smaller one under the ceiling.

Selection follows this sequence:

Order eligible payment balance transactions by available_at, oldest first.
Calculate each transaction's remaining payout-eligible amount after completed refunds.
Include that whole remaining amount if the new total stays at or below max_amount.
Stop when the next transaction would exceed max_amount.

For example, suppose the eligible transactions are 40, 40, and 50, in that order, and max_amount is 100:

Transaction	Candidate amount	Running result
Oldest	40	40
Next	40	80
Next	50	Stop: including it would produce 130

The final payout amount is 80. The remaining 50 stays available for a future payout.

If the oldest eligible transaction is 120 and max_amount is 100, that transaction is not split and a newer smaller transaction is not substituted. No balance transaction is selected for that payout.

This preserves a predictable settlement order and avoids leaving partly paid payout claims on individual balance transactions.

Support for exact-amount payouts is coming in a future release. Until then, use max_amount as a ceiling and build payout reconciliation around the final amount returned on the payout.

How refunds affect selection

Refunds and payouts draw from the same merchant funds, so Inttegro prevents the same capacity from being used twice.

When a refund is unresolved, the required refund amount is reserved. The remainder of a payment involved in that reservation can also wait for the refund outcome before becoming payout-eligible. This means aggregate available balance can temporarily be higher than the amount the next payout can select.

For example, consider a payment balance transaction of 50 with a pending refund of 20:

the refund reserves 20;
the remaining 30 is not selected from that transaction while the refund outcome is unresolved;
if the refund succeeds, that transaction can later contribute the stable remaining 30; and
if the refund fails or is canceled, the reservation can be released and the transaction can later contribute up to its original 50.

Ordering matters operationally. A refund reserved first is protected from a later payout. A payment transaction claimed by a payout is unavailable to a later refund reservation, so the refund must use other eligible merchant funds or can fail because merchant balance is insufficient.

Refunds do not retroactively change a payout whose final amount has already been selected.

Why source transactions may not sum to the payout

The payout's balance_transactions array identifies the source payment transactions selected for it. Those transactions retain their original amounts. A completed refund can reduce how much of a source payment remains for payout without changing that original amount.

For example:

original payment balance transaction: 50;
completed refund funded from that payment: 20;
remaining contribution to the payout: 30; and
payout balance_transactions: still includes the original payment transaction ID.

If you fetch that source transaction, its original amount is still 50. Do not assume that summing the original amounts of balance_transactions must equal the payout amount.

For reconciliation:

Treat the payout amount as the amount Inttegro selected for transfer.
Use balance_transactions to identify the source payments and orders.
Review related refund records and refund balance transactions when a source payment's gross amount is higher than its payout contribution.
Compare the payout amount with the deposit that arrived at the destination.
Store the payout ID as the primary settlement reference.

Claims, failures, and cancellation

Selection claims balance transactions before provider execution so another payout or refund cannot reuse them concurrently.

A selected transaction can expose claimed_at and payout_id before the payout succeeds.
A successful payout retains the relationship and records paid_at.
A payout that fails before completing releases its claims for future consideration.
Canceling a payout before execution also releases its claims.

Balance snapshots are point-in-time views, so a released claim may not be visible in the aggregate response until a newer snapshot is available.

Payout lifecycle

Use Lookup a payout to track a payout after it is scheduled.

Status	Meaning	What to do
`initialized`	The payout record exists but has not been scheduled yet.	Continue monitoring.
`scheduled`	The payout is waiting for `execute_after`.	Cancel only if execution has not started.
`pending`	The payout is waiting for the next processing step.	Continue monitoring.
`processing`	Inttegro is selecting and preparing eligible balance transactions.	Do not assume the final amount yet.
`executing`	Transfer execution has started with the destination provider.	Do not cancel; wait for a terminal state.
`succeeded`	Funds were transferred successfully.	Reconcile using the payout ID and final amount.
`invalid`	The payout cannot complete.	Inspect `error` and correct the cause before scheduling another payout.
`canceled`	The payout was canceled before execution.	Its released funds can be considered by a future payout.

Inttegro does not expose merchant-facing payout webhooks today. Poll the lookup endpoint when your application needs current status, and stop when the payout reaches succeeded, invalid, or canceled.

Troubleshooting

Symptom	Check first
Payout is lower than `max_amount`	Apply whole-transaction FIFO selection to the eligible source amounts.
Balance is positive but nothing was selected	Check whether the oldest transaction exceeds `max_amount`, funds are still aging, or a refund is unresolved.
Available balance is higher than the payout	Compare the balance cutoff with current refund reservations, open payout claims, and transaction-level eligibility.
Source transaction amounts exceed the payout	Look for completed refunds associated with the same payments or orders; use payout `amount` as authoritative.
No automatic payout ran	Confirm automatic mode, currency routing, a valid destination, and eligible balance transactions.
Payout is `invalid`	Inspect `error.type`, `error.message`, `error.cause`, and `error.occurred_at` when present.
Destination received nothing	Confirm the payout reached `succeeded`; destination settlement times can vary.

When investigating, compare the payout, payout settings, latest balance snapshot, source balance transactions, and related refunds for the same currency. MCP can collect those records through get_payout, get_payout_settings, get_balances, and list_balance_transactions.

Payouts API reference - Schedule, cancel, look up, and configure payouts.
Payouts product guide - Product model, operating modes, and destinations.
Payout settings - Understand schedules, destinations, and aging.
Balances - Understand available, pending, reserved, and refund amounts.
Balance transactions - Read the line-level payment and refund evidence.
Refunds - Understand refund lifecycle and balance effects.