Payment Checkout Flow (e.g. Stripe, Shopify)

/checkout            → redirects to /checkout/information
/checkout/information → email + shipping address
/checkout/shipping    → shipping method selection
/checkout/payment     → payment method + billing
/checkout/review      → order summary + place order
/checkout/confirmation/[orderId] → post-purchase

┌─────────────────────────────────────────────────────────────────────────┐
│                           BROWSER                                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐  ┌──────────────────┐  ┌───────────────────────────┐  │
│  │ Checkout App │  │ Hosted Fields    │  │ Apple Pay / Google Pay    │  │
│  │ (Your Code)  │  │ (Stripe iframe)  │  │ (Payment Request API)    │  │
│  │              │  │                  │  │                           │  │
│  │ - Steps UI   │◄─┤ - Card Number    │  │ - canMakePayment()       │  │
│  │ - State Mgmt │  │ - Expiry         │  │ - show() → token         │  │
│  │ - Validation │  │ - CVC            │  │ - onshippingaddresschange │  │
│  │ - API calls  │  │ - PostalCode     │  │                           │  │
│  └──────┬───────┘  └────────┬─────────┘  └─────────────┬─────────────┘  │
│         │                    │                           │                │
│         │    postMessage     │      Payment Token        │                │
│         │◄───────────────────┘                           │                │
│         │◄───────────────────────────────────────────────┘                │
│         │                                                                 │
└─────────┼─────────────────────────────────────────────────────────────────┘
          │ HTTPS (fetch)
          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        YOUR API (BFF)                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  ┌───────────────┐  │
│  │ Checkout    │  │ Inventory    │  │ Price      │  │ Fraud Signal  │  │
│  │ Session API │  │ Reservation  │  │ Calculator │  │ Collector     │  │
│  └──────┬──────┘  └──────┬───────┘  └─────┬──────┘  └───────┬───────┘  │
│         │                 │                 │                  │          │
└─────────┼─────────────────┼─────────────────┼──────────────────┼──────────┘
          │                 │                 │                  │
          ▼                 ▼                 ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐
│ Stripe /     │  │ Inventory    │  │ TaxJar /     │  │ Device Fingerprint│
│ Adyen /      │  │ Service      │  │ Avalara      │  │ (Fingerprint.js) │
│ Payment PSP  │  │ (Redis TTL)  │  │ Tax Engine   │  │                  │
└──────────────┘  └──────────────┘  └──────────────┘  └──────────────────┘

CheckoutLayout (server component — shell only)
├── CheckoutProgress (client — step indicator)
├── CheckoutRouter (client — step management)
│   ├── InformationStep
│   │   ├── EmailInput
│   │   ├── AddressForm
│   │   │   ├── AddressAutocomplete (Google Places)
│   │   │   └── AddressFields (street, city, state, zip, country)
│   │   └── SavedAddressPicker
│   ├── ShippingStep
│   │   ├── ShippingMethodList
│   │   └── DeliveryEstimate
│   ├── PaymentStep
│   │   ├── PaymentMethodSelector
│   │   ├── CardPaymentForm
│   │   │   ├── HostedCardNumber (iframe)
│   │   │   ├── HostedExpiry (iframe)
│   │   │   ├── HostedCVC (iframe)
│   │   │   └── BillingAddressToggle
│   │   ├── WalletPaymentButton (Apple Pay / Google Pay)
│   │   ├── BNPLOption (Klarna / Afterpay)
│   │   ├── PayPalButton (PayPal JS SDK)
│   │   └── BankRedirectOption (iDEAL, Sofort)
│   ├── ReviewStep
│   │   ├── OrderSummary
│   │   ├── PriceBreakdown
│   │   └── PlaceOrderButton (idempotent)
│   └── ConfirmationStep
│       ├── OrderConfirmation
│       └── PostPurchaseUpsell
├── CartSummary (client — sticky sidebar)
│   ├── CartItemList
│   ├── DiscountCodeInput
│   └── PriceTotals
└── CheckoutErrorBoundary

interface CheckoutSession {
  id: string; // UUID, server-generated
  cartId: string; // Reference to cart entity
  status: CheckoutStatus;
  email: string | null;
  shippingAddress: Address | null;
  billingAddress: Address | null;
  shippingMethod: ShippingMethod | null;
  paymentMethodType: PaymentMethodType | null;
  paymentIntentId: string | null; // Stripe PI / Adyen ref
  idempotencyKey: string; // Generated once per checkout attempt
  inventoryReservationId: string | null;
  reservationExpiresAt: string | null; // ISO 8601
  discountCodes: string[];
  pricing: PriceCalculation | null;
  fraudSignals: FraudSignals;
  createdAt: string;
  updatedAt: string;
  expiresAt: string; // Entire session TTL (30 min)
}

type CheckoutStatus =
  | "information"
  | "shipping"
  | "payment"
  | "review"
  | "processing"
  | "requires_action" // 3DS challenge pending
  | "completed"
  | "failed"
  | "abandoned";

interface Address {
  firstName: string;
  lastName: string;
  line1: string;
  line2: string | null;
  city: string;
  state: string;
  postalCode: string;
  country: string; // ISO 3166-1 alpha-2
  phone: string | null;
  placeId: string | null; // Google Places reference
  validated: boolean; // Server-validated via USPS/Royal Mail
}

interface ShippingMethod {
  id: string;
  carrier: string;
  name: string; // "Standard", "Express", "Next Day"
  estimatedDays: { min: number; max: number };
  price: MoneyAmount;
  cutoffTime: string | null; // ISO 8601 time for same-day dispatch
}

type PaymentMethodType =
  | "card"
  | "apple_pay"
  | "google_pay"
  | "paypal"
  | "klarna"
  | "afterpay"
  | "ach_debit"
  | "ideal"
  | "sofort"
  | "crypto";

interface PriceCalculation {
  subtotal: MoneyAmount;
  shippingCost: MoneyAmount;
  taxAmount: MoneyAmount;
  discountAmount: MoneyAmount;
  total: MoneyAmount;
  taxBreakdown: TaxLineItem[];
  discountBreakdown: DiscountLineItem[];
  currency: string; // ISO 4217
}

interface MoneyAmount {
  amount: number; // Integer cents (avoid floating point)
  currency: string; // ISO 4217
  formatted: string; // "$12.99" — server-formatted for locale
}

interface TaxLineItem {
  jurisdiction: string;
  rate: number; // 0.0825 for 8.25%
  amount: MoneyAmount;
  type: "sales_tax" | "vat" | "gst";
}

interface DiscountLineItem {
  code: string;
  type: "percentage" | "fixed_amount" | "free_shipping";
  value: number;
  appliedAmount: MoneyAmount;
}

interface CartItem {
  id: string;
  productId: string;
  variantId: string;
  title: string;
  variantTitle: string;
  imageUrl: string;
  quantity: number;
  unitPrice: MoneyAmount;
  lineTotal: MoneyAmount;
  inventoryStatus: "available" | "low_stock" | "reserved" | "unavailable";
  maxQuantity: number;
}

interface FraudSignals {
  deviceFingerprint: string; // Fingerprint.js visitorId
  sessionDurationMs: number;
  pagesVisitedBeforeCheckout: number;
  previousPurchaseCount: number;
  ipGeolocation: string | null; // Country code from server
  browserTimezone: string;
  screenResolution: string;
  touchCapable: boolean;
  cookiesEnabled: boolean;
  webdriverDetected: boolean;
}

// Client-side UI state (Zustand store)
interface CheckoutUIState {
  currentStep: CheckoutStatus;
  stepValidation: Record<CheckoutStatus, boolean>;
  isSubmitting: boolean;
  submitError: CheckoutError | null;
  hostedFieldsReady: boolean;
  hostedFieldErrors: Record<string, string>;
  threeDSChallengeUrl: string | null;
  reservationTimeRemaining: number | null; // seconds
  paymentMethodsAvailable: PaymentMethodType[];
}

interface CheckoutError {
  code: string;
  message: string;
  field: string | null;
  recoverable: boolean;
  suggestedAction:
    | "retry"
    | "change_method"
    | "contact_support"
    | "update_card";
}

// POST /api/checkout/sessions
// Creates a new checkout session from cart
interface CreateCheckoutRequest {
  cartId: string;
  email?: string;
  returnUrl: string; // For 3DS redirect return
}

interface CreateCheckoutResponse {
  sessionId: string;
  clientSecret: string; // For Stripe.js initialization
  expiresAt: string;
  reservationExpiresAt: string;
}

// PATCH /api/checkout/sessions/:sessionId
// Updates session (address, shipping, etc.)
interface UpdateCheckoutRequest {
  email?: string;
  shippingAddress?: Address;
  billingAddress?: Address;
  shippingMethodId?: string;
  discountCode?: string;
}

