> ## Documentation Index
> Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stage failure reasons

> The stages[].failureReason codes on buy and sell transactions, what each one means, and what to do next

Buy and sell transactions return a `stages` array. Each stage has a `status`.
When a stage has `status: "failed"`, its `failureReason` field holds a
**snake\_case** code that says why. This page lists every code that the Widget
API can return, the stage that returns it, and the recommended next step.

The same `stages` array appears in:

* [Get Buy transaction](https://dev.moonpay.com/api-reference/widget/getbuytransaction.md) and the other
  buy transaction endpoints.
* [Get Sell transaction](https://dev.moonpay.com/api-reference/widget/getselltransaction.md) and the other
  sell transaction endpoints.
* The [transaction](https://dev.moonpay.com/api-reference/widget/webhooks/transaction-updated.md) and
  [sell transaction](https://dev.moonpay.com/api-reference/widget/webhooks/sell-transaction-updated.md)
  webhooks.

> [!NOTE]
>
> Use `failureReason` to choose what to show the customer. Do not show the code
> itself. The widget shows its own message for each code, and that message can
> change without notice.

## How stages fail

* Only one stage fails. Stages after a failed stage have
  `status: "not_started"`.
* A stage can have `status: "failed"` and `failureReason: null`. This can
  happen on `stage_three_processing`. Treat it the same as `error`.
* New codes can be added. Treat any code that you do not recognize the same as
  `error`.

## Buy stages

| `stage` | What it shows |
| - | - |
| `stage_one_ordering` | The payment. Used for cards, Apple Pay, Google Pay, Revolut Pay and balance payments. |
| `stage_one_waiting_payment` | The payment. Used instead of `stage_one_ordering` for other payment methods, such as bank transfers, PayPal, Venmo, Cash App Pay and PIX. |
| `stage_one_waiting_authentication` | The payment, while MoonPay waits for the customer to complete 3D Secure. This stage does not fail. |
| `stage_two_verification` | Identity, card and risk checks. |
| `stage_three_processing` | Buying the crypto. |
| `stage_four_delivery` | Sending the crypto to the customer's wallet. |

## Buy failure reasons

| `failureReason` | Stage | What happened | Retry with the same payment method? |
| - | - | - | - |
| `payment_authorization_declined` | `stage_one_ordering`, `stage_one_waiting_payment` | The card issuer or payment provider declined the payment. | Sometimes. If it fails again, use another payment method. |
| `payment_authorization_error` | `stage_one_waiting_payment` | An error at the card issuer or payment provider stopped the payment. | Yes. If it fails again, use another payment method. |
| `card_not_supported` | `stage_one_ordering` | MoonPay does not support this card type for this purchase. | No. Use a different card or payment method. |
| `timeout_3d_secure` | `stage_one_ordering` | The customer did not complete 3D Secure in time. The customer was not charged. | Yes. Place a new order and complete 3D Secure. |
| `timeout_bank_transfer` | `stage_one_ordering`, `stage_one_waiting_payment` | MoonPay did not receive the bank transfer or PIX payment in time. | Yes. Place a new order and send the payment. |
| `instant_ach_failure` | `stage_one_waiting_payment` | The instant ACH transfer failed. For example, the account had insufficient funds or was closed. | No. Use a different bank account or payment method. |
| `paypal_payment_failed` | `stage_one_waiting_payment`, `stage_three_processing` | PayPal could not process the payment. The customer was not charged. | Sometimes. If it fails again, use another payment method. |
| `venmo_payment_failed` | `stage_one_waiting_payment` | Venmo could not process the payment. The customer was not charged. | Sometimes. If it fails again, use another payment method. |
| `cash_app_customer_blocked_merchant` | `stage_one_waiting_payment` | The customer has blocked MoonPay in their Cash App Pay settings. | Yes, after the customer unblocks MoonPay in Cash App Pay. |
| `cash_app_insufficient_funds` | `stage_one_waiting_payment` | The customer's Cash App Pay balance was too low. | Yes, after the customer adds funds. |
| `cash_app_limit_reached` | `stage_one_waiting_payment` | The customer reached a Cash App Pay limit. | Yes, with a smaller amount or later. |
| `rejected_card` | `stage_two_verification` | The card failed verification or risk checks. | No. Use a different card. |
| `timeout_card_verification` | `stage_two_verification` | The customer did not complete card verification in time. | Yes. Place a new order and complete the card verification. |
| `timeout_kyc_verification` | `stage_two_verification` | The identity check was not completed in time. | Yes. Place a new order and complete the identity check. |
| `rejected_kyc` | `stage_two_verification` | The identity check failed. | No. The customer must contact MoonPay support. |
| `daily_purchase_limit_exceeded` | `stage_two_verification` | The order is over the customer's daily purchase limit. | Yes, with a smaller amount or after the limit resets. |
| `rejected_travel_rule` | `stage_two_verification` | The order does not meet Travel Rule requirements for the destination wallet. | Yes, with a different wallet. |
| `rejected_other` | `stage_two_verification` | MoonPay rejected the order for a risk or compliance reason. MoonPay does not share the exact reason. | Unlikely. Use another payment method or contact support. |
| `cancelled` | `stage_two_verification` | MoonPay cancelled the order. | Yes. Place a new order. |
| `refund` | `stage_two_verification` | MoonPay cancelled the order and refunded the payment. | Yes. Place a new order. |
| `cancelled_by_customer` | `stage_three_processing` | The customer cancelled the order. | Yes. Place a new order. |
| `failed_testnet_withdrawal` | `stage_three_processing` | Sandbox only. The MoonPay testnet wallet could not send the crypto. | Yes, later. |
| `error` | `stage_one_ordering`, `stage_one_waiting_payment`, `stage_four_delivery` | A failure that has no more specific code. See [The `error` code](#the-error-code). | Yes. If it fails again, contact support. |

## Sell stages

| `stage` | What it shows |
| - | - |
| `sell_stage_one_verification` | Identity and risk checks. Not returned for sell orders made from a quote. |
| `sell_stage_two_waiting_for_deposit` | Waiting for the customer's crypto deposit. |
| `sell_stage_two_handle_quote` | Waiting for the customer to accept an updated quote. |
| `sell_stage_two_cancelled` | The order was cancelled. |
| `sell_stage_three_processing` | Selling the crypto. |
| `sell_stage_three_refunding_crypto` | Returning the crypto to the customer. |
| `sell_stage_four_withdrawal` | Sending the fiat payout to the customer. |

## Sell failure reasons

| `failureReason` | Stage | What happened | Next step |
| - | - | - | - |
| `timeout_kyc_verification` | `sell_stage_one_verification` | The identity check was not completed in time. | Place a new order and complete the identity check. |
| `rejected_kyc` | `sell_stage_one_verification` | The identity check failed. | The customer must contact MoonPay support. |
| `rejected_other` | `sell_stage_one_verification`, `sell_stage_three_processing`, `sell_stage_four_withdrawal` | MoonPay rejected the order for a risk or compliance reason. MoonPay does not share the exact reason. | Contact MoonPay support. |
| `rejected_travel_rule` | `sell_stage_three_processing`, `sell_stage_four_withdrawal` | The order does not meet Travel Rule requirements. | Contact MoonPay support. |
| `timeout_deposit` | `sell_stage_two_waiting_for_deposit` | MoonPay did not receive the customer's crypto deposit in time. | Place a new order and send the crypto. |
| `cancelled` | `sell_stage_one_verification`, `sell_stage_two_cancelled`, `sell_stage_two_handle_quote` | MoonPay cancelled the order. | Place a new order. |
| `cancelled_by_customer` | `sell_stage_two_cancelled` | The customer cancelled the order. | Place a new order. |
| `refund` | `sell_stage_two_cancelled`, `sell_stage_two_handle_quote`, `sell_stage_three_processing`, `sell_stage_four_withdrawal` | MoonPay returned the crypto to the customer. | Place a new order. |
| `card_payout_failed` | `sell_stage_four_withdrawal` | MoonPay could not send the payout to the customer's card. | Use a different card or payout method. |
| `error` | `sell_stage_two_waiting_for_deposit`, `sell_stage_two_handle_quote`, `sell_stage_three_processing`, `sell_stage_three_refunding_crypto`, `sell_stage_four_withdrawal` | A failure that has no more specific code. See [The `error` code](#the-error-code). | Try again. If it fails again, contact support. |

## The `error` code

`error` is a catch-all. MoonPay returns it when a failure has no more specific
code. For example:

* An internal error at MoonPay.
* A PIX or Yellow Card payment that the customer's bank declined.
* Any failure on `stage_four_delivery`.
* A sell deposit or payout that failed for a reason not listed above.

The widget shows a generic message for `error`. If you need the exact cause of
a specific transaction, contact MoonPay support with the transaction ID.

## Codes that this API does not return

The widget's transaction status screen uses some codes that the Widget API does
not return on buy or sell transactions. These include the ACH and MoonPay
balance codes (`ach_*`, `moonpay_balance_hold_rejected`) and the swap code
`swap_requote_rejected`.

## Related failure fields

| Field | Where | Documentation |
| - | - | - |
| `stages[].failureReason` | Widget API buy and sell transactions | This page |
| `moonPayErrorCode` | Widget API HTTP errors | [Errors](https://dev.moonpay.com/api-reference/widget/errors.md) |
| `stages[].failureReason` (Platform API) | Platform API transactions | [Stage failure reasons](https://dev.moonpay.com/api-reference/platform/objects-and-types/stage-failure-reasons.md) |
