Skip to main content
TL;DR: A session that hits its TTL becomes expired and can’t be paid — confirm with a GET, then start a new session. If the GET also shows decline_reason: "expired_while_processing", the payment’s outcome is unknown and the charge may have gone through. The sale’s first final webhook or the transaction status is the final answer: fulfil on payment.captured (or void the sale before settlement if you can’t fulfil), and don’t fulfil on payment.declined, payment.reversed, or payment.failed — see Final events for a one-shot sale. If the session’s gateway_transaction_id is set, you can poll the transaction status every 60 seconds until it’s final; it’s often null here, so then wait for the webhook.
A checkout session only lives for its ttl_minutes (5–60, default depends on your environment — see Session lifecycle). If the shopper doesn’t finish paying before it elapses, the session moves to expired and can’t be paid.

When this happens

  • The shopper leaves the hosted page open past the TTL without completing payment.
  • The hosted page’s own countdown times out: it redirects the shopper to your raw cancel_url with reason=timeout appended.
  • The TTL elapses while a payment is in flight (session processing). The session still moves to expired, with decline_reason: "expired_while_processing" — see Session expired mid-payment.
  • The shopper closes the tab or navigates away before the TTL — see Handle abandoned checkouts for that path instead; it looks the same server-side but nothing redirects the shopper back.

What you see

reason=timeout only appears on the countdown’s own auto-redirect. Don’t rely on it as your only signal that a session expired — always confirm with a GET request, since a shopper who manually clicks back or closes the tab gets no query params at all.

What to do

1

Treat any cancel-URL return as unpaid, provisionally

A return to cancel_url — with or without reason=timeout — never carries a sig, so don’t infer anything from it beyond “the shopper didn’t complete the redirect flow.” Confirm with the next step.
2

Confirm the session's actual status

Call the authenticated session-status endpoint (using your secret key) from your server (API reference):
A status of expired means the session can’t be paid any more. Then check decline_reason:
  • null — no charge was submitted. Go to the next step.
  • "expired_while_processing" — the session expired while a payment was in flight. Follow Session expired mid-payment before the next step.
  • Any other value — more values may be added later; treat a value you don’t recognise as null.
3

Start a new session if the shopper wants to try again

Create a fresh checkout session (API reference). You can reuse the same order_reference — an expired session’s order_reference is no longer idempotency-active, so this creates a genuinely new session rather than replaying the old one.

Session expired mid-payment

A session that reaches expires_at while it’s processing — the shopper submitted a payment and the outcome hadn’t come back yet — still moves to expired, and the authenticated GET shows decline_reason: "expired_while_processing". The outcome is unknown, and the charge may have gone through — for example, the card network approved it but the reply reached the hosted page too late. The session stays expired either way; the payment.* webhook, or the transaction status, is the final answer for the charge. Only "expired_while_processing" needs settling. An expired session with decline_reason: null (or a value you don’t recognise, which you should treat as null) never submitted a charge — start a new session straight away.
1

Hold the order and don't create a retry session yet

Don’t fulfil, cancel, or retry the order until the in-flight attempt has a final outcome. A retry session before then could charge the shopper twice.
2

Wait for the payment webhook

The gateway sends one final event for the in-flight transaction’s outcome (a payment.* event, or authorization.created for a UOB Rewards hold); “still processing” isn’t announced, so no event yet is normal while it’s PENDING or REVERSAL_PENDING. When it arrives depends on how the charge ended. If the gateway finished the charge but its reply was lost or reached the hosted page after expires_at, the event is sent straight away — and an approval here is a kept charge (payment.captured), even though the session stays expired. If the gateway’s own deadline cut the charge off, it first checks it with the card network 5–10 minutes after the request, then every 5 minutes, so the event typically arrives 6–15 minutes after the payment was submitted. Match it to your order with data.references.order_reference, and keep the charge’s ID from data.transaction.id. See Webhook event types.Act on the first final event as Final events for a one-shot sale describes. In short: fulfil on payment.captured (or void the sale before it settles if you can’t fulfil); never on payment.declined, payment.failed, or payment.reversed; and on a UOB Rewards payment, authorization.created is a hold, not a charge — capture it and fulfil on payment.captured, or let the hold lapse (a hold can’t be voided).It’s one event, possibly delivered more than once — de-duplicate on the event id before you act on it. See Delivery guarantees.
3

Or poll the transaction status

Use the session’s gateway_transaction_id if it is set. If it is null, the transaction ID comes only from the payment.* webhook (data.transaction.id), so wait for the webhook. If none arrives within 60 minutes of expires_at, contact Support with your order_reference. null is the usual case for a session that expired while processing: the ID is only stored once the gateway answers the charge.With a transaction ID, poll GET /v1/transactions/{transaction_id}/status every 60 seconds — see Poll until the outcome settles:
  • PENDING or REVERSAL_PENDING: not settled yet — poll again in 60 seconds. If it still isn’t final 60 minutes after expires_at, stop and contact Support with your order_reference.
  • INCONSISTENT: the transaction is under manual review — stop polling and contact Support with your order_reference.
  • CAPTURED: final — the charge went through. Fulfil the order, or void the sale before it settles if you can’t.
  • AUTHORIZED (UOB Rewards payments only): the points redemption failed and the card is held, not charged. Capture it through the Payments API using gateway_transaction_id and fulfil once it’s CAPTURED, or let the hold lapse — a hold can’t be voided.
  • Any other documented status is final and nothing was kept (for example DECLINED, REVERSED, or FAILED) — don’t fulfil the order from this session.
  • A status you don’t recognise: treat it as not final and keep polling, within the same 60 minutes.
4

Expect more than one transaction per order

Each payment attempt for the order — on this session, or on an earlier session with the same order_reference — is its own transaction, with its own request_id and its own payment.* event. Match each event, or status result, to its attempt by the transaction ID.
5

Contact Support if nothing arrives

If no webhook arrives within 60 minutes of expires_at, contact Support with your order_reference. Don’t create a retry session until the outcome is settled. A transaction under manual review (INCONSISTENT) sends no event until an operator resolves it, during business hours; then its final event arrives.This assumes your webhook endpoint was reachable. After an endpoint outage, wait for the redelivery attempts — 8 attempts in total (the first plus 7 retries) over about 30 hours (see Retry schedule) — or poll the transaction status before you contact Support.
Once the webhook or a final status confirms the outcome, act on it: fulfil on payment.captured (CAPTURED); otherwise start a new session as described above if the shopper still wants to pay.

Prevent it

  • Set ttl_minutes to match how long your checkout page is realistically open (for example, longer for a page reachable from an abandoned-cart email link).
  • Surface your own countdown or warning in your own UI before the hosted page’s timer fires, if your integration keeps the shopper on your domain (embedded mode).

Session lifecycle

Statuses, TTL, and retry rules in full.

Redirect integration

How the cancel-return step fits into the full flow.

Handle abandoned checkouts

When the shopper never returns at all.

Handle failures

All ten failure scenarios, symptom → page.
Last modified on October 25, 2026