interface UpdateCheckoutResponse {
  session: CheckoutSession;
  pricing: PriceCalculation; // Recalculated after each update
  availableShippingMethods?: ShippingMethod[];
  validationErrors?: ValidationError[];
}

// POST /api/checkout/sessions/:sessionId/confirm
// Idempotent order placement
interface ConfirmCheckoutRequest {
  paymentMethodType: PaymentMethodType;
  paymentToken?: string; // From hosted fields tokenization
  idempotencyKey: string; // Client-generated UUID, stored in session
  returnUrl: string; // 3DS redirect return URL
  fraudSignals: FraudSignals;
}

interface ConfirmCheckoutResponse {
  status: "completed" | "requires_action" | "failed";
  orderId?: string;
  redirectUrl?: string; // 3DS challenge URL
  error?: CheckoutError;
}

// GET /api/checkout/sessions/:sessionId/status
// Poll after 3DS redirect return
interface CheckoutStatusResponse {
  status: CheckoutStatus;
  orderId?: string;
  error?: CheckoutError;
}

// POST /api/checkout/calculate-price
// Called on address/shipping/discount change
interface CalculatePriceRequest {
  cartId: string;
  shippingAddress?: Address;
  shippingMethodId?: string;
  discountCodes: string[];
}

interface CalculatePriceResponse {
  pricing: PriceCalculation;
  warnings?: PriceWarning[]; // "Item X price changed since added to cart"
}

interface PriceWarning {
  type: "price_changed" | "item_unavailable" | "discount_expired";
  itemId?: string;
  message: string;
}

// POST /api/checkout/validate-address
interface ValidateAddressRequest {
  address: Address;
}

interface ValidateAddressResponse {
  valid: boolean;
  suggestedAddress?: Address; // Standardized version
  corrections?: AddressCorrection[];
}

interface AddressCorrection {
  field: keyof Address;
  original: string;
  suggested: string;
}

Timeline (4G mid-range device):
────────────────────────────────────────────────────────────────
0ms       HTML + critical CSS arrive
100ms     Shell renders (progress bar, layout)
300ms     Main JS chunk executes, Zustand hydrates from localStorage
500ms     Cart summary renders (from cache or API)
800ms     Form fields render, autofocus on first empty field
1200ms    Stripe.js loaded, iframe mounting begins
1800ms    Hosted fields ready (interactive card input)
2200ms    Address autocomplete SDK ready
2500ms    Full TTI — all interactions functional
────────────────────────────────────────────────────────────────

Checkout bundle breakdown:
─────────────────────────────────
Core checkout logic:         28KB gzipped
React + React DOM:           42KB (shared across app)
Zustand + React Query:        8KB
Form validation (Zod):        6KB
─────────────────────────────────
Total blocking:              84KB

Lazy-loaded (per payment method):
Stripe.js (external):       35KB (loaded from js.stripe.com)
PayPal SDK (external):       45KB (loaded on PayPal selection)
Klarna Widget:               22KB (loaded on BNPL selection)
Google Places:               18KB (loaded on address focus)
─────────────────────────────────

┌─────────────────────────────────────────────────┐
│              YOUR DOMAIN (merchant.com)           │
│                                                   │
│   ┌─────────────────────────────────────────┐    │
│   │  Checkout Application                    │    │
│   │  - Renders form layout                   │    │
│   │  - Manages non-sensitive state           │    │
│   │  - CANNOT read iframe content            │    │
│   │                                          │    │
│   │  ┌────────────────────────────────────┐  │    │
│   │  │ iframe src="js.stripe.com/v3/..."  │  │    │
│   │  │ ┌──────────────────────────────┐   │  │    │
│   │  │ │  Card Number: 4242...        │   │  │    │
│   │  │ │  (Rendered by Stripe JS)     │   │  │    │
│   │  │ └──────────────────────────────┘   │  │    │
│   │  │                                    │  │    │
│   │  │ Communication: postMessage only    │  │    │
│   │  │ Events: focus, blur, error, ready  │  │    │
│   │  │ No card data crosses this boundary │  │    │
│   │  └────────────────────────────────────┘  │    │
│   └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

confirmCardPayment() → status: "succeeded" → show confirmation

confirmCardPayment() → status: "requires_action"
  → stripe.handleNextAction() renders 3DS iframe/modal
  → User completes challenge in-page
  → status: "succeeded" → show confirmation

confirmCardPayment({ return_url }) → status: "requires_action"
  → Browser redirects to bank's 3DS page
  → User authenticates with bank
  → Bank redirects to return_url?payment_intent=pi_xxx&redirect_status=succeeded
  → App reads URL params, polls /api/checkout/sessions/:id/status
  → status: "completed" → show confirmation

