Design a checkout flow

Requirements: what to ask before drawing anything

Checkout is the shortest part of a store and the one that earns all the money. Every other page exists to bring a shopper here. A checkout that is slow, confusing, or that fails once in a hundred orders costs revenue directly, and a checkout that charges twice costs trust that no page can win back.

Most carts never become orders. Baymard Institute averages 50 published studies to a documented cart abandonment rate of about 70 percent. Much of that is window shopping, but the reasons people give besides just browsing are a checkout to-do list: extra costs too high (40 percent), not trusting the site with a card (19 percent), being made to create an account (18 percent), a checkout that is too long or complicated (17 percent), and a declined card (10 percent).

It is also a place where three groups have hard rules. The shopper wants to pay fast and see the real total. The business wants every order recorded, taxed, and paid exactly once. The card networks and regulators decide how card numbers may be handled and when a bank may ask the shopper to prove who they are.

Spend the first five minutes on questions whose answers change the design. The table lists them, the answer this guide assumes, and what each answer changes.

Functional requirements

• Start checkout from the cart as a guest or signed in. Signed-in shoppers see saved addresses and saved cards.
• Pay in one or two taps with an express wallet (Apple Pay, Google Pay, PayPal, Shop Pay style), which supplies the address and payment together.
• Enter a shipping address with suggestions as you type, in the format of the destination country, and a billing address if it differs.
• Pick a delivery option whose list and price depend on the address and the cart.
• Apply and remove discount codes and gift cards and see their effect on the total right away.
• Pay by card in fields that look like part of the page, pass a bank challenge when asked, and see a clear message when a card is declined.
• Review the order with the exact total that will be charged, place it once, and land on a confirmation page that can be refreshed or shared with the order number.
• After paying as a guest, create an account with one field: a password.

Non-functional requirements, with numbers

• Exactly one charge per order. Double clicks, retries, refreshes, and a lost response must never create a second order or a second charge. This is the requirement every other choice serves.
• The total shown is the total charged. The amount on the place-order button equals the amount the server charges, to the cent, or the shopper is asked to confirm a new amount.
• Fast on a phone. The main content of the checkout renders within 2.5 seconds on a mid-range phone on 4G (Largest Contentful Paint, LCP, at most 2.5 s at the 75th percentile), and taps respond within 200 ms (Interaction to Next Paint, INP).
• Re-pricing feels instant. A new address or code updates the total within 500 ms at the 75th percentile, with a visible pending state while it runs.
• Card data never touches our servers. Only the payment provider sees card numbers. Our code sees a token.
• Accessible. WCAG 2.2 AA: every field labelled, errors announced and linked, keyboard-only checkout possible, no surprise timeouts.
• Observable. We can see drop-off per step and the error rate of each call, without sending names, emails, or addresses to analytics.

Out of scope, and why

• The cart page itself, product pages, and recommendations: covered by the shopping cart and Amazon guides.
• Fraud scoring and the payment provider's own systems. We call them; we do not design them.
• Subscriptions and buy-now-pay-later plans. They add states but reuse the same session and payment design.
• Order tracking after the purchase. The confirmation page is the last screen we own.

What makes checkout hard

A checkout looks like a long form with a button at the end. Five traits make it much harder than a form, and each one drives a later chapter.

1. The total is a moving target. Subtotal, delivery, tax, discounts, and gift cards each depend on other inputs. Tax depends on the address. Delivery depends on the address and the weight of the cart. A discount may depend on the delivery option (free shipping codes) or exclude sale items. One change can ripple through every line, and the server, not the browser, owns the math.
2. The money part is not yours. Card numbers must stay inside the payment provider's frames. The bank may interrupt with a challenge. The final yes or no comes from systems you do not control, sometimes seconds later, sometimes by webhook.
3. The last request is the dangerous one. Every earlier request is safe to repeat. Placing the order moves money. If its response is lost, the shopper does not know whether they paid, and the naive fix (try again) can charge twice.
4. The world changes under the shopper. A shopper may spend 4 minutes on checkout, or leave the tab for an hour. Meanwhile an item sells out, a flash price ends, or a code expires. The design must notice, explain, and ask, never silently charge a different amount.
5. Every extra second and field costs orders. Large usability studies keep finding that long, confusing checkouts and surprise costs are among the top reasons people abandon a purchase. Speed, few fields, and honest totals are business requirements, not polish.

Put those together and the design has a clear center: a checkout session that lives on the server. It holds the cart snapshot, address, delivery choice, codes, the computed totals, and a version number. The browser edits the session through small calls and renders what the server says.

Placing the order is one idempotent call against one version of that session. Most of this guide is about getting that loop right.

One page or many steps: the shape of the flow

The first visible decision is the shape of the checkout. Teams argue about it for months, so it is worth knowing what the research says before picking.

