Payout lifecycle

A payout transfers money from your balance to a payer’s bank account, for example a winnings withdrawal or a refund.

Overview

 create ─┬─ amount within limit ─► pending ─► in queue ─► sent to bank ─► succeeded
         │                                     (processing)  (processing)
         │                                          │             │
         │                                          └──────┬──────┘
         │                                                 ▼
         │                                              failed ─► retried or canceled
         │
         └─ amount above limit ─► in_review ─┬─ approved ─► pending ─► ...
                                             └─ not approved ─► canceled

Steps

1. You create the payout

   Your system calls POST /v1/payouts with the payer, amount and a webhook URL. The money goes to that payer’s registered bank account. See Payouts (API).

   The platform checks that your available balance covers the amount plus fees and holds that sum immediately, so your available balance drops from this moment.

2. Review of large payouts (if needed)

   If the amount is above your account’s automatic payout limit, the payout is in_review (console: In review). The provider’s team reviews it:

   • Approved: the payout goes back to pending and continues; a payout.pending webhook is sent.
   • Not approved: the payout becomes canceled, the hold is released, and a payout.canceled webhook is sent.

   The provider sets this limit; contact support to change it.

3. The platform sends the money

   The payout is queued (console: In queue) and then sent to the bank (console: Sent to bank); both are processing in the API. This normally takes a few minutes.

4. Result

   When the bank confirms, the payout is succeeded, the hold becomes a real debit, a payout.succeeded webhook is sent, and the console shows Payout completed at.

Failed payouts

If the bank rejects the transfer or it cannot be sent, the payout becomes failed (console: Error). The status message on the detail page (failureReason in the API) gives the bank’s reason.

• The amount stays on hold until the payout is retried successfully or canceled.
• The provider’s team may retry it, which puts it back in the queue.
• If you no longer want to pay, cancel it through the API; the hold is released to your available balance.

Common causes are a wrong account number or name for the payer, or a closed destination account. Check the payer’s details before creating a new payout.

Canceling a payout

Cancel with POST /v1/payouts/{id}/cancel when the payout is:

Status	Can be canceled
pending, in queue, failed	Any time
Sent to bank	If it was created more than 30 minutes ago and the bank confirms the cancellation
in_review, succeeded, canceled	No

A successful cancel releases the hold immediately. Canceling through the API does not send a webhook. The partner console has no cancel button for payouts; ask support with the UUID if you need help.

Do not create a second payout while the first is unfinished

A payer can have one unfinished payout at a time (pending_payout_exists). If the previous payout failed, cancel it before creating a new one so you do not pay twice.

Common errors when creating a payout

API code	Cause	What to do
insufficient_balance	Available balance too low	Add funds or wait for pay-ins
pending_payout_exists	The payer has an unfinished payout	Wait for it to finish, or cancel it
amount_below_minimum / amount_above_maximum	Outside your per-payment limits	Change the amount, or ask for new limits
no_payout_account_available	No payout account available at the moment	Try again later; contact support if it persists
payouts_disabled	Payouts are turned off for your account	Contact support