Handle failures

Ten scenarios cover everything that can go wrong in a hosted-checkout integration, from creating the session through to confirming the result. Find what you’re seeing below, or browse by when it happened.

Creating the session

Symptom	Signal	Page
A retry returns the session you already had, or a race returns a conflict	`201` with the original `checkout_id`, or `409 session:idempotency_conflict`	Prevent duplicate sessions and double payments
The create call itself fails, or the shopper’s charge attempt fails mid-payment	`422 gateway:unavailable` / `502 gateway:request_failed` at create; a retry message or `CHECKOUT_ERROR` while paying	Handle payment service outages during checkout
An embedded iframe stays blank	CSP `frame-ancestors` violation; no card form ever renders	Fix embedded checkout that won’t load

While the shopper pays

Symptom	Signal	Page
The shopper’s card is declined	`cancel_url` with no query params; session status `failed`	Handle declined hosted checkout payments
The shopper closes the tab or navigates away	No redirect, no event; session stays `pending` until it expires	Handle abandoned checkouts
Your cancel call is rejected	`409 session:invalid_state`	Resolve checkout cancellation conflicts
The embedded iframe loads, but your listener never fires	No `CHECKOUT_*` message ever arrives at your page	Debug missing embedded checkout events

After checkout

Symptom	Signal	Page
The session times out before the shopper finishes	Status `expired`; `cancel_url?reason=timeout` on the countdown path	Handle expired checkout sessions
The shopper’s browser never returns to your site	No redirect at all — the payment itself still resolves server-side	Confirm payment when the redirect never arrives
`sig` is missing or fails verification on the success redirect	Missing, malformed, non-matching, or stale (`ts` > 5 min) `sig`	Reject invalid redirect signatures

Every scenario above resolves the same way: confirm the outcome with a webhook or an authenticated GET, never from a redirect or postMessage event alone. See Verify the payment result for the full decision table.

Preventing duplicate charges

Several of the scenarios above — session retries, races, and reused order_reference values — are really the same underlying risk: a shopper (or your own retry logic) ends up paying twice for one order.

Prevent duplicate payments

How order_reference deduplication works, its time limit, and how to guard your own order state against a double charge.

Next steps

API errors

The full Checkout API error reference and retry rules.

Payment outcomes

Declined, failed, expired, and cancelled — not errors.

Verify the payment result

Confirm the outcome server-side before fulfilling.

Introduction

Guides

3D Secure

Errors

Reference

Handle failures - Hosted checkout

Creating the session

While the shopper pays

After checkout

Preventing duplicate charges

Prevent duplicate payments

Next steps

API errors

Payment outcomes

Verify the payment result

​Creating the session

​While the shopper pays

​After checkout

​Preventing duplicate charges

Prevent duplicate payments

​Next steps

API errors

Payment outcomes

Verify the payment result

Creating the session

While the shopper pays

After checkout

Preventing duplicate charges

Next steps