Checking a session's status
Let webhooks tell you when a payment changes, and read a session only when you need it.
Webhooks tell your server the moment a checkout is paid, fails or expires, so you never have to ask. Read a session with GET /checkout/sessions/:id only when you need it, for example when a customer lands on your return page.
Don't poll. Re-reading sessions on a timer adds thousands of calls that tell you nothing new, and XPay contacts merchants whose integration does it.
When a session is done
Once a session reaches one of these states, it won't change again:
- Paid (
complete+paid): fulfil the order. You receivecheckout.session.completed, orcheckout.session.async_payment_succeededfor Fawry. - Setup finished (
complete+no_payment_required): the customer saved their payment details. Nothing was charged. You receivecheckout.session.completed. - Expired (
expired): the customer didn't finish in time. You receivecheckout.session.expired. - Fawry not paid: the reference expired or was declined. You receive
checkout.session.async_payment_failed.
A Fawry session stays complete + unpaid while the customer still has time to pay. There's nothing to check in the meantime: its webhook tells you how it ends.
On your return page
Customers often reach your return page a moment before the payment is confirmed. Read the session once, from your server:
- Paid or setup finished: show your success page.
- Expired: let the customer start a new checkout.
- Anything else: show "We're confirming your payment". Your webhook updates the order.
Always read sessions from your server. The call needs your secret key, which never belongs in the browser.