Skip to main content
View as Markdown

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.

AmountWhat it tells you
balances.ghs.available.amountAggregate funds classified as available at the balance snapshot cutoff.
maxAmountOptional ceiling authorized for one payout. It is not a requested exact amount.
Payout amountFinal amount selected for that payout. Treat this as authoritative for reconciliation.
Balance transaction amountOriginal 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 balances.ghs.available.amount and maxAmount 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 availableAt time;
  • it still has a positive availableAmount after refund and payout allocations; 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.

Partial FIFO selection

Inttegro evaluates eligible payment balance transactions from oldest to newest. It fully consumes each older transaction's available amount before using a newer one. When the payout ceiling falls inside the next transaction, Inttegro allocates only the amount needed from that final source transaction.

Selection follows this sequence:

  1. Order eligible payment balance transactions by availableAt, oldest first.
  2. Read each transaction's availableAmount after current refund and payout allocations.
  3. Allocate the full available amount from each older source while the running total remains below maxAmount.
  4. If the next source would cross the ceiling, allocate only the remaining amount needed and stop.

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

TransactionAvailable amountAllocationRunning result
Oldest404040
Next404080
Next5020100

The final payout amount is 100. The final source transaction retains 30 of available amount for a future refund or payout.

If the oldest eligible transaction has 120 available and maxAmount is 100, the payout allocates 100 from that transaction and leaves 20 available. It does not skip the oldest source to assemble the same amount from newer transactions.

This preserves predictable FIFO settlement while allowing operators to choose flexible payout ceilings.

Use maxAmount 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 as a pending allocation. Only that allocated amount becomes unavailable to other work.

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

  • the refund reserves 20;
  • the transaction reports pending_amount: 20 and available_amount: 30;
  • the remaining 30 can fund a payout without reusing the refund's reserved amount;
  • if the refund succeeds, its allocation moves from pending to completed; and
  • if the refund fails or is canceled safely, the reservation is released and the available amount returns to 50, less any other allocations.

Ordering matters operationally. A refund or payout allocation reserved first is protected from later work, but only its allocated amount becomes unavailable. Later consumers can use the remaining capacity without double-spending the same funds.

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

Why original source amounts may not sum to the payout

The payout's balanceTransactions array embeds a sparse view of every source payment transaction selected for it. Each item contains the source ID, its original amount, the exact allocated_amount contributed to this payout, and a status of reserved, completed, or released.

The array is historical payout composition, not only a list of current reservations. Failed and canceled payouts retain their selected transactions with status: released after the capacity becomes available for reuse. An unresolved provider outcome keeps the contribution reserved until reconciliation establishes whether money moved.

For example:

  • original payment balance transaction: 50;
  • completed refund funded from that payment: 20;
  • payout allocation from the remaining capacity: 30; and
  • payout contribution: id identifies the payment transaction, amount is 50, allocated_amount is 30, and status explains whether that contribution remains reserved, completed, or was released.

The contribution object is enough to reconcile this payout without another lookup: sum its allocated_amount values, not its original amount values. Fetch the full source transaction only when you need its order, payment, refund, availability, or complete allocation history. Do not treat amount - allocated_amount as the source's current availability; other allocations may have consumed that difference.

For reconciliation:

  1. Treat the payout amount as the amount Inttegro selected for transfer.
  2. Sum allocated_amount across balanceTransactions and confirm it equals the payout amount.
  3. Use each contribution's id to fetch the full balance transaction only when you need source payment, order, or allocation-history details.
  4. Compare the payout amount with the deposit that arrived at the destination.
  5. Store the payout ID as the primary settlement reference.

Claims, failures, and cancellation

Selection creates pending allocations before provider execution so another payout or refund cannot reuse the same amounts concurrently.

  • A selected source exposes a payout allocation with status: pending and the exact amount reserved from that transaction.
  • A successful payout changes its allocations to status: completed and records completed_at.
  • A payout that fails definitively before money movement releases its allocations for future consideration.
  • Canceling a payout before execution also releases its allocations.
  • An unresolved provider outcome keeps allocations pending until reconciliation proves whether money moved.

Balance snapshots are point-in-time views, so a released allocation 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.

StatusMeaningWhat to do
Inttegro.PayoutStatuses.InitializedThe payout record exists but has not been scheduled yet.Continue monitoring.
Inttegro.PayoutStatuses.ScheduledThe payout is waiting for executeAfter.Cancel only if execution has not started.
Inttegro.PayoutStatuses.ProcessingInttegro is selecting and preparing eligible balance transactions.Do not assume the final amount yet.
Inttegro.PayoutStatuses.ExecutingTransfer execution has started with the destination provider.Do not cancel; wait for a terminal state.
Inttegro.PayoutStatuses.SucceededFunds were transferred successfully.Reconcile using the payout ID and final amount.
Inttegro.PayoutStatuses.FailedThe payout reached an unsuccessful terminal state.Inspect failure before deciding whether to create another payout.
Inttegro.PayoutStatuses.CanceledThe payout was canceled before execution.Its released funds can be considered by a future payout.

Poll the lookup endpoint when your application needs current status, and stop when the payout reaches Inttegro.PayoutStatuses.Succeeded, Inttegro.PayoutStatuses.Failed, or Inttegro.PayoutStatuses.Canceled.

Troubleshooting

SymptomCheck first
Payout is lower than maxAmountCompare FIFO source availability with aging, currency, destination, and allocation constraints.
Balance is positive but nothing was selectedCheck whether funds are still aging, already allocated, or incompatible with the destination.
Available balance is higher than the payoutCompare the balance cutoff with current refund and payout allocations plus transaction-level eligibility.
Source transaction amounts exceed the payoutSum only the nested amounts of allocations that reference this payout; the original transaction amounts remain unchanged.
No automatic payout ranConfirm automatic mode, currency routing, a valid destination, and eligible balance transactions.
Payout is Inttegro.PayoutStatuses.FailedBranch on failure.reason, show failure.detail to an operator, and consult failure.retryable before creating a new payout.
Destination received nothingConfirm the payout reached Inttegro.PayoutStatuses.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.