Skip to main content
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.

​
Status

The status field of a payment session represents the current stage in the payment session lifecycle:
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.
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.
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.
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
The transitions below ensure that the payment session lifecycle is fully traceable and supports retries where appropriate: