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 and the other buy transaction endpoints.
- Get Sell transaction and the other sell transaction endpoints.
- The transaction and sell transaction webhooks.
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"andfailureReason: null. This can happen onstage_three_processing. Treat it the same aserror. - 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.
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.