Skip to main content

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 with failureCode: user_signature_declined. In sandbox you trigger this state by calling POST /v2/sandbox/payouts/:id/simulate/cosign with outcome: "declined".

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

This is a terminal state. The payout cannot be recovered; a new payout must be submitted if the user wants to proceed.
1. Confirm the terminal state Read the payout to confirm it is terminal:
2. Determine whether to resubmit If the decline was accidental or the user wants to try again, confirm the destination and amount with them first, then submit a new payout:
Use a fresh 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.failed with this code — branch on failureCode === 'user_signature_declined' to surface a clear “you declined this transfer” message rather than a generic error
The transaction.failed event fires when the payout terminates: