What happened
A non-custodial payout reached the user-signature step and the end user declined to approve it. No funds were moved. The payout is in a terminal failed state withfailureCode: user_signature_declined.
In sandbox you trigger this state by declining the payout on the approval page at the verificationUrl from transaction.awaiting_signature, or, for a machine signer, with POST /v2/signing-requests/:id/reject.
Common causes
- Intentional decline — the user reviewed the payout details and chose not to proceed
- Incorrect payout details — the amount, recipient, or asset shown on the signing screen did not match what the user expected
- Accidental decline — the user tapped the wrong button on the signing UI
Recovery
1. Confirm the terminal state Read the payout to confirm it is terminal:Idempotency-Key — the prior key is bound to the declined payout.
Prevention
- Show payout details before sending — display the amount, asset, and destination address on a confirmation screen before initiating the signing step
- Handle
transaction.failedwith this code — branch onfailureCode === 'user_signature_declined'to surface a clear “you declined this transfer” message rather than a generic error
Related webhooks
Thetransaction.failed event fires when the payout terminates:
Related endpoints
- GET /v2/payouts/:id — read payout state
- POST /v2/payouts — submit a new payout