> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

> Payment session statuses and state transitions

<Note>
  `payment_status` is deprecated in favour of `payment_outcome`. The new field supersedes the old and adds `not_started`, `reserved`, and `payment_method_verified` values. The deprecated field is still populated with `paid`, `unpaid`, or `pending` for backwards compatibility.
</Note>

#### Status

The `status` field of a payment session represents the current stage in the payment session lifecycle:

<AccordionGroup>
  <Accordion title="active">
    The session is currently in progress.

    * For `one_time` and `first_in_series`: The session remains in an **active** state while the customer is interacting with the Checkout page via the `session_url`. In the event of a failed payment, the session remains in an **active** state to allow a customer to make another payment attempt. In the event of a successful payment, the session transitions into a **completed** state.
    * For `next_in_series`: The session is briefly in an **active** state while the payment is being processed without customer interaction using a saved payment method. In the event of both successful and failed payments, the session transitions into a **completed** state.

    The payment outcome (`payment_outcome`) reflects the state of the payment: **not\_started** before any attempt has been made, **pending** while an attempt is in flight, and one of the terminal values **paid**, **unpaid**, **reserved**, or **payment\_method\_verified** once the attempt resolves. If the outcome is **paid** or **reserved**, the `payment_id` field represents the associated payment.

    A **pending** outcome means the payment is still being processed and will transition to a terminal value based on the payment result.
  </Accordion>

  <Accordion title="completed">
    The session has completed.

    * For `one_time` and `first_in_series`: The session has completed with the customer having completed the payment flow. This typically implies the payment was successful, but should be verified by interrogating the payment outcome (`payment_outcome`) as described below.
    * For `next_in_series`: The session has completed without customer interaction using a saved payment method, but the payment may have either succeeded or failed. The outcome should be verified by interrogating the payment outcome field (`payment_outcome`) as described below.

    The payment outcome (`payment_outcome`) reflects the result of the payment: **paid**, **unpaid**, **reserved** (for manual-capture flows), or **payment\_method\_verified** (for `amount: 0` verification flows). If the outcome is **paid** or **reserved**, the `payment_id` field represents the associated payment.
  </Accordion>

  <Accordion title="expired">
    The session expired due to inactivity or a timeout.

    * For `one_time` and `first_in_series`: The customer did not complete the checkout process in time.
    * For `next_in_series`: Not applicable.
  </Accordion>

  <Accordion title="cancelled">
    The session was explicitly cancelled by the customer or merchant.

    * For `one_time` and `first_in_series`: The customer or merchant chose to cancel the payment.
    * For `next_in_series`: Not applicable
  </Accordion>
</AccordionGroup>

The transitions below ensure that the payment session lifecycle is fully traceable and supports retries where appropriate:

<AccordionGroup>
  <Accordion title="One Time and First In Series Payment Sessions">
    ```mermaid theme={"system"}
    stateDiagram-v2
      [*] --> active : Session Created
      active --> completed : Payment succeeded
      active --> active : Payment failed
      active --> expired : Timeout or inactivity
      active --> cancelled : Explicit cancellation
      completed --> [*]
      expired --> [*]
      cancelled --> [*]
    ```

    | **From State** | **To State** | **Condition**                                                     | **Description**                                                                                                                                                             |
    | -------------- | ------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `active`       | `completed`  | Payment was successful.                                           | The session completed successfully, and the payment was successful. The payment outcome (`payment_outcome`) reflects the result of the payment as **paid** or **reserved**. |
    | `active`       | `active`     | Payment failed.                                                   | The session remains in an active state after a failed payment to allow the customer to make another payment attempt.                                                        |
    | `active`       | `expired`    | The session timed out due to inactivity.                          | The session expired because the customer didn't complete the payment or the authorization timed out.                                                                        |
    | `active`       | `cancelled`  | The session was explicitly cancelled by the customer or merchant. | The session was cancelled during checkout or before the programmatic payment was processed.                                                                                 |
  </Accordion>

  <Accordion title="Next In Series Payment Sessions">
    ```mermaid theme={"system"}
    stateDiagram-v2
      [*] --> active : Session Created
      active --> completed : Payment succeeded
      active --> completed : Payment failed
      completed --> [*]
    ```

    | **From State** | **To State** | **Condition**           | **Description**                                                                                                                                             |
    | :------------- | :----------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `active`       | `completed`  | Payment was successful. | The session completed successfully, and the payment was successful. The payment outcome (`payment_outcome`) reflects the result of the payment as **paid**. |
    | `active`       | `completed`  | Payment failed.         | The session completed successfully, however the payment failed. The payment outcome (`payment_outcome`) reflects the result of the payment as **unpaid**.   |
  </Accordion>
</AccordionGroup>