Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท Checkout and Payment Intents

Stripe Checkout: The Hosted Payment Page

Take payments with Stripe Checkout. Create a Checkout Session on the server, redirect the customer, handle success and cancel URLs, and fulfil orders safely with a runnable stand-in.

The fastest, safest way to take a card payment is to let Stripe host the whole payment page. Stripe Checkout is a prebuilt, mobile-friendly, translated payment page that supports cards, wallets such as Apple Pay and Google Pay, and many local payment methods. You never build a card form; you create a Checkout Session on your server and send the customer to the URL Stripe returns. After paying, they return to your site.

Checkout puts you at the lightest compliance tier, handles 3D Secure for you, and can collect shipping addresses, tax IDs, promo codes and more with a few parameters. For most new projects it should be the first thing you try.

The flow

sequenceDiagram
  participant B as Browser
  participant S as Your server
  participant K as Stripe Checkout
  B->>S: POST /checkout (productId, quantity)
  S->>K: Create Checkout Session
  K-->>S: session.url
  S-->>B: 303 redirect to session.url
  B->>K: Customer pays on Stripe's page
  K-->>B: Redirect to success_url
  K->>S: Webhook checkout.session.completed
  S->>S: Fulfil the order

The redirect to the success page is a convenience. The webhook is the proof you fulfil from.

Creating a session (real code, read-only)

JavaScript
// Real Stripe usage (read-only). Express-style route.
app.post("/checkout", async (req, res) => {
  const product = catalog[req.body.productId];          // server decides the price
  if (!product) return res.status(400).send("Unknown product");

  const session = await stripe.checkout.sessions.create({
    mode: "payment",
    line_items: [
      {
        price_data: {
          currency: "usd",
          unit_amount: product.cents,
          product_data: { name: product.name },
        },
        quantity: 1,
      },
    ],
    success_url: "https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
    cancel_url: "https://example.com/cart",
    client_reference_id: String(req.user.id),
    metadata: { order_id: order.id },
  });

  res.redirect(303, session.url);
});

The important parameters:

Parameter Meaning
mode payment (one-time), subscription, or setup (save a card only)
line_items What is being bought; use price (an existing Price ID) or inline price_data
success_url Where the customer returns after paying. is replaced by Stripe
cancel_url Where they go if they click back
client_reference_id Your own reference (user or cart ID) echoed back to you
metadata Up to 50 key/value pairs of your own data, copied onto the session
customer / customer_email Attach to an existing customer or prefill the email

Use a 303 redirect after the POST, so browsers follow it with a GET and a refresh does not resubmit.

Stand-in: a Checkout Session service

To see the logic, here is a local stand-in "Checkout" with the same ideas: server-side prices, a session with a URL and status, a customer paying, and a success redirect. It listens on loopback, which the runner allows. It is not Stripe.

Node.js A stand-in Checkout flow

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Success page: do not trust it alone

The customer lands on your success_url. It is tempting to mark the order paid right there. Do not: anyone can type that URL, and customers can also close the tab before they ever reach it. Use the success page to show a friendly confirmation (optionally retrieving the session to display details), and fulfil the order from the checkout.session.completed webhook, which Stripe sends even if the customer never returns.

Check payment_status === "paid" before fulfilling. For delayed methods (some bank debits), the session can complete while payment is still unpaid, and a later checkout.session.async_payment_succeeded event arrives.

Fulfilment must be idempotent

Webhooks can arrive twice. Your fulfilment code should tolerate repeats: record the session ID when you fulfil, and skip it the second time.

Node.js Idempotent fulfilment (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Customising Checkout

Without writing any UI you can add: promotion codes (allow_promotion_codes: true), shipping address collection, automatic tax (see the billing chapter), adjustable quantities, custom text and your branding from Dashboard settings, plus payment_method_types (or dynamic payment methods managed in the Dashboard) to turn local methods on without code changes.

When Checkout is not flexible enough (a fully embedded, custom-designed form), you move down a level to the PaymentIntent and the Payment Element, which the next lessons teach: PaymentIntents and Their Lifecycle.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does the customer enter their card details with Checkout?

    Checkout is a Stripe-hosted page, which keeps card data off your servers.
  2. 2. What is the best signal to fulfil an order?

    The success URL can be visited by anyone and may never be reached. The webhook is reliable.
  3. 3. What does mode: "subscription" change?

    mode chooses payment, subscription or setup behaviour.
  4. 4. Why record the session ID when fulfilling?

    Webhooks are delivered at least once, so handlers must be idempotent.

Summary

  • Checkout is a hosted payment page: create a session on the server, redirect to session.url.
  • The server sets prices; use client_reference_id and metadata to link back to your order.
  • Treat the success page as UX only; fulfil from the webhook after checking payment_status.
  • Make fulfilment idempotent.
  • Move to PaymentIntents when you need a fully custom flow.

Next: PaymentIntents and Their Lifecycle