---
title: "How payouts use your balance"
description: "Understand how payout selection interacts with balances, refunds, limits, and reconciliation."
canonical: "https://studio.inttegro.com/guides/understand-payouts"
format: inttegro-machine-docs/v1
language: "TypeScript"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/typescript/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: 529
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_integration_guide","check_integration_readiness","get_balances"]
estimated_tokens: 4998
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Reconcile a payout from its final selected amount and source records, not by equating it with the last available-balance snapshot or ceiling.

### Five questions

#### Q1. Which amount is authoritative for the transfer?

The final payout amount from [Lookup a payout](https://studio.inttegro.com/machine/typescript/api/payouts.md#lookup-a-payout) is the settlement reference. Available balance is a snapshot, and max amount is a ceiling rather than an exact amount request.

#### Q2. Why can a payout stop below its ceiling?

Eligible payment transactions are considered oldest-first, one whole remaining contribution at a time. Selection stops when the next transaction would exceed the ceiling; it neither splits that contribution nor skips it for a newer smaller one.

#### Q3. Why may source transaction amounts exceed the payout?

The payout's source IDs identify original payment records, whose gross amounts do not shrink after a refund. Compare [balance transactions](https://studio.inttegro.com/machine/typescript/api/balance-transactions.md) and related [refunds](https://studio.inttegro.com/machine/typescript/api/refunds.md); reconcile with the payout's final amount.

#### Q4. What changes when a refund or payout is unresolved?

Refund reservations and payout claims protect the same merchant funds from concurrent use. A snapshot can lag those current eligibility decisions; check the refund, payout, and source transaction states before treating funds as selectable.

#### Q5. Which MCP reads support an investigation?

An authenticated connection can combine [get_payout](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_payout), [get_payout_settings](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_payout_settings), [get_balances](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_balances), and [list_balance_transactions](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#list_balance_transactions). Keep their IDs and cutoffs; a bounded list is not a complete ledger.

## Document content

# 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.

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

## Keep these amounts separate

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

| Amount                                                                                                             | What it tells you                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| [`balances.ghs.available.amount`](https://typescript.inttegro.dev/v12.0.0)                             | Aggregate funds classified as available at the balance snapshot cutoff.                                                        |
| [`payout.maxAmount`](https://typescript.inttegro.dev/v12.0.0)                                   | Optional ceiling authorized for one payout. It is not a requested exact amount.                                                |
| Payout [`payout.amount`](https://typescript.inttegro.dev/v12.0.0)                                | Final amount selected for that payout. Treat this as authoritative for reconciliation.                                         |
| Balance transaction [`transaction.amount`](https://typescript.inttegro.dev/v12.0.0) | 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 [`balances.ghs.available.amount`](https://typescript.inttegro.dev/v12.0.0) 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 [`transaction.availableAt`](https://typescript.inttegro.dev/v12.0.0) time;
- it still has a positive [`transaction.availableAmount`](https://typescript.inttegro.dev/v12.0.0) 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 [`transaction.availableAt`](https://typescript.inttegro.dev/v12.0.0), oldest first.
2. Read each transaction's [`transaction.availableAmount`](https://typescript.inttegro.dev/v12.0.0) after current refund and payout allocations.
3. Allocate the full available amount from each older source while the running total remains below [`maxAmount`](https://typescript.inttegro.dev/v12.0.0).
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`](https://typescript.inttegro.dev/v12.0.0) is `100`:

| Transaction | Available amount | Allocation | Running result |
| ----------- | ---------------: | ---------: | -------------: |
| Oldest      |               40 |         40 |             40 |
| Next        |               40 |         40 |             80 |
| Next        |               50 |         20 |            100 |

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`](https://typescript.inttegro.dev/v12.0.0) 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 [`payout.amount`](https://typescript.inttegro.dev/v12.0.0) 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 [`payout.balanceTransactions`](https://typescript.inttegro.dev/v12.0.0) 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 [`payout.amount`](https://typescript.inttegro.dev/v12.0.0) as the amount Inttegro selected for transfer.
2. Sum `allocated_amount` across [`payout.balanceTransactions`](https://typescript.inttegro.dev/v12.0.0) 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 [`payout.amount`](https://typescript.inttegro.dev/v12.0.0) 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](https://studio.inttegro.com/machine/typescript/api/payouts.md#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 [`payout.executeAfter`](https://typescript.inttegro.dev/v12.0.0). | Cancel only if execution has not started.                                                                                               |
| `"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.                                                                                         |
| `"failed"`      | The payout reached an unsuccessful terminal state.                                                             | Inspect [`payout.failure`](https://typescript.inttegro.dev/v12.0.0) before deciding whether to create another payout. |
| `"canceled"`    | The 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 `"succeeded"`, `"failed"`, or `"canceled"`.

## Troubleshooting

| Symptom                                                                                               | Check first                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payout is lower than [`payout.maxAmount`](https://typescript.inttegro.dev/v12.0.0) | Compare FIFO source availability with aging, currency, destination, and allocation constraints.                                                                                                                                                                                                                                             |
| Balance is positive but nothing was selected                                                          | Check whether funds are still aging, already allocated, or incompatible with the destination.                                                                                                                                                                                                                                               |
| Available balance is higher than the payout                                                           | Compare the balance cutoff with current refund and payout allocations plus transaction-level eligibility.                                                                                                                                                                                                                                   |
| Source transaction amounts exceed the payout                                                          | Sum only the nested amounts of allocations that reference this payout; the original transaction amounts remain unchanged.                                                                                                                                                                                                                   |
| No automatic payout ran                                                                               | Confirm automatic mode, currency routing, a valid destination, and eligible balance transactions.                                                                                                                                                                                                                                           |
| Payout is `"failed"` | Branch on [`payout.failure.reason`](https://typescript.inttegro.dev/v12.0.0), show [`payout.failure.detail`](https://typescript.inttegro.dev/v12.0.0) to an operator, and consult [`payout.failure.retryable`](https://typescript.inttegro.dev/v12.0.0) before creating a new payout. |
| 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`.

## Related resources

- [Payouts API reference](https://studio.inttegro.com/machine/typescript/api/payouts.md) - Schedule, cancel, look up, and configure payouts.
- [Payouts product guide](https://studio.inttegro.com/machine/typescript/products/payouts.md) - Product model, operating modes, and destinations.
- [Payout settings](https://studio.inttegro.com/machine/typescript/guides/understand-payout-settings.md) - Understand schedules, destinations, and aging.
- [Balances](https://studio.inttegro.com/machine/typescript/guides/understand-balances.md) - Understand available, pending, reserved, and refund amounts.
- [Balance transactions](https://studio.inttegro.com/machine/typescript/products/balance-transactions.md) - Read the line-level payment and refund evidence.
- [Refunds](https://studio.inttegro.com/machine/typescript/products/refunds.md) - Understand refund lifecycle and balance effects.