docs
IntegrateWebhooks

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 receive checkout.session.completed, or checkout.session.async_payment_succeeded for Fawry.
  • Setup finished (complete + no_payment_required): the customer saved their payment details. Nothing was charged. You receive checkout.session.completed.
  • Expired (expired): the customer didn't finish in time. You receive checkout.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.

Where to next

On this page