Skip to main content
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:
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

Buy failure reasons

Sell stages

Sell failure reasons

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.