type ThreeDSState =
  | { status: "idle" }
  | { status: "challenge_presented"; challengeUrl: string }
  | { status: "challenge_completed"; paymentIntentId: string }
  | { status: "redirect_initiated"; returnUrl: string }
  | {
      status: "redirect_returned";
      paymentIntentId: string;
      redirectStatus: string;
    }
  | { status: "failed"; error: CheckoutError };

async function handlePlaceOrder(): Promise<void> {
  if (store.getState().isSubmitting) return; // Guard against race conditions

  store.setState({ isSubmitting: true, submitError: null });

  const idempotencyKey = store.getState().idempotencyKey; // Generated once on review step entry

  try {
    const result = await confirmCheckout({
      idempotencyKey,
      paymentMethodType: store.getState().paymentMethodType,
      paymentToken: store.getState().paymentToken,
      returnUrl: `${window.location.origin}/checkout/payment?session=${sessionId}`,
      fraudSignals: collectFraudSignals(),
    });

    if (result.status === "completed") {
      router.push(`/checkout/confirmation/${result.orderId}`);
    } else if (result.status === "requires_action") {
      store.setState({ threeDSChallengeUrl: result.redirectUrl });
    } else {
      store.setState({ submitError: result.error, isSubmitting: false });
    }
  } catch (error) {
    store.setState({
      submitError: {
        code: "network_error",
        message: "Connection failed. Your card was not charged.",
        recoverable: true,
        suggestedAction: "retry",
        field: null,
      },
      isSubmitting: false,
    });
  }
}

<main role="main" aria-label="Checkout">
  <nav aria-label="Checkout progress">
    <ol role="list">
      <li aria-current="step">Shipping</li>
      <li>Payment</li>
      <li>Review</li>
    </ol>
  </nav>

  <form aria-labelledby="step-heading">
    <h1 id="step-heading">Shipping Address</h1>
    <!-- Step content -->
  </form>
</main>

// Announce price changes
<div aria-live="polite" aria-atomic="true" className="sr-only">
  {`Order total updated to ${pricing.total.formatted}`}
</div>

// Announce validation errors
<div aria-live="assertive" role="alert" className="sr-only">
  {validationError && `Error: ${validationError.message}`}
</div>

// Announce step transitions
<div aria-live="polite" className="sr-only">
  {`Step ${currentStepNumber} of 4: ${currentStepName}`}
</div>

// Announce payment processing
<div aria-live="assertive" className="sr-only">
  {isSubmitting && "Processing your payment. Please wait."}
</div>

// Structured error reporting
function reportCheckoutError(
  error: CheckoutError,
  context: ErrorContext,
): void {
  errorTracker.capture({
    error,
    tags: {
      checkout_step: context.step,
      payment_method: context.paymentMethod,
      is_retry: context.isRetry,
      session_id: context.sessionId, // For correlation
    },
    extra: {
      cart_item_count: context.cartItemCount,
      cart_total: context.cartTotal,
      time_in_checkout: context.timeInCheckoutMs,
      device_type: context.deviceType,
    },
  });
}

┌─────────────────────────────────────────────────────────────┐
│  CHECKOUT HEALTH DASHBOARD                                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  [1] Conversion Funnel          [2] Payment Success Rate     │
│  Cart → Info → Ship → Pay →     ████████████░░ 94.2%        │
│  Review → Confirm               Declined: 4.1%              │
│  ███ → ██ → ██ → █ → █ → █     3DS Failed: 1.7%            │
│  100%  82%  78%  74%  71% 68%                               │
│                                                              │
│  [3] Latency (p75)             [4] Error Rate               │
│  Checkout load: 1.8s           Client JS: 0.02%             │
│  Payment form ready: 1.4s      API 5xx: 0.01%               │
│  Confirm → complete: 2.1s     Stripe errors: 0.3%           │
│                                                              │
│  [5] Revenue at Risk            [6] Active Checkouts         │
│  Abandoned (last 1h): $4,200    In progress: 342            │
│  Failed payments: $890          Awaiting 3DS: 28             │
│  Expired reservations: $320     Reservation expiring: 12     │
│                                                              │
│  [7] Payment Method Mix         [8] Device Split             │
│  Card: 62%  Apple Pay: 18%      Mobile: 58%                 │
│  PayPal: 12%  BNPL: 5%         Desktop: 37%                │
│  Other: 3%                      Tablet: 5%                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