Skip to main content
TL;DR: None of these are Checkout API errors — they’re terminal session outcomes. The redirect alone can’t tell them apart; confirm with a webhook or authenticated GET.
A checkout session can end in one of four non-completed terminal states. Each looks similar (or identical) at the redirect layer, which is why you always confirm the outcome server-side rather than branching on the return URL. See Session lifecycle for the full state model and Verify the payment result for the trust hierarchy behind this page.

Outcomes

The webhook is the sale’s first final event: payment.captured, payment.declined, payment.failed, payment.reversed, or — on a UOB Rewards payment whose points redemption failed — authorization.created (a hold, not a charge). Final events for a one-shot sale says what each one means and whether to fulfil. No event yet is normal while the transaction is still PENDING, REVERSAL_PENDING, or under manual review (INCONSISTENT).
authorized isn’t on this page because it isn’t a failure — but it isn’t a payment either. The card is held for the full amount and nothing was captured (for example, a UOB Rewards payment whose points redemption failed). The shopper returns to your success_url, and the gateway sends authorization.created, not payment.captured. Capture it through the Payments API using gateway_transaction_id, or let the hold lapse (a hold can’t be voided), and fulfil only on payment.captured — see Authorized: a hold, not a payment.
A decline and a genuine shopper abandon also both land on cancel_url with no params. See Handle abandoned checkouts — the only way to tell any of these apart is a GET on the session.

Why a decline isn’t an error

The Checkout API — like the Payments API underneath it — treats a decline as a normal, successful response: the gateway reached the issuer and got a “no.” For the acquirer response code behind a decline, how to branch on it safely, and what to tell the shopper, see Decline codes (Payments API — the single source for decline codes, since hosted checkout uses the same gateway underneath). For the full set of gateway transaction statuses (CAPTURED, FAILED, VOIDED, and so on) that a webhook or GET can report, see Payment lifecycle.

Starting a new attempt

Every outcome on this page is terminal for that session — none can be retried in place.
  • Declined or failed: create a new session to let the shopper try again. A failed session releases its order_reference, so reusing it creates a genuinely new session; a new order_reference keeps your own tracking cleaner.
  • Expired: you can reuse the same order_reference — an expired session’s key is no longer idempotency-active, so it creates a genuinely new session. If decline_reason is "expired_while_processing", first wait for the webhook (or a final transaction status) that settles the in-flight attempt — it may have gone through (payment.captured), in which case fulfil instead — see Session expired mid-payment. See Session lifecycle § Replay.
  • Cancelled: same as expired — create a new session when the shopper is ready.
Always check your own order state before creating any new session — see Prevent duplicate payments.

Next steps

API errors

Actual Checkout API error types — a decline isn’t one of these.

Decline codes

Interpret the issuer’s response code.

Verify the payment result

Confirm the outcome server-side before fulfilling.

Handle failures

Ten common failure scenarios, each with the exact signal and what to do.
Last modified on October 25, 2026