The naive view is that fewer pages always convert better, so everything goes on one long page. The other naive view is that small steps feel easier, so every field group gets its own page. Baymard Institute, which has run large checkout usability studies for over a decade, finds that neither layout wins by itself.

In their testing, people had relatively few problems moving between steps when each step followed a few simple rules. The usability problems came from what each step asked the shopper to do. A lean form works in both layouts and a bloated one fails in both. Their benchmark puts the average US checkout at about 15 form fields shown by default (23 form elements), while 7 or 8 fields can be enough.

So the layout question is really about engineering and context, not magic conversion numbers. Here are the three serious options.

What goes in each section

Two details matter more than they look. First, the order summary is always visible: on desktop as a sticky right column, on a phone as a collapsed bar at the top that shows the total and expands to show line items. Not being able to see or calculate the total cost up front is itself a reason 12 percent of shoppers give for leaving, so the total is never more than one tap away.

Second, the place-order button names the amount, as in Pay 84.10 EUR. It turns the button into the last confirmation of the total and catches surprise costs before the click, not after.

Guest checkout, accounts after purchase, and express wallets

The fastest form is the one the shopper never fills. Two decisions remove most of the typing: let people buy without an account, and let wallet users skip the form entirely.

Guest checkout: the email is the identity

The naive checkout starts with a sign-in wall: sign in or create an account to continue. As the requirements showed, being made to create an account is one of the most common reasons people abandon. Many shoppers buy once a year from a store and do not want another password.

Two traps to avoid. Do not tell a guest that an account already exists for their email (that leaks who shops where, an account enumeration problem); instead offer an optional sign-in link and let them buy as a guest anyway. And when a guest becomes a user after purchase, link the order by the checkout session's one-time token, not just by matching the email, or anyone who types someone else's email could claim their order history.

Express checkout: wallets that skip the form

A wallet such as Apple Pay, Google Pay, PayPal, or Shop Pay already knows the shopper's address and card. In one sheet, the shopper confirms a shipping address, picks a delivery option, and authorizes payment with Face ID or a fingerprint. On a phone that turns minutes of typing into a few seconds.

What a wallet skips: the contact, address, delivery, and card sections. What it does not skip: server-side pricing, stock checks, the idempotent place-order call, and fraud checks. Because they skip so much, express buttons go at the very top of checkout, above the email field, and often also on the cart page and product page. Placing them after the form means the shopper has already typed everything the wallet would have filled.

The sequence has two engineering details that catch teams out. First, the sheet must open in direct response to the tap. The spec only allows show() during a user activation (a tap or key press the browser has just seen), and Safari is strict about it, so you cannot await a network call between the tap and show(). The total must already be known when the button renders, which means the checkout session is created and priced before the express buttons appear.

Second, the address in the change event is partial. Before the shopper authorizes, the browser redacts the address to what is needed to compute rates (country, region, city, postal code), leaving out the street lines, the recipient's name, and the phone. The full address arrives only after authorization. So the re-pricing endpoint must accept a partial address and return delivery options and an estimated tax for it.

const request = new PaymentRequest(methods, toDetails(session), {
  requestShipping: true,
  requestPayerEmail: true,
});

request.addEventListener("shippingaddresschange", (event) => {
  // Partial address: country, region, city, postal code.
  event.updateWith(
    api.reprice(session.id, { address: request.shippingAddress })
      .then((next) => toDetails(next)),
  );
});

buttonEl.addEventListener("click", async () => {
  const response = await request.show(); // must run inside the tap
  const result = await placeOrder({ walletToken: response.details });
  await response.complete(result.ok ? "success" : "fail");
});

Address entry: suggestions, country formats, and validation

The shipping address is the longest part of the form and the one with the costliest mistakes. A wrong postal code means a returned parcel, a refund, and a support ticket. It is also the input that drives delivery options and tax, so every keystroke here can change the total.

The naive form is the US form for everyone: street, city, state, ZIP. It breaks right away for a store in 20 countries. A required state field blocks a shopper in Germany, and a 5-digit ZIP check blocks everyone in Canada, whose codes look like K1A 0B1.

The differences run deep. The UK has postcodes but no states. Japan writes addresses from the largest unit to the smallest and puts the postal code first, often using it to fill the prefecture and city. Hong Kong has no postal codes at all, and Ireland has Eircodes that Google's address data treats as optional.

Country first, then the fields that country needs

The country select comes first, defaulted from the shopper's locale or the store region. Choosing a country swaps the field set: which fields exist, their labels (ZIP code, postcode, PIN code), which are required, their order, and the postal code pattern.

Do not invent this table yourself. Google publishes per-country address metadata (fields, required fields, labels, postal code patterns) through its open-source libaddressinput project, whose C++ library Chromium uses for its address forms. Many stores build on that data or on a provider's equivalent.

type AddressField = "name" | "line1" | "line2" | "city" | "region" | "postalCode";

