Stage

Each Transaction includes a stages array that breaks the buy pipeline into ordered steps. Poll GET /platform/v1/transactions/{id} or client.getTransaction() to see how each stage is progressing. When a stage’s status is failed, read failureReason for a machine-readable code you can branch on in your app.

stages reflects buy pipeline progress. The top-level transaction status (pending, completed, or failed) is what you should treat as terminal when polling. A transaction can be failed while earlier stages still show success.

Properties

Property	Type	Required	Description
`kind`	string	Yes	Which pipeline step this object represents. See Stage kinds.
`name`	string	No	Human-readable label for the stage (suitable for display).
`status`	string	Yes	Progress for this stage. See Stage status.
`failureReason`	string \| null	No	Present when `status` is `failed`. Snake_case tracker code — not a customer-facing sentence. See Stage failure reasons.

Stage kinds

Value	Description
`ordering`	Quote and order creation.
`waiting_payment`	Waiting for the customer to send a bank transfer (for example, SEPA).
`waiting_authentication`	Waiting for payment authentication (for example, 3D Secure).
`verification`	Identity or payment-method verification (KYC, card checks).
`processing`	Payment capture and internal processing after authorization.
`delivery`	Crypto delivery to the customer’s wallet.
`crypto_hold`	Funds held before release (when applicable to the payment method or route).

Not every transaction includes every kind. The array only contains stages that apply to that payment method and route.

Stage status

Value	Description
`not_started`	The stage has not started yet.
`in_progress`	The stage is in progress.
`success`	The stage completed successfully.
`failed`	The stage failed. Read `failureReason` if set.

Stage failure reasons

When status is failed, failureReason is a snake_case code (for example, payment_authorization_declined). Use it for programmatic handling — not for display copy. Show your own message or MoonPay’s frame failureReason string when the customer initiated payment through Apple Pay or Google Pay.

Do not confuse stages[].failureReason with other failure fields MoonPay exposes elsewhere (frame failureCode, Widget HTTP moonPayErrorCode, or the legacy Widget transaction failureReason sentence).

Frame failureCode (camelCase) on Apple Pay / Google Pay complete events — see the Apple Pay and Google Pay failure code tables.
HTTP moonPayErrorCode on Widget API errors — see Widget errors.
Top-level transaction failureReason on the legacy Widget transaction object (human-readable sentence), not returned on Platform GET /transactions/{id}.

A catalog of buy-stage failureReason values, the stage that surfaces each code, and retry guidance is documented on Stage failure reasons.

Bank transfers and `waiting_payment`

For SEPA bank transfers, the transaction stays pending until the customer’s deposit arrives. Check the waiting_payment stage: when its status is success, MoonPay has received the transfer. See Get a transaction for polling guidance.

Example

Failed card authorization on the processing stage:

{
  "kind": "processing",
  "name": "Processing",
  "status": "failed",
  "failureReason": "payment_authorization_declined"
}

Full transaction excerpt with stages:

{
  "id": "tr_abc123",
  "status": "failed",
  "stages": [
    {
      "kind": "ordering",
      "name": "Ordering",
      "status": "success",
      "failureReason": null
    },
    {
      "kind": "verification",
      "name": "Verification",
      "status": "success",
      "failureReason": null
    },
    {
      "kind": "processing",
      "name": "Processing",
      "status": "failed",
      "failureReason": "payment_authorization_declined"
    },
    {
      "kind": "delivery",
      "name": "Delivery",
      "status": "not_started",
      "failureReason": null
    }
  ]
}

Documentation

Sessions

Customers

Payment Methods

Assets

Quotes

Transactions

Objects & Types

Properties

Stage kinds

Stage status

Stage failure reasons

Bank transfers and `waiting_payment`

Example

​Properties

​Stage kinds

​Stage status

​Stage failure reasons

​Bank transfers and waiting_payment

​Example

Properties

Stage kinds

Stage status

Stage failure reasons

Bank transfers and `waiting_payment`

Example