Payout statuses

The statuses, substatuses and failure reasons a payout moves through.

Statuses

StatusFinalMeaning
requires_actionNoWaiting for funds. fundingInstructions says what to send. See Handle requires_action.
processingNoFunds are held and the transfer is under way.
succeededYesThe recipient received amount.
failedYesNothing reached the recipient. failureReason says why. Any held amount + feeAmount returns to your balance.
expiredYesNot funded within 30 days of creation.
cancelledYesYou cancelled it while it waited for funds. Nothing was held or sent.

txHash is set on succeeded. In rare cases the transfer is relayed without a hash we can report, and txHash stays null; the payout still succeeded.

Substatuses

substatus says where a payout is within its status. It is computed on read and can change without a webhook.

StatusSubstatusMeaning
requires_actionawaiting_fundingWaiting for a deposit.
processingexecutingThe transfer is being prepared.
processingsubmitted_onchainThe transfer was sent to the chain and is confirming.
processingstalledThe transfer is taking longer than expected (over 10 minutes) or is being retried. No action needed.
succeededsettledDelivered.
failedSame as failureReasonSee Failure reasons.
expiredexpiredNot funded in time.
cancelledcancelledCancelled by you.

Failure reasons

failureReason is set on failed and expired payouts and is null otherwise. Its values are fixed, so you can branch on them.

ValueStatusMeaning
screening_rejectedfailedThe destination failed sanctions screening, at creation or at funding. Nothing was held or sent.
transfer_rejectedfailedThe transfer was refused before it was sent. Nothing moved.
transfer_failedfailedThe transfer failed on chain, or kept failing after five attempts. Nothing reached the recipient.
insufficient_balance_expiredexpiredThe payout wasn't funded within 30 days.

New values may be added. Treat an unknown value as a failure in your support flow.

On this page