type CountryFormat = {
  rows: AddressField[][];
  required: AddressField[];
  labels: Partial<Record<AddressField, string>>;
  postalPattern?: RegExp;
};

const formats: Record<string, CountryFormat> = {
  US: {
    rows: [["name"], ["line1"], ["line2"], ["city", "region", "postalCode"]],
    required: ["name", "line1", "city", "region", "postalCode"],
    labels: { region: "State", postalCode: "ZIP code" },
    postalPattern: /^\d{5}(-\d{4})?$/,
  },
  GB: {
    rows: [["name"], ["line1"], ["line2"], ["city"], ["postalCode"]],
    required: ["name", "line1", "city", "postalCode"],
    labels: { city: "Town or city", postalCode: "Postcode" },
  },
  HK: {
    rows: [["name"], ["line1"], ["line2"], ["region"]],
    required: ["name", "line1", "region"],
    labels: { region: "Area" },
  },
};

Let the browser fill it: autocomplete attributes

Before adding any address API, use what every browser already has. Browsers and password managers store addresses and fill a whole form in one tap, but only if the inputs say what they are. The HTML autocomplete attribute does that. A section token (shipping or billing) tells the browser which address the field belongs to, so it never mixes them.

Suggestions as you type

Next, a type-ahead that turns 12 characters into a full, valid address. Google Places Autocomplete, Loqate, and Mapbox are common choices. The mechanics are the autocomplete guide's (debounce, cancel stale requests, keyboard listbox) with three checkout-specific twists.

• Billing sessions. Places-style APIs bill per session: you send the same session token with each type-ahead request and with the final details request, so a whole lookup is billed as one session instead of one charge per keystroke. Create a new token per address entry, and debounce to about 150 to 250 ms so fast typists do not fire a request per key.
• Fill the structured fields, keep them editable. Picking a suggestion fills line 1, city, region, and postal code, then moves focus to line 2 (flat or apartment number), the field suggestions most often miss.
• Never trap the shopper. New buildings and rural addresses are often missing from the suggestions. A visible Enter address manually link must always be there, and the form must work fully if the suggestion script fails to load.

Validation and normalization

Format checks run in the browser (required fields, the postal code pattern for the country). Deliverability checks run on the server, when the shopper leaves the address section: an address validation service (Google's Address Validation API, a carrier API such as USPS in the US, or the provider's own) returns whether the address is deliverable and a normalized version, for example 123 main street apt 4 becomes 123 Main St Apt 4.

The UI rule is: suggest, do not overwrite. If the service proposes a change, show both versions and let the shopper pick, with the entered version one tap away. Services are wrong about new buildings and some rural addresses, and silently replacing what someone typed is how parcels go to the wrong place.

Block only on hard failures (the postal code does not exist in that country). We store both the normalized address and the shopper's raw input, so support can see what was really typed.

The total: delivery options, tax, discounts, and gift cards

The order summary has five to eight lines: subtotal, discounts, delivery, tax, gift card, total. Each depends on others. This chapter is about keeping that summary correct while the shopper changes things, and making sure the number on the button is the number charged.

Here is a concrete case. A shopper in Austin, Texas has a linen shirt and two wool scarves, 80.00 USD in all. They pick Express delivery (12.00) and apply code SHIP50, half off delivery. Texas sales tax (8.25 percent in Austin) applies to the goods and, because the goods are taxable, to the delivery charge too.

Now they switch the address to Portland, Oregon. Oregon has no sales tax, the Express option is not offered to that postal code, and the code still applies but to a different delivery price. Four lines change from one edit, and a browser that tried to compute this would need every tax rule, carrier rate, and promotion rule. That is exactly the knowledge the server already has.

Out-of-order responses and the session version

A shopper changes the postal code, then quickly picks a different delivery option. Two calls are in flight, and if the first response arrives last, the screen shows the total for the old option. This is a request race, and two tools fix it together.

First, the client aborts the earlier request with an AbortController when a newer edit to the same session starts. Second, the server stamps every response with the session version; the client ignores any response whose version is lower than the one it already shows. Aborting saves work; the version check is what guarantees correctness, since an aborted request may still have been applied on the server.

let inFlight: AbortController | null = null;

async function updateSession(patch: SessionPatch) {
  inFlight?.abort();
  const controller = new AbortController();
  inFlight = controller;
  store.markPending(patch);
  try {
    const next = await api.patchSession(store.session.id, patch, {
      signal: controller.signal,
    });
    if (next.version > store.session.version) store.setSession(next);
  } catch (err) {
    if (!controller.signal.aborted) store.showError(err);
  } finally {
    if (inFlight === controller) store.clearPending();
  }
}

Delivery options that depend on the address and cart

The delivery list comes from the server with the priced session: each option has an id, a label, a price, and an estimated delivery date range. It depends on the destination and the cart (a sofa cannot go by letter post; some items cannot ship to some regions).

