Skip to main content

Payouts

Payouts move eligible Inttegro balance into the financial accounts you configure. They turn many customer payments, balance transactions, limits, and destination rules into settlement records your finance team can track.

Use MCP for payout operations

An authenticated AI agent can inspect balances, list balance transactions, review payout settings, and investigate payout records while operators reconcile settlement.

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

Use this page to understand the product model. Use the Payouts API reference when you need exact request attributes, response shapes, and error details.

What payouts are for

Payouts exist to answer a practical business question: when can money leave Inttegro, and where should it land?

They provide four things:

  • settlement from Inttegro balance to an external account;
  • batching, so many small payments can become one payout record;
  • a predictable operating mode for automatic or manual settlement; and
  • reconciliation evidence that links the payout back to balance transactions.

The payout record is the source of truth for status, destination, amount, timing, and included balance transactions. A bank or wallet statement is useful evidence, but reconciliation should start from the Inttegro payout ID.

The payout model

Payouts sit between balances and financial accounts.

ObjectRole
Balance transactionLine-level money movement that can become payout-eligible after aging and policy checks.
Balance snapshotCurrent aggregate view of available, pending, reserved, and refund amounts.
Financial accountBank account or wallet that can receive money when active and push-enabled.
Payout settingsAutomatic mode, schedule, aging rule, and currency-to-destination routing.
PayoutSettlement record that claims eligible balance transactions and attempts transfer to one destination.

A payout is not simply “everything currently available.” It is the amount Inttegro can safely select for one destination at execution time after applying currency, aging, limits, existing claims, and destination eligibility.

How money becomes payout-ready

  1. A customer payment succeeds and settles into your Inttegro balance.
  2. Inttegro records balance transactions for the money movement.
  3. Those transactions age according to the payout schedule policy.
  4. A payout is created automatically or scheduled manually.
  5. Inttegro selects eligible transactions for the payout destination and currency.
  6. The transfer executes with the destination provider.
  7. The payout reaches a terminal status and can be reconciled.

Eligibility is intentionally stricter than “the payment succeeded.” Funds may still be pending, reserved, already claimed by another open payout, or blocked by destination configuration.

Automatic vs manual mode

There are two separate ideas that are easy to confuse.

TermMeaningUse it when
Automatic modeInttegro creates payouts on the configured schedule when eligible funds and destinations exist.You want routine settlement without weekly operational work.
Manual modeAutomatic creation is disabled. Your team schedules payouts explicitly.You need tighter control for audits, destination tests, cashflow timing, or incident response.
Manual payoutA one-off payout scheduled with the API.You want to move eligible funds now. This can still be done while automatic mode is enabled.

The default schedule is weekly. Balance transactions still need to satisfy the aging rule before they can be selected; switching modes changes who creates the payout, not whether eligibility rules apply.

Use Disable automatic payouts to switch to manual mode. Use Enable automatic payouts to return to scheduled settlement.

Destinations and currency routing

Every payout needs a financial account destination. For automatic payouts, payout settings map each currency to the financial account that should receive that currency:

{
  "destinations": {
    "ghs": "fa_H3cNv7pQf9WbLt2mJs6yXrPq4Kz1Vd5G0aEiUo"
  }
}

That means “send eligible GHS payouts to this financial account.”

Destination checks are strict:

  • the financial account must be connected to the same Inttegro account;
  • the account currency must match the payout currency;
  • the account must be active, not disconnected, and not archived;
  • push capability must be enabled; and
  • the account type must be supported for payout destinations.

For the current Ghana payout flow, use a supported mobile money wallet or Ghana bank account. Dosh accounts can be recorded as financial accounts, but they are not payout destinations.

See Set up financial accounts for account setup and Manage payout destinations for routing.

Amounts and limits

Payout amounts use integer minor units, the same as the rest of the Inttegro API. For GHS, values are in pesewas.

When scheduling a manual payout, max_amount is an optional ceiling. If you provide it, it must be greater than zero. The final payout amount may still be lower than max_amount because Inttegro only includes transactions that are eligible for that destination and currency at execution time.

Common reasons the final amount is lower than expected:

  • some transactions have not aged long enough;
  • another open payout already claimed eligible transactions;
  • payout or currency limits apply;
  • funds became reserved for refunds, holds, or other controls;
  • the destination is missing, disconnected, or not push-enabled; or
  • the provider rejected the transfer.

Refunds are one of the common reasons this happens. A pending refund can reserve merchant funds before payout selection runs; a successful refund consumes those funds; and a canceled pending refund can release them for future payout consideration. See How refunds affect balances and payouts.

For the detailed selection order, whole-transaction behavior, and refund reconciliation examples, see How payouts use your balance.

Tracking and reconciliation

Use payout status to decide what your system should do next.

Status familyMeaningOperational response
Created or scheduledThe payout exists but transfer has not started.Monitor it; cancel only if the API reference says the current state is cancellable.
Processing or executingInttegro is selecting transactions or executing the transfer.Do not assume success yet. Continue polling.
SucceededThe transfer completed.Reconcile with the payout ID, amount, destination, and balance transactions.
Invalid or canceledThe payout will not complete.Inspect the public error or cancellation reason, fix the cause, then schedule a replacement if needed.

For reconciliation:

  1. Store every payout ID returned by the API.
  2. Look up the payout before marking settlement complete in your own system.
  3. Use returned balance transaction IDs to connect the payout back to payments, orders, refunds, and adjustments.
  4. Keep currencies separate; do not combine settlement totals across currencies.
  5. Treat destination statements as confirmation evidence, not as the only ledger.

If your application needs current payout status, poll Lookup a payout until the payout reaches a terminal state.

Where MCP helps

MCP is useful for payout review and investigation. It does not change payout settings or move money.

Good operator prompts:

  • “Show current payout settings and tell me whether GHS has a valid destination.”
  • “List recent payouts and identify the ones that are not terminal.”
  • “Look up this payout and summarize the amount, destination, status, and included balance transactions.”
  • “Compare current balances with recent payout activity and explain why available balance may be lower than expected.”

The relevant tools are linked in the MCP callout at the top of this page.

Implementation checklist

Before relying on payouts in production:

  • connect at least one supported financial account;
  • enable push capability on the account;
  • configure the payout destination for each currency you accept;
  • verify automatic or manual mode in payout settings;
  • store payout IDs and terminal statuses;
  • reconcile payouts using balance transactions, not dashboard totals alone;
  • use idempotency keys for payout-changing requests; and
  • build handling for lower-than-expected payout amounts.