# Introduction to order and payment lifecycle in Merchant API Welcome to our comprehensive guide on understanding the order and payment state flow within the Merchant API! ## The role of order and payment objects The Merchant API mainly operates with `orders`, which are the primary objects necessary for accepting payments. An order represents a customer's intent to purchase goods and is the starting point for any transaction. Within each order, there can be multiple `payment` objects, representing different payment attempts associated with a single order. Once a successful payment is completed, no further payment attempts are allowed on that order. Each order and payment object within the API has its own lifecycle, marked by specific status changes. These changes reflect the progression of an order or payment from creation to completion. The following diagrams show the process and correlations of `order` and `payment` object state changes. ## Order object lifecycle - ![Successful order] ![Successful order state flow](/img/accept-payments/other-resources/order-state-flow-successful.png 'Successful order state flow') | Initial state | Result state | Description | | ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | - | `pending` | Order is created via the Merchant API.

For more information, see: [Merchant API: Create an order](/docs/api/merchant#create-order). | | `pending` | `processing` | A payment session begins when a customer is ready to finalise their purchase and presses the **Pay** button on the payment page or widget. A new payment object is created with `pending` state and linked to the order.

Order stays in `processing` state, until the current payment flow reaches a final state. | | `processing` | `authorised` | Payment passed the authentication and authorisation stage and transitions to `authorised` state.

For more information about authentication and authorisation, see: [Payment object lifecycle](#payment-object-lifecycle). | | `processing` | `pending` | If the payment fails at any point during the order's `processing` state, the order status reverts to `pending`.

A new payment session will need to be initiated, creating a new payment object linked to the order. | | `authorised` | `pending` | If the payment fails while the order is in `authorised` state and no partial capture has occurred (for example, when a `capture_deadline` expires without the payment being captured), the order resets to `pending` state.

New payment attempts can be made on the same order without having to recreate it. | | `authorised` | `completed` | The payment transitions to `captured`, indicating that the order is complete. | - ![Unsuccessful order] ![Unsuccessful order state flow](/img/accept-payments/other-resources/order-state-flow-unsuccessful.png 'Unsuccessful order state flow') | Initial state | Result state | Description | | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | - | `pending` | Order is created via the Merchant API.

For more information, see: [Merchant API: Create an order](/docs/api/merchant#create-order). | | `pending` | `failed` | Processing the order fails if the order expires and no completed payment exists. | | `pending` | `cancelled` | Order is cancelled via the Merchant API, no further payment attempts can be initiated on a cancelled order.

If you want to reinitiate a payment, a new order has to be created.

For more information, see: [Merchant API: Cancel an order](/docs/api/merchant#cancel-order). | | `pending` | `processing` | A payment session begins when a customer is ready to finalise their purchase and presses the **Pay** button on the payment page or widget. A new payment object is created with `pending` state and linked to the order.

Order stays in `processing` state, until the current payment flow reaches a final state. | | `processing` | `pending` | If the payment fails at any point during the order's `processing` state, the order status reverts to `pending`.

A new payment session will need to be initiated, creating a new payment object linked to the order. | | `processing` | `authorised` | Payment passed the authentication and authorisation stage and transitions to `authorised` state.

For more information about authentication and authorisation, see: [Payment object lifecycle](#payment-object-lifecycle). | | `authorised` | `cancelled` | Order is either [cancelled via the Merchant API](/docs/api/merchant#cancel-order), or the `cancel_authorised_after` timeout expires. By default, uncaptured orders stay in `authorised` state for 7 days before being automatically cancelled, but this can be configured.

No further payment attempts can be initiated on a cancelled order. If you want to reinitiate a payment, a new order has to be created. | | `authorised` | `pending` | If the payment fails while the order is in `authorised` state and no partial capture has occurred (for example, when a `capture_deadline` expires without the payment being captured), the order resets to `pending` state.

New payment attempts can be made on the same order without having to recreate it. | ## Payment object lifecycle - ![Successful payment] ![Successful payment state flow](/img/accept-payments/other-resources/payment-state-flow-successful.png 'Successful payment state flow') | Initial state | Result state | Description | | -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | - | `pending` | A payment session begins when a customer is ready to finalise their purchase and presses the **Pay** button on the payment page or widget. A new payment object is created and linked to the order, when an order transitions to `processing` state. | | `pending` | `authorised` | Payment bypasses the authentication challenge due to meeting exemption criteria, directly transitioning to `authorised` state.

Order transitions to `authorised` state.

Intermediate states
  1. `authorisation_started`
  2. `authorisation_passed`
| | `pending` | `authentication_challenge` | If required, the payment enters an authentication challenge state. Depending on the challenge type, the customer may need to complete a verification step, or Revolut may perform the authentication silently in the background.

For more information, see: [3D Secure](/docs/guides/merchant/reference/3d-secure). | | `authentication_challenge` | `authorised` | Upon successful authentication, the payment transitions to `authorised` state.

Order transitions to `authorised` state.

Intermediate states
  1. `authentication_verified`
  2. `authorisation_started`
  3. `authorisation_passed`
| | `authorised` | `captured` | The payment amount is successfully captured.

Order transitions to `completed` state.

Intermediate states
  1. `capture_started`
| | `captured` | `completed` | Captured funds are settled on the merchant's account, marking the payment as `completed`. | - ![Unsuccessful payment] ![Unsuccessful payment state flow](/img/accept-payments/other-resources/payment-state-flow-unsuccessful.png 'Unsuccessful payment state flow') | Initial state | Result state | Description | | -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | - | `pending` | A payment session begins when a customer is ready to finalise their purchase and presses the **Pay** button on the payment page or widget. A new payment object is created and linked to the order, when an order transitions to `processing` state. | | `pending` | `authorised` | Payment bypasses the authentication challenge due to meeting exemption criteria, directly transitioning to `authorised` state.

Order transitions to `authorised` state.

Intermediate states
  1. `authorisation_started`
  2. `authorisation_passed`
| | `pending` | `authentication_challenge` | If required, the payment enters an authentication challenge state. Depending on the challenge type, the customer may need to complete a verification step, or Revolut may perform the authentication silently in the background.

For more information, see: [3D Secure](/docs/guides/merchant/reference/3d-secure). | | `authentication_challenge` | `authorised` | Upon successful authentication, the payment transitions to `authorised` state.

Order transitions to `authorised` state.

Intermediate states
  1. `authentication_verified`
  2. `authorisation_started`
  3. `authorisation_passed`
| | `authentication_challenge` | `failed` | If issues arise during or post-authentication preventing the payment from being authorised (e.g., using the wrong OTP during the challenge), the state transitions to `failed` or `declined`, depending on the payment processor's response. For more information, see: [Decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons).

Order transitions to `pending` state. A new payment session will need to be initiated, creating a new payment object linked to the order.

Intermediate states
  1. `failing`
| | `authentication_challenge` | `declined` | If issues arise during or post-authentication preventing the payment from being authorised (e.g., using the wrong OTP during the challenge), the state transitions to `failed` or `declined`, depending on the payment processor's response. For more information, see: [Decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons).

Order transitions to `pending` state. A new payment session will need to be initiated, creating a new payment object linked to the order.

Intermediate states
  1. `authentication_verified`
  2. `authorisation_started`
  3. `declining`
| | `authorised` | `cancelled` | An authorised order can be cancelled before manually capturing via the [Merchant API: Cancel an order endpoint](/docs/api/merchant#cancel-order), which then cancels the corresponding payment. By default, uncaptured orders stay in `authorised` state for 7 days before being automatically cancelled, but this can be configured via the `cancel_authorised_after` parameter.

Order transitions to `cancelled` state. No further payment attempts can be initiated on a cancelled order. If you want to reinitiate a payment, a new order has to be created.

Intermediate states
  1. `cancellation_started`
  2. `cancelling`
| | `pending` | `declined` | Payment is declined if it fails pre-authorisation checks. For more information, see: [Decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons).

Order transitions to `pending` state. A new payment session will need to be initiated, creating a new payment object linked to the order.

Intermediate states
  1. `declining`
|
:::warning **Intermediate states** are quick steps in the payment process. They are crucial for internal validations but often too rapid to be detected in status polls. Actions or decisions should be based on the states described under **Result states**, merchants should not base any conditional logic on intermediate states. :::