When the address changes, three things can happen to the selected option: it stays valid at the same price, it stays valid at a new price, or it disappears. The server picks a replacement (the cheapest) when it disappears and reports the change. The client then shows it in the change summary instead of quietly switching it. Show delivery dates, not only speeds: Arrives Tue 14 to Thu 16 Oct is easier to judge than 3 to 5 business days.

Tax: computed by destination, shown the local way

• Before an address, show an estimate and say so. Use the country (and region if known) from the store locale: Estimated tax 6.40. Never show 0.00 as if it were final.
• Inclusive versus exclusive. In the EU and UK, consumer prices include VAT, so the summary shows Including 16.67 VAT and the total does not jump. In the US, sales tax is added on top. The server returns which mode applies; the client renders the right wording.
• Money as integers. Amounts travel as integer minor units with a currency ({ amount: 8410, currency: "EUR" }) and are formatted with Intl.NumberFormat. Floats lose cents (0.1 + 0.2 is not 0.3), and some currencies, such as the Japanese yen, have no minor unit at all.

Discount codes and gift cards

A discount code changes the price. A gift card pays part of it. They look similar in the UI but behave differently, and mixing them up causes bugs in tax and refunds.

When a code stops qualifying, do not delete it. Keep it attached and show why it is not applied, as in Code SAVE10 needs a subtotal of 60.00: add 5.05 more. Deleting it makes the shopper think they mistyped it.

When gift cards cover the whole total, the card fields hide and the button changes to Place order: no extra charge. The code entry field itself sits collapsed behind a Have a code? link: an open, empty code box sends many shoppers off to search for codes in another tab, and some never come back.

Try it below. Change the destination, the delivery option, the code, and the stock, and watch which lines the server recomputes and what the change summary tells the shopper.

Payment: card fields we never see, bank challenges, and declines

The naive payment form is four inputs in our own page (number, expiry, CVC, name) posted to our API, which forwards them to the payment provider. It works, and it is the most expensive choice we could make. Every server, log, and script that touches a card number falls under PCI DSS (the Payment Card Industry Data Security Standard, the security rules that card networks require of anyone handling card data). If card numbers pass through our API, the whole backend is in scope, and a single console.log(body) writes card numbers to a log file.

Merchants prove compliance with a Self-Assessment Questionnaire (SAQ), and which one applies depends on how the card form is built. That makes the payment form an architecture decision, not a styling one.

Tokens and the payment intent

Modern providers model a payment as an object on their side, created by our server with the amount and currency (Stripe calls it a PaymentIntent; Adyen and Braintree have their own equivalents). The browser never decides the amount. Because the amount lives on the server-side object, a tampered page cannot pay 1.00 for an 84.10 order.

Our design confirms the payment on the server, which providers support for exactly this case (Stripe calls it finalizing payments on the server). On Pay, the provider script turns the card data inside its frame into a token (in Stripe, a ConfirmationToken). Our place-order call sends that token to our checkout backend (a backend for frontend, or BFF, that owns the session), which confirms the intent for the session total, getting back succeeded, requires_action, or a decline.

The simpler alternative, where the provider script confirms the intent from the browser with a client secret, works too, but then our server learns the outcome only afterwards.

3-D Secure: a challenge in a frame or a redirect

