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.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_urlwithreason=timeoutappended. - The TTL elapses while a payment is in flight (session
processing). The session still moves toexpired, withdecline_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 reachesexpires_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:PENDINGorREVERSAL_PENDING: not settled yet — poll again in 60 seconds. If it still isn’t final 60 minutes afterexpires_at, stop and contact Support with yourorder_reference.INCONSISTENT: the transaction is under manual review — stop polling and contact Support with yourorder_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 usinggateway_transaction_idand fulfil once it’sCAPTURED, 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, orFAILED) — 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.payment.captured (CAPTURED); otherwise start a new session as described above if the shopper still wants to pay.
Prevent it
- Set
ttl_minutesto 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).
Related
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.