diagrams
Payments

Checkout Session Flow

A hosted checkout session is an approach where the payment gateway generates a secure, short-lived session URL that the merchant redirects the customer to, rather than the merchant rendering its own payment form. This model offloads PCI compliance burden from the merchant — the gateway's UI collects and tokenizes card data in an environment the merchant never touches.

diagram.mmd — sequence
Edit in Graphlet →
Checkout Session Flow sequence diagram
About Source

A hosted checkout session is an approach where the payment gateway generates a secure, short-lived session URL that the merchant redirects the customer to, rather than the merchant rendering its own payment form. This model offloads PCI compliance burden from the merchant — the gateway's UI collects and tokenizes card data in an environment the merchant never touches.

The flow begins when the customer proceeds to payment on the merchant's website. The merchant's backend makes a server-side API call to the payment gateway to create a checkout session, passing the order details: line items, amounts, currency, success URL, and cancel URL. The gateway creates the session, assigns it a short-lived session ID and a hosted URL, and returns them to the merchant backend.

The merchant redirects the customer's browser to the hosted checkout URL. The customer sees the gateway's payment page — already branded with the merchant's logo if configured — and enters their card details. This form posts directly to the gateway's servers; the card number never reaches the merchant's systems.

The gateway tokenizes the card, applies fraud checks, potentially triggers 3D Secure Authentication, and processes the charge. On success, it redirects the customer to the merchant's success_url with the session ID as a query parameter. The merchant's success page calls the gateway API to retrieve the session object, confirms the payment status, and fulfills the order.

Simultaneously, the gateway fires a webhook to the merchant's server-side webhook endpoint — the webhook is the authoritative signal for order fulfillment, because customers may close their browser before the redirect completes. The merchant should never fulfill based solely on the redirect. See Payment Webhook Processing for the webhook handling pattern.

Free online editor
Edit this diagram in Graphlet
Fork, modify, and export to SVG or PNG. No sign-up required.
Open in Graphlet →

Frequently asked questions

A hosted checkout session is a short-lived, gateway-generated URL that the merchant redirects customers to for payment collection. The gateway's page handles card entry and tokenisation, meaning card data never touches the merchant's servers.
The merchant backend creates a session via a server-side API call, passing order details and redirect URLs. The customer is sent to the gateway's hosted page, completes payment, and is redirected back. The merchant confirms the result via both the redirect query parameter and an authoritative webhook event.
Use hosted checkout when you want to minimise PCI DSS scope, reduce frontend development effort, or offer a pre-built UI with support for multiple payment methods. It is especially suitable for small teams or rapid prototypes.
Common mistakes include fulfilling orders based only on the redirect URL (ignoring the webhook), not validating the session status server-side before fulfilment, setting overly long session expiry times, and failing to handle the customer closing the browser mid-redirect.
mermaid
sequenceDiagram participant Customer participant Merchant as Merchant Backend participant Gateway as Payment Gateway participant WebhookHandler as Merchant Webhook Handler Customer->>Merchant: Proceed to checkout Merchant->>Gateway: POST /checkout/sessions (items, amount, currency, URLs) Gateway-->>Merchant: Session ID + hosted checkout URL Merchant-->>Customer: Redirect to hosted checkout URL Customer->>Gateway: Enter card details on hosted page Gateway->>Gateway: Tokenize card data Gateway->>Gateway: Run fraud checks Gateway->>Gateway: Process charge (with 3DS if required) alt Payment successful Gateway->>WebhookHandler: POST checkout.session.completed event Gateway-->>Customer: Redirect to merchant success_url Customer->>Merchant: Load success page (session ID in query) Merchant->>Gateway: GET /checkout/sessions/:id — verify status Gateway-->>Merchant: Session object (payment_status: paid) Merchant->>Merchant: Fulfill order WebhookHandler->>Merchant: Idempotent fulfillment from webhook else Payment failed Gateway-->>Customer: Redirect to merchant cancel_url Customer->>Merchant: Load cancel page end
Copied to clipboard