Payouts reference

The statuses, substatuses, failure reasons and error codes of the Payouts API.

Statuses

A payout starts processing, or requires_action while it waits for funds, and ends succeeded, failed, expired or cancelled.

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.

Errors

Errors return { "code", "message" }, plus issues: [{ field, message }] for validation errors. Branch on code.

HTTPcodeWhat to do
400params_validation, invalid_paramsFix the request; issues names the field.
400missing_idempotency_keySend an Idempotency-Key.
400unsupported_assetUse USDC on a chain from GET /v1/payout-accounts.
401missing_api_key, invalid_api_keySend a valid, unrevoked wcpo_ key.
403payouts_disabledPayouts are off for your account. Reads keep working.
404not_foundNo payout with this ID on your account.
409idempotency_conflictThis key was used for a different payout.
409payout_not_cancellableThe payout isn't requires_action, so it can't be cancelled. Read it for its current status.
409payout_account_unavailableYour payout account isn't set up yet.
503screening_unavailableRetry with the same Idempotency-Key.
503payout_account_busyRetry with the same Idempotency-Key.
503payouts_unavailablePayouts aren't available. Don't retry.
500internal_errorRetry; for a payout, with the same Idempotency-Key.

On this page