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:
From StateTo StateConditionDescription
activecompletedPayment 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.
activeactivePayment failed.The session remains in an active state after a failed payment to allow the customer to make another payment attempt.
activeexpiredThe session timed out due to inactivity.The session expired because the customer didn’t complete the payment or the authorization timed out.
activecancelledThe session was explicitly cancelled by the customer or merchant.The session was cancelled during checkout or before the programmatic payment was processed.
From StateTo StateConditionDescription
activecompletedPayment was successful.The session completed successfully, and the payment was successful. The payment outcome (payment_outcome) reflects the result of the payment as paid.
activecompletedPayment failed.The session completed successfully, however the payment failed. The payment outcome (payment_outcome) reflects the result of the payment as unpaid.