Stage failure reasons

When a buy transaction fails, GET /platform/v1/transactions/{id} returns stages with status: "failed" on the stage where the failure occurred. The failureReason field on that stage is a snake_case tracker code. This page lists values that can appear on buy transactions. See the Stage object for field definitions and how stages relate to the top-level transaction status.

Surface	Field / event	Format	Documentation
Platform transaction stages	`stages[].failureReason`	snake_case	This page
Apple Pay / Google Pay frames	`failureCode` on `complete`	camelCase	Apple Pay, Google Pay
Widget HTTP errors	`moonPayErrorCode`	`5_PS_*`	Widget errors

payment_authorization_declined on a stage is the REST counterpart to frame failureCode: "authorizationDeclined" — different naming, same decline class.

Catalog

Use failureReason for branching. The Retry column describes whether a customer can usually retry the same payment instrument; MoonPay does not expose this as a field on Platform transactions today.

`failureReason`	Typical stage(s)	What happened	Retry same instrument?
`payment_authorization_declined`	`processing`, `waiting_authentication`	The issuer or gateway declined the payment authorization.	Sometimes — try another card or method if decline persists.
`card_not_supported`	`verification`, `processing`	The card or payment method is not supported for this purchase.	No — use a different payment method.
`rejected_card`	`verification`	The card failed verification or risk checks.	No — use a different card.
`daily_purchase_limit_exceeded`	`ordering`, `verification`	The customer hit a daily purchase limit.	Yes — after the limit resets or with a lower amount.
`timeout_3d_secure`	`waiting_authentication`	The customer did not complete 3D Secure in time.	Yes — restart the payment flow.
`timeout_card_verification`	`verification`	Card verification timed out.	Yes — retry verification.
`timeout_kyc_verification`	`verification`	Identity verification timed out.	Yes — retry KYC in your flow.
`timeout_bank_transfer`	`waiting_payment`	The bank transfer was not received in time.	Yes — customer can send a new transfer (new transaction).
`rejected_kyc`	`verification`	Identity verification failed or was rejected.	No — customer must resolve KYC or contact support.
`rejected_other`	`verification`, `processing`	The transaction was rejected for a policy or risk reason not covered above.	Unlikely — try another method or contact support.
`cancelled`	Any in-progress stage	The customer or system cancelled before completion.	Yes — start a new transaction.
`error`	`processing`, `delivery`	An unexpected internal or partner error.	Yes — retry; escalate if it persists.

Test declined card scenarios with the tables on Test payment cards and 3D Secure test cards, then call GET /platform/v1/transactions/{id} to confirm the failureReason on the failed stage.

Documentation

Sessions

Customers

Payment Methods

Assets

Quotes

Transactions

Objects & Types

Catalog

​Related failure taxonomies

​Catalog

Related failure taxonomies

Catalog