Payouts

A payout transfers funds from one of your wallets to one payee’s bank account, in the payee’s currency. You create payouts with POST /payouts: a single call creates between 1 and 100 payouts, groups them in a batch, prices them, reserves their total in the wallet you choose, and sends every payout whose payee is ready.

How it works

Validate. Infinity checks every item: the payee exists and can be paid in that currency, the amount meets the currency’s rules, and each payee appears once.
Price. Each payout is priced at the current rate with your account’s fee_bearer, exactly as a quote would price it.
Reserve. The total debit_amount is checked against the wallet’s available amount and reserved.
Send or hold. Payouts to active payees are handed to the payout network as pending. Payouts to payees who aren’t ready yet are created awaiting_payee and wait, with their funds reserved, until the payee is ready.

The call is atomic. If any item fails validation, or the total doesn’t fit in the wallet, the request fails and no batch, payout or reservation is created, so you never have to reconcile a partially created set.

Create payouts

curl "$BASE/payouts" \
  -H "Authorization: Bearer $INFINITY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-run-2026-10" \
  -d '{
    "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
    "name": "October invoices",
    "description": "Contractor invoices, October",
    "reference": "run-2026-10",
    "items": [
      { "payee_id": "payee_c8pnahcrxqzd3z8d", "amount": "500.00", "currency": "eur", "reference": "inv-1042" },
      { "payee_id": "payee_x3k7r9mwq2dn8hat", "amount": "1200.00", "currency": "usd", "reference": "inv-1043", "metadata": { "project": "atlas" } }
    ]
  }'

Response (abridged)

{
  "id": "batch_fcb4cuwtd6fcbmwr",
  "number": "PB-2026-21",
  "name": "October invoices",
  "description": "Contractor invoices, October",
  "status": "awaiting_payees",
  "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
  "debit_currency": "usd",
  "total_debit": "1778.35",
  "total_fee": "20.00",
  "payee_count": 2,
  "payout_summary": { "total": 2, "pending": 1, "awaiting_payee": 1, "paid": 0, "...": 0 },
  "payouts": [
    {
      "id": "payout_4kz9xq7m2w8dn3ra",
      "payee_id": "payee_c8pnahcrxqzd3z8d",
      "amount": "500.00",
      "currency": "eur",
      "debit_amount": "568.35",
      "fee": "10.00",
      "rate": "0.8955",
      "payee_amount": "500.00",
      "status": "pending",
      "hold_expires_at": null,
      "reference": "inv-1042"
    },
    {
      "id": "payout_9dq3m7xk2wr5hn8t",
      "payee_id": "payee_x3k7r9mwq2dn8hat",
      "amount": "1200.00",
      "currency": "usd",
      "debit_amount": "1210.00",
      "fee": "10.00",
      "rate": "1.0000",
      "payee_amount": "1200.00",
      "status": "awaiting_payee",
      "hold_expires_at": "2026-11-25T10:05:00Z",
      "reference": "inv-1043"
    }
  ],
  "reference": "run-2026-10",
  "metadata": {},
  "created_at": "2026-10-26T10:05:00Z"
}

Maria is active, so her payout was sent immediately. Northwind Studio hasn’t finished onboarding, so its payout is on hold until it does, and the batch reports awaiting_payees. The response is the batch, with every payout it created in payouts, in request order.

Request

Field	Required	Rules
`wallet_id`	Yes	The wallet that pays. Its `available` amount must cover `total_debit`.
`items`	Yes	1 to 100 payouts. Each payee at most once per request.
`name`	No	Up to 255 characters, shown on your dashboard. Defaults to `API batch` followed by the UTC date and time.
`description`	No	Up to 500 characters. Applied to every payout in the batch.
`reference`, `metadata`	No	Your identifier and data for the batch.

Each item:

Field	Required	Rules
`payee_id`	Yes	A payee in your account that isn’t `inactive`.
`amount`	Yes	A decimal string greater than 0 with at most 2 decimals, at or above the currency’s minimum.
`currency`	Yes	A currency with `payout_enabled: true`. An `active` payee can be paid only in their bank account’s currency; a payee on hold only in the currency of their first payout. Accounts enabled for India enter INR payouts as `usd`.
`reference`	No	Your identifier for this payout, up to 100 characters, such as an invoice number.
`metadata`	No	Up to 20 string key-value pairs for this payout.

The Idempotency-Key header is required. A retry with the same key and body returns the original batch instead of creating a second one; see Idempotency. When a request fails validation, param points at the offending field, for example items[1].amount. Pricing and balance failures that concern the request as a whole return param: null.

What you’re charged

Each payout records what it cost:

Field	Meaning
`debit_amount`, `debit_currency`	What the wallet was debited for this payout, fee included.
`fee`	Infinity’s fee, in `debit_currency`.
`fee_bearer`	`account` (you paid the fee on top) or `payee` (it was deducted from the payee’s side).
`rate`	Units of `payee_currency` per one unit of `debit_currency`. `null` until known; for INR, until settlement.
`payee_amount`, `payee_currency`	What the payee receives. An estimate until the payout is `paid`, and the settled amount after.

