Track a payout

Track payout status, webhooks, and failure modes

A payout moves crypto out of the wallet on-chain and then settles fiat at the provider, so it completes asynchronously. The action’s status is the primary signal: succeeded means the fiat settled, not just that the crypto moved.

Read the current state with GET /v1/wallets/{wallet_id}/actions/{action_id}, or subscribe to wallet action webhooks:

Event	Fires when
wallet_action.payout.created	The payout is created and queued.
wallet_action.payout.succeeded	The provider settled the fiat to the bank account.
wallet_action.payout.rejected	Privy rejected the payout before broadcasting the on-chain transfer. No crypto left the wallet.
wallet_action.payout.failed	The payout failed after the on-chain transfer was broadcast. See failure modes.

Payload fields include provider, environment, source_asset, source_chain, source_amount, destination_fiat_account_id, destination_currency, and destination_payment_rail, alongside the standard wallet action fields, plus failure_reason on the terminal failure events.

Failure modes

rejected and failed call for different handling, and failed itself covers more than one situation. The question that decides the response is whether the crypto has already left the wallet, because retrying a payout sends more crypto.

The specific steps Privy runs for a payout are an implementation detail and may change. Inspect steps for diagnostics rather than assuming a fixed order, count, or set of types.

On a terminal failure, read the action’s steps and work through them:

1. Check whether any on-chain step confirmed

   Look for a step of type evm_transaction or svm_transaction with status confirmed. If none confirmed, the crypto never left the wallet.

2. If no on-chain step confirmed, resolve the cause and retry

   The failure is either pre-broadcast (rejected) or an on-chain failure such as reverted, replaced, or abandoned. Read the step’s failure_reason, confirm the balance is intact, and retry once the cause is fixed.

3. If an on-chain step confirmed, do not retry

   The crypto reached the provider and the fiat leg is what failed. Read the failed step’s failure_reason and the provider state below to determine where the funds are. Reissuing the payout would send a second transfer.

When the fiat leg fails, the provider’s state says where the funds ended up:

Provider state	What it means
returned, refunded	The provider sent the crypto back on-chain. Expect it to arrive back in the wallet.
refund_failed	Settlement failed and the refund also failed. The funds are held at the provider.
error, canceled, undeliverable	Settlement could not complete, for example because the bank rejected the transfer.

A payout whose fiat leg failed with refund_failed, error, canceled, or undeliverable needs provider support to resolve, since the crypto has already left the wallet. Reach out to Privy support rather than reissuing the payout.

rejected means no crypto was broadcast, so the wallet is untouched and the payout can be retried once the cause is fixed. Common causes are a policy denial, a missing or invalid authorization signature, an unverified entity, and a source asset or chain the provider does not support.

Next steps

Wallet action webhooks

Track payouts and other wallet actions in real time

Fiat deposits

Fund a wallet with fiat through a dedicated bank account