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.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.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
failedsession releases itsorder_reference, so reusing it creates a genuinely new session; a neworder_referencekeeps 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. Ifdecline_reasonis"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.
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.