Quotes and pricing explains how fee_bearer changes these amounts.

Payout statuses

Status	Meaning	Your action
`awaiting_payee`	The payee isn’t ready. Funds are reserved.	None. It’s released after the payee becomes `active`.
`awaiting_funds`	The payee is ready, but the wallet’s available amount was too low at release.	Fund the wallet. It’s retried at each daily release.
`pending`	Accepted and handed to the payout network.	None.
`processing`	In transit to the payee’s bank.	None.
`paid`	Delivered to the payee’s bank.	None, unless it’s later `returned`.
`failed`	Not delivered. See `failure_code`.	Act on the failure code. The reservation is released.
`returned`	Delivered, then sent back by the payee’s bank.	Verify the payee’s details with them.
`canceled`	Canceled by you while on hold.	None. The reservation is released.
`expired`	The hold reached `hold_expires_at` before the payee was ready.	None. The reservation is released.

failed, canceled and expired are terminal. paid is final except for one transition: a bank can return a payout days after crediting it, which moves it to returned. Don’t treat a payout as irrevocably settled in your ledger until you’re comfortable with that window.

Payouts on hold

You can pay a payee before they’ve finished onboarding. The payout is created as awaiting_payee and its full debit_amount is reserved in the wallet, so the funds can’t be spent twice.

Release. Infinity releases payouts on hold once a day at 09:00 IST. A payout is released if its payee is active and has been for at least 5 minutes. Released payouts are priced again at the current rate; any difference from the reserved amount is taken from, or returned to, the wallet.
Insufficient funds at release. If the wallet’s available amount can’t cover the repriced payout, it moves to awaiting_funds and is retried at every daily release until it’s sent or expires. Funding the wallet doesn’t release it by itself.
Expiry. hold_expires_at is set at creation from your account’s hold_expiry_days. A payout still on hold at that time moves to expired and its reservation is released.
Currency. A payee’s first payout on hold fixes their currency. Later payouts to that payee must use the same currency.

Update a payout on hold

curl "$BASE/payouts/payout_9dq3m7xk2wr5hn8t" \
  -H "Authorization: Bearer $INFINITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "1350.00" }'

You can change amount, and currency while the payee has no bank account and no other payouts on hold. The payout is priced again and its reservation replaced; an increase is checked against the wallet’s available amount. description, reference and metadata can’t be changed. Infinity emits payout.updated.

Cancel a payout on hold

curl -X POST "$BASE/payouts/payout_9dq3m7xk2wr5hn8t/cancel" -H "Authorization: Bearer $INFINITY_KEY"

The payout moves to canceled and its reservation is released. Both update and cancel are allowed only in awaiting_payee and awaiting_funds; in any other status they fail with 409 payout_not_editable.

Failure codes

When a payout is failed or returned, failure_code identifies the cause and failure_message carries a fixed description of it.

`failure_code`	Cause	Recommended action
`below_minimum`	The amount is below what the destination accepts.	Send a larger amount.
`insufficient_funds`	The wallet couldn’t cover the payout when it was sent.	Fund the wallet and create a new payout.
`bank_account_missing`	The payee had no active bank account in that currency.	Add an address, then create a new payout.
`bank_details_invalid`	The payee’s bank rejected the account details.	Confirm the details with the payee and contact your Infinity team to replace the address.
`rate_changed`	The rate changed before the payout could be sent.	Create a new payout.
`returned_by_bank`	The payee’s bank returned the funds.	Confirm the account details with the payee.
`undeliverable`	The network couldn’t deliver to the payee’s bank.	Check the details or use another account.
`refunded`	The payout was refunded to your wallet.	Create a new payout if needed.
`refund_failed`	The payout failed and the refund is delayed.	None; our operations team follows up with you.
`canceled`	The payout was canceled before delivery.	Create a new payout if needed.
`processing_error`	An error on Infinity’s side.	Retry with a new payout, or contact support with the payout ID.

New failure codes may be added. Treat an unknown code as a generic failure and route it for review.

Retrieve and list payouts

curl "$BASE/payouts?status=failed&created[gte]=2026-10-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $INFINITY_KEY"

GET /payouts filters by status, payee_id, batch_id, created[gte] and created[lte], returns results newest first and pages with limit (up to 100) and starting_after. GET /payouts/{id} returns one payout as it is now.

Events

Each payout emits payout.created when it’s created, then one event per status change: payout.pending, payout.awaiting_funds, payout.processing, payout.paid, payout.failed, payout.returned, payout.canceled and payout.expired. An update emits payout.updated. Every event carries the full payout object as it was at that moment. See Webhooks.

Get started

Concepts

Build reliably