Under strong customer authentication (SCA) rules in the EU and UK, the bank may ask the shopper to prove it is them, through 3-D Secure (3DS). The Amazon guide explains the protocol. What matters for our design is that a challenge arrives as requires_action, and the provider script then runs it (Stripe's handleNextAction) in one of two shapes.

Most often the provider opens the bank's page in a modal iframe on our page, and the provider's promise resolves when it closes. Sometimes the bank's flow needs the whole page, so the browser is redirected to the bank and back to a return URL we provide. Redirect-based payment methods such as iDEAL always work this way.

The redirect is the reason the server session matters again. Our page unloads, and every piece of state in memory is gone. The return URL carries the checkout session id (/checkout/cs_123/return), so the page loads the session from the server, reads the payment and order status, and shows the right screen. In both shapes, the page then reads the session (GET /checkout-sessions/{id}) to learn the result, so a design that handles the redirect handles the modal too.

Saved cards

Signed-in shoppers see their saved cards as a radio list: brand, last 4 digits, expiry, with the default selected. The card itself is stored by the provider against a customer id; we store only the provider's payment method id and the display fields.

Expired cards show as disabled with an Update link. Some stores ask for the CVC again on a saved card for riskier orders; that CVC field is a provider iframe too. A new card goes through the same frames, with a Save for next time checkbox that is off by default for guests.

Declines: clear, kind, and never revealing

In Baymard's survey, about 1 in 10 shoppers who abandoned cited a declined card. A decline is not the end of the order, as long as the page tells the shopper what to do next. The provider returns a decline code; we map it to a message that helps without leaking fraud signals.

The message goes in a live region and the error summary, focus moves to it, and the form keeps every value. Repeated declines from one session (say, 5 in 10 minutes) are a card-testing signal: fraudsters use checkouts to test stolen card numbers. The server rate-limits by session, IP, and device, and the client shows a bot check when told to.

Placing the order: exactly one charge, whatever the network does

Everything so far was safe to repeat: re-pricing twice gives the same total. Placing the order is different. It reserves stock, takes money, and creates a record that a warehouse acts on. It must happen exactly once per checkout, and the shopper must always end up knowing whether it happened.

The naive version disables the button and sends POST /orders with the cart and payment token. Here is how it fails, with numbers from a sale day where the place-order call takes 2 to 8 seconds under load:

1. Double tap. On a slow phone the second tap lands before React re-renders the disabled button. Two requests leave. Two orders.
2. Impatient retry. After 8 seconds of spinner, the shopper refreshes and presses Place order again. The first request was still running. Two orders.
3. Lost response. The server charged the card and created the order, then the train entered a tunnel. The browser gets a network error. The page says Something went wrong, try again. The shopper does. Two charges, and a support ticket.
4. Two tabs. The shopper had checkout open in two tabs and placed the order in both. Two orders for one cart.

The third case is the important one, because no amount of button disabling fixes it: the client simply does not know the outcome. Any safe design must let the client ask again, or retry, without the risk of doing the work twice. The flight booking guide solves this for a booking with an idempotency key; checkout adds a second layer, the session, for tabs and refreshes.

On the client: a guard, a key, and bounded retries

The client side is small but every line matters. A synchronous guard (a ref, not React state, so it is set before the next tap is handled) stops double taps. The key is created once per press for a given session version and saved in sessionStorage, so a refresh during submit reuses it.

Network errors and 5xx responses are retried with the same key and backoff (see the retries and backoff lesson); 4xx responses are answers, not failures, and are never retried. After the retries run out, the client does not show an error. It switches to reconciling: it asks the server what happened.

const submitting = useRef(false);

async function placeOrder(session: CheckoutSession) {
  if (submitting.current) return;
  submitting.current = true;
  const keyName = `place:${session.id}:${session.version}`;
  const key = sessionStorage.getItem(keyName) ?? crypto.randomUUID();
  sessionStorage.setItem(keyName, key);
  machine.send("SUBMIT");
  try {
    for (const delay of [0, 1000, 3000]) {
      await sleep(delay);
      try {
        const res = await api.complete(session.id, session.version, key);
        return machine.send({ type: "RESULT", res }); // 2xx or 4xx
      } catch {
        // network error or 5xx: same key, try again
      }
    }
    machine.send("UNKNOWN"); // starts polling GET /checkout-sessions/:id
  } finally {
    submitting.current = false;
  }
}

On the server: the order of steps

The frontend engineer does not build this, but must know its shape to design the client states. The complete call runs these steps in order, and each is safe to repeat:

1. Look up the idempotency key. If a stored response exists, return it. If the same key is still running, return 409 with the error code request_in_progress and a hint to poll.
2. Lock the session. If it is already completed, return the existing order. If it is processing, return 202 Accepted with the status URL.
3. Check the version. If the shopper's version is older than the current one, return 409 with the current session.
4. Re-validate: recompute prices, tax, promotions, and stock. If anything changed, bump the version and return 409 with a change list.
5. Reserve stock, then confirm the payment with the provider, using an idempotency key derived from the session id. If the bank wants a 3-D Secure challenge, return 202 with what the page needs to run it.
6. Create the order, mark the session completed, store the response under the key, and return 201 with the order id.

The confirmation page is the source of truth

On success, the client navigates to /orders/{id}/confirmation with history.replaceState semantics (the router's replace option), so the Back button does not return to a page that offers to place the order again. The confirmation page loads the order from the server, not from memory, so a refresh, a shared link, or a return from a 3DS redirect all show the same truth. If the shopper does go back to /checkout/cs_123, the session is completed and the page shows Your order is placed with a link to it, not a fresh form.

Try the lab below. Each scenario is a real failure. Compare the three strategies and count charges and orders.

When things change or break: re-validation and reconciliation

Two kinds of trouble arrive at the last moment. The world changed while the shopper was typing (a price, a stock level, a code). Or the place-order call itself ended without an answer. Both need a screen that is honest, calm, and never asks the shopper to pay twice.

Re-validation at submit: show what changed and ask

Prices and stock on the page are a snapshot from the last re-pricing, maybe 20 minutes ago. The server re-validates everything inside the complete call (step 4 in the previous chapter). If anything differs, it does not charge. It bumps the session version and returns 409 Conflict with the new session and a list of changes.

{
  "error": "session_changed",
  "session": { "id": "cs_123", "version": 9, "total": { "amount": 9130, "currency": "EUR" } },
  "changes": [
    { "kind": "price", "lineId": "li_2", "from": 2990, "to": 3490 },
    { "kind": "stock", "lineId": "li_3", "requested": 2, "available": 1 },
    { "kind": "promotion", "code": "SPRING", "reason": "expired" }
  ]
}

The UI turns that into a short panel above the button: Before you pay, 3 things changed. Each change gets one line in plain words (Linen shirt is now 34.90, was 29.90; Only 1 Wool scarf left, we updated the quantity; Code SPRING has ended), followed by the new total on the button: Pay 91.30 EUR. Focus moves to the panel heading and a live region announces it. The shopper must press the button again; nothing is charged at a price they did not see.

Payment went through, the response did not

This is the failure that makes checkout a system design question. The server charged the card and created the order, but the response was lost. The client's retries also time out because the phone is offline. What does the shopper see, and how does the order still get completed if they close the tab?

Three mechanisms work together, one on each side.

• The client polls the session. After retries run out, the page shows Confirming your order. Please do not pay again. It polls GET /checkout-sessions/{id} with backoff (1, 2, 4, 8 seconds, capped at 10, for up to 2 minutes), and resumes immediately when the browser fires the online event or the tab becomes visible again. The answer is one of completed (go to the confirmation), processing (keep waiting), or open with a payment error (show it and let them try again).
• The provider webhook completes the order on the server. The payment provider sends a webhook (a server-to-server HTTP call) to our backend: in Stripe, payment_intent.succeeded, or payment_intent.amount_capturable_updated when the card is only authorized. If the session is still processing because our own request died halfway, the webhook handler finishes it: creates the order and sends the confirmation email. The order no longer depends on the browser staying open. Webhooks can arrive late, twice, or out of order, so the handler is idempotent too (see the webhooks lesson).
• A sweeper resolves the stuck ones. A scheduled job asks the provider about any session stuck in processing for more than a few minutes. If the payment succeeded, it completes the order; if the order cannot be created (the stock is gone), it voids the authorization or refunds and emails the shopper.

A pending state, not an error

The wording of the unknown state decides whether the shopper pays twice. Something went wrong, please try again invites a second payment. A calm message does not: Confirming your order, this can take up to a minute, we will email a.shopper@example.com when it is confirmed, please do not pay again. The place-order button is hidden in this state, not just disabled.

If two minutes pass with no answer, the page says the order is still being confirmed and that the email will follow, with a link to support, still without a Pay button. Other tabs with the same session hear about the result over a BroadcastChannel and switch to the same state.

Expiry and time limits

A checkout session expires after some hours (say 24) so stale prices cannot be charged days later. Most stores do not hold stock during checkout. For flash sales that do (a 10-minute reservation, like a fare hold in the flight booking guide), the timer must follow WCAG's timing rules: show it, warn at least 20 seconds before it ends, and let the shopper extend it with one action. An expired session opens a fresh one from the same cart and shows what changed, the same panel as above.

Architecture, data model, and interface

With the decisions made, the parts fall out of them. The checkout is its own route with its own small bundle. It talks to one backend for frontend (BFF) that owns the checkout session, and it hosts the payment provider's frames, which talk to the provider directly.

Three boundaries deserve a sentence each in an interview. The money boundary: the browser never computes or decides an amount; it renders what the BFF returns and confirms intents the BFF created. The card boundary: card data exists only inside the provider's frames and the provider's servers. The truth boundary: the session on the server is the truth; the client store is a cache of it with a version, rebuilt from scratch after a refresh or a 3DS redirect.

Rendering and loading

The checkout is a separate route with its own entry, not a modal inside the store's single-page app. That keeps its JavaScript small and lets us run a stricter Content Security Policy (CSP) on it than on the rest of the store. The server renders the shell with the priced session embedded, so the summary and the express buttons are visible at first paint. The loading order (provider script early, address suggestions late) is in the performance section.

Data model: what the client holds, and where

The client holds little, and almost all of it is a copy of the server session. The truth boundary shapes the model: money and availability come from the server; the client owns only what the shopper is typing right now and the status of its own requests.

type Money = { amount: number; currency: string }; // minor units

type CheckoutSession = {
  id: string;
  version: number;
  status: "open" | "processing" | "completed" | "expired";
  email?: string;
  lines: { id: string; sku: string; title: string; qty: number; unit: Money; total: Money }[];
  shippingAddress?: Address;
  billingSameAsShipping: boolean;
  deliveryOptions: { id: string; label: string; price: Money; arrives: [string, string] }[];
  selectedDeliveryId?: string;
  codes: { code: string; applied: boolean; reason?: string; amount?: Money }[];
  giftCards: { last4: string; applied: Money }[];
  totals: {
    subtotal: Money; discount: Money; delivery: Money;
    tax: Money; taxIncluded: boolean; taxEstimated: boolean;
    giftCards: Money; due: Money;
  };
  payment: { intentClientSecret?: string; status?: string; declineCode?: string };
  orderId?: string;
  expiresAt: string;
};

Notice what is missing: no local copy of prices to compute with, no cart in localStorage that could disagree with the session, no card fields in form state. Autosaving drafts is still useful for the address, but the right place for it is the server session (sent on blur), not localStorage with personal data in it; the multi-step form guide explains autosave in depth.

Interface: the checkout API

The API is small and resource-shaped: one session resource with a few actions. Every write returns the full priced session, so the client never has to merge partial responses.

POST /checkout-sessions/cs_123/complete
Idempotency-Key: 6f1c2a9e-4b7d-4e55-9a51-0c3e8f2d7b10
Content-Type: application/json
X-CSRF-Token: 8d0e...

{ "expectedVersion": 8, "paymentMethod": "pm_1Q...", "expectedTotal": { "amount": 8410, "currency": "EUR" } }

HTTP/1.1 201 Created
Content-Type: application/json

{ "orderId": "ord_88412", "status": "completed", "confirmationUrl": "/orders/ord_88412/confirmation" }

The request sends expectedTotal as well as the version. The version alone is enough for the server to detect change, but the total makes the intent explicit in logs and lets the server refuse if the client rendered a different number for any reason. Errors use one shape across all calls: a machine-readable error code, a human message that is safe to show, field paths for validation errors, and the current session when relevant (see the API contracts and errors lesson).

{
  "error": "payment_declined",
  "declineCode": "insufficient_funds",
  "message": "Your card was declined.",
  "retryable": true,
  "session": { "id": "cs_123", "version": 8, "status": "open" }
}

Component interfaces

type SectionProps = {
  session: CheckoutSession;
  pending: boolean;
  open: boolean;
  onOpen: () => void;
  onPatch: (patch: SessionPatch) => Promise<void>;
};

<AddressSection {...common} formats={formats} suggest={addressService} />
<DeliverySection {...common} />
<PaymentSection {...common} adapter={paymentAdapter} savedCards={user?.cards} />
<OrderSummary session={session} pending={pending} />
<PlaceOrderButton total={session.totals.due} state={machine.state} onPress={placeOrder} />

Security: forged requests, script control, and web skimming

Checkout is the most attacked page of a store, for an obvious reason: it is where the money and card numbers are. Three threats shape the frontend: requests forged from other sites, scripts that should not run on the page, and skimmers that steal what shoppers type.

Forged requests (CSRF)

The checkout session lives in a cookie, so a malicious site could try to make the shopper's browser send POST /checkout-sessions/cs_123/complete with that cookie attached. The CSRF lesson covers the defences in depth; for checkout we use all three cheap layers.

The session cookie is SameSite=Lax (or Strict), Secure, and HttpOnly. Every state-changing call carries a CSRF token from the server-rendered page in a header, which a cross-site form cannot set. And the BFF checks the Origin header on writes. The 3DS redirect return arrives as a top-level GET, which Lax cookies allow, so the return page works; it only reads state and never places orders.

Web skimming (Magecart) and why the iframe is not enough

Web skimming, often called Magecart after the groups that made it famous, is malicious JavaScript added to a checkout page that copies what shoppers type and sends it to the attacker. The attacker does not need to break into the store's servers: changing one third-party script the page loads is enough.

In the 2018 British Airways breach, attackers changed a JavaScript library served from BA's own site and skimmed the card and personal details of up to about 429,000 customers and staff over about two weeks; the UK regulator later fined the airline 20 million pounds.

Provider iframes protect the card numbers from being read directly, but a script on our page can still hide the real frame and draw a fake card form on top, or skim the name, email, and address fields, which are on our page. So the page that hosts the payment frames must run only scripts we know about. That is exactly what PCI DSS 4.0 added in two requirements, best practice until 31 March 2025 and mandatory since.

As covered in the payment chapter, a merchant that only embeds provider frames may be able to complete SAQ A, where these two items are replaced by the eligibility criterion about script attacks. The PCI SSC's FAQ 1588 allows two ways to confirm it: script controls like those in 6.4.3 and 11.6.1, run by the merchant or a third party, or a confirmation from the provider that its embedded form protects the page when integrated as instructed. Either way, the engineering is the same: a short, known script list is what makes the claim true.

A strict Content Security Policy for the checkout route

The CSP lesson explains the directives; here is what is specific to checkout. The policy is stricter than the store's and lists the payment provider's and the address service's origins explicitly. Use nonces for our own scripts and keep the list of allowed origins short.

If you add strict-dynamic so that a trusted loader can add scripts, browsers that support it ignore the origin list, and the nonce becomes the control. Provider docs publish the exact origins they need; the example uses the ones Stripe lists for Stripe.js, including hooks.stripe.com for 3DS and redirect frames.

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'nonce-r4nd0m' https://js.stripe.com https://*.js.stripe.com https://maps.googleapis.com;
  frame-src https://js.stripe.com https://*.js.stripe.com https://hooks.stripe.com;
  connect-src 'self' https://api.stripe.com https://maps.googleapis.com https://places.googleapis.com;
  img-src 'self' data: https://*.stripe.com https://maps.gstatic.com;
  frame-ancestors 'none';
  form-action 'self';
  base-uri 'none';
  report-to csp-endpoint

• frame-ancestors 'none' stops other sites from framing the checkout to trick clicks (clickjacking).
• form-action 'self' stops an injected form from posting to an attacker's server.
• No tag managers, chat widgets, heatmaps, or ad pixels on the checkout route. Each one is a script that can change the page. Purchase events are sent from our own code or from the server (next chapter).
• Provider scripts update in place at a fixed URL, so they cannot carry a fixed SRI hash. Allow them by origin, keep them in the inventory, and let the change monitor watch them.
• report-to names an endpoint declared in a Reporting-Endpoints response header, where the browser sends violation reports for the change monitor to read.

Two smaller items. Shopper input (names, address lines, gift messages) is rendered as text, never as HTML, so a name like an image tag with an onerror handler stays harmless; see the XSS lesson. And code and gift card endpoints are rate-limited per session, IP, and device, because they are guessing targets.

Speed, accessibility, and measuring the funnel

Three qualities decide whether a correct checkout is also a good one: it loads fast on a mid-range phone, everyone can complete it, and the team can see where people give up without collecting their personal data.

Performance: a small page with one heavy guest

• Budget. Our own JavaScript for the route stays under about 150 KB compressed. The provider script is the largest single item and is not optional, so everything else gives way to it: no carousels, no recommendation widgets, no chat.
• First paint shows real numbers. The server renders the priced session, so LCP (Largest Contentful Paint) is the summary or the first section, not a spinner. Target LCP under 2.5 s at the 75th percentile on mobile.
• Connect early. The provider script is on the critical path for the Pay button, so it loads early, and preconnect hints to the provider's script and API origins in the document head do the DNS lookup and the TCP and TLS handshakes ahead of time (often a few hundred milliseconds on mobile).
• Load late what is late. The address suggestion script loads on focus of the address field. The 3DS code is inside the provider SDK and loads only when needed.
• Keep taps fast. INP under 200 ms: a tap updates the selected option right away and the re-pricing call runs in the background, and there are no long tasks from third-party scripts, because the route has none.
• No layout jumps. Payment frames and delivery options get reserved heights so they do not push the Pay button as they load (CLS, Cumulative Layout Shift, under 0.1). A Pay button that moves under a thumb causes mis-taps.

Accessibility: errors, focus, and time

The multi-step form guide covers the error summary and inline errors in depth; checkout adds a few specific points.

• Error summary first. On a failed submit, a summary at the top of the open section lists each error as a link to its field, and receives focus. For errors inside provider frames, the provider's own error text appears inside the frame, and our summary links to the frame's container.
• Announce money changes. When the total changes after re-pricing, a polite live region says Total updated to 84.10 euros. It is debounced so a burst of changes is announced once. The change panel at submit is announced and focused.
• Focus on section changes. When a section completes and the next opens, focus moves to the new section's heading. The collapsed summary keeps an Edit button that names what it edits (Edit shipping address).
• Busy, not frozen. While placing the order the button shows a progress label (Placing order) and has aria-disabled plus a guard in the handler, so screen reader users still hear what is happening. During reconciling, a status message explains the wait.
• Time limits. No hidden session timeouts. If a reservation timer exists, follow WCAG 2.2.1: warn before it ends and allow extending it with one action.
• Wallets and frames. Wallet sheets and provider fields are accessible by their makers, but test them with VoiceOver and TalkBack in your page, with your labels. A visible label above each frame (Card number) is still ours to provide when the provider asks for it.

Measuring the funnel without leaking personal data

The business wants to know where shoppers give up: how many start checkout, finish each section, see a decline, and place an order. The analytics tracking lesson covers event design and delivery. The checkout-specific rules are about privacy and trust.

Events go from our own code to our own collection endpoint (first-party), batched and sent with navigator.sendBeacon or fetch with keepalive so the last event before navigation is not lost. The purchase event that ad platforms need is sent server-side from the order system, not from a pixel on the payment page. URLs in events are scrubbed of query parameters, because return URLs from payment redirects can carry tokens.

With this, a funnel chart shows, for example, that 31 percent of mobile shoppers who open the payment section never finish it, and the error events show whether that is declines, frame load failures, or something else.

Running it in the interview

A checkout question rewards candidates who find the dangerous parts early. Many spend 30 minutes on form fields and run out of time before the place-order request, which is where most of the senior signal is. Here is a plan for 60 minutes.

Draw the place-order sequence with the failure path on the board. It is the single picture that shows you understand distributed systems from the browser's side: the request, the charge, the lost response, the retry with the same key, the poll, and the webhook arriving at the server independently.

Follow-up questions and strong answers