Payment lifecycle
Understand checkout, payment and subscription states and decide when to fulfil an order.
Checkout sessions
| Status | Meaning |
|---|---|
open | The customer can still open the hosted checkout and pay. |
complete | A payment for the session was confirmed. |
expired | The 24-hour session expired or a related renewal link was closed. |
A checkout status is not a substitute for the payment record. Use the
payment_id returned on a completed session to retrieve the payment.
Payments
| Status | Meaning | Fulfil? |
|---|---|---|
processing | The final gateway result is not known yet. | No |
succeeded | The payment was authenticated and recorded. | Yes |
failed | The attempt failed or was cancelled. | No |
partially_refunded | Some of the successful payment was returned. | Already fulfilled; apply your refund policy |
refunded | The full payment amount was returned. | Already fulfilled; apply your refund policy |
The browser's return URL carries payment_id, status and session_id as
convenient hints. Do not fulfil from those query parameters. Fulfil when you
receive a verified payment.succeeded event, or after GET /payments/:id
returns succeeded.
Deliveries can be delayed or duplicated. Make fulfilment idempotent using the
event id or payment id. If a payment stays processing, keep checking rather
than creating another charge automatically.
Subscriptions
Subscriptions use active, on_hold and cancelled. A successful renewal
creates a normal payment whose billing_reason is subscription_cycle.
See Subscriptions for the two renewal engines and
cancellation behaviour.
There is currently no public endpoint or dashboard button to initiate a
refund. Refunds performed operationally still update the payment and emit
refund.succeeded.