Skip to main content
A checkout session moves through a small set of statuses from creation to a final outcome. Use these statuses — never gateway_response_code — to drive your own logic.

Statuses

  • pending → processing — the shopper submits payment; a second submission while the first is in flight is rejected.
  • processing → completed / failed — the charge resolves.
  • processing → authorized — the card is held for the full amount but not captured, so no money has moved (for example, when a UOB Rewards points redemption is declined). See Authorized: a hold, not a payment.
  • pending → expired — the TTL elapses before the shopper pays.
  • processing → expired — the TTL elapses while a payment is in flight. The GET shows decline_reason: "expired_while_processing": the outcome is unknown and the charge may have gone through. The payment.* webhook or the transaction status is the final answer — fulfil on payment.captured, not on a decline, reversal, or failure. See Session expired mid-payment.
  • pending → cancelled — you cancel the session while it’s still pending.
  • processing → pending — the payment service was briefly unreachable; nothing was charged, and the shopper can retry on the same session.
  • Same order_reference, same amount and currency, within the session TTL returns this same session as long as it can still be paid (pending, processing, completed, or authorized) — see Replay and retries below for the full rule, including what happens on a terminal session or a changed amount.
More statuses may be added. Treat a status you don’t recognise as not paid.

Authorized: a hold, not a payment

Hosted checkout runs a one-step sale, so a successful payment normally ends completed. Occasionally the sale ends as a hold instead: the session shows authorized, the card is held for the full amount, and nothing has been captured. Hosted checkout never captures a hold for you. The shopper still returns to your success_url (a signed redirect carries status=authorized), and in embedded mode CHECKOUT_COMPLETE carries status: "authorized". To settle it, capture the hold through the Payments API using the session’s gateway_transaction_id, or let the hold lapse: it’s released when its capture window runs out, and you receive authorization.expired. A hold can’t be voided. Fulfil only once the payment.captured webhook arrives. An authorized session can’t be cancelled, and retrying create with the same order_reference returns it rather than starting a second payment.

Expiry (TTL)

Set ttl_minutes on create (an integer from 5–60). If you omit it, the session uses your environment’s default: 15 minutes in production, 25 minutes in sandbox. Since this also bounds how long order_reference deduplicates a retry (see Replay and retries below), set ttl_minutes explicitly rather than relying on the default, especially in production. A session that reaches its TTL without a completed payment moves to expired — even while processing. Check decline_reason on the GET: null means no charge was submitted; "expired_while_processing" means the outcome is unknown and the charge may have gone through, so wait for the payment.* webhook or poll the transaction status, and fulfil only on payment.captured. Treat a decline_reason value you don’t recognise as null. No webhook announces an expiry — webhooks announce payments only — so confirm it with a GET. An expired session can’t be paid — create a new session (with a new or the same order_reference, see Replay below) if the shopper wants to try again. See Handle expired checkout sessions for the exact redirect signal and recovery steps.
Retention: a session record exists for its TTL plus a short grace buffer, then is no longer retrievable by GET. Your own order records — and the gateway’s transaction record, once a charge happens — are the durable source of truth, not the checkout session itself.

Merchant cancellation

Cancel a session from your server (for example, if the shopper abandons your cart) with your secret key, via the cancel endpoint:
Cancelling is idempotent while the session is still pending — and calling it again on an already-cancelled session is also idempotent. If the session has already moved to processing or another terminal status, or its status changes while the cancel is being applied, the cancel request returns a 409 — you can’t cancel a session that’s already been submitted for payment or already reached a final state. See Resolve checkout cancellation conflicts for the full decision table.
A shopper closing the tab or clicking their browser’s back button does not cancel the session — it stays pending until it expires. If you need it cancelled immediately, call the cancel endpoint from your own server.

Replay and retries

Sending POST /api/v1/checkout/sessions again with the same order_reference (for the same merchant, within the original session’s TTL) either returns the existing session, rejects the retry, or creates a fresh one — depending on whether the original session can still be paid, and whether the amount and currency match. The table below covers every situation you’ll actually hit: See Prevent duplicate sessions and double payments for the full walkthrough. Retrying after a decline, cancellation, or expiry is different: those sessions are terminal, so the reference is released automatically and the next create with the same order_reference starts a genuinely new session — you don’t need to mint a new order_reference for it to work, though using one keeps your own tracking cleaner. Either way, the shopper can’t retry a card on the old session itself. After an expiry, first settle a charge that was still in flight — it may have gone through — see Session expired mid-payment.

Next steps

Verify the payment result

Confirm the outcome server-side before fulfilling.

Customize checkout

Line items, shopper details, branding, and more.

Brand the payment page

Colours, fonts, logo, and light/dark mode.

Handle failures

Ten common failure scenarios and what to do for each.
Last modified on October 25, 2026