@cartbase/storefront 0.20.1 → 0.22.0

package/src/checkout/order-summary.tsx

@@ -1,16 +1,15 @@
 "use client"
 
-import { useEffect, useMemo, useState } from "react"
+import { useEffect } from "react"
 
 import type { StorefrontClient } from "../api/http"
-import { updateLineItem, type Cart, type CartLineItem } from "../api/carts"
+import type { Cart, CartLineItem } from "../api/carts"
 import { Price } from "../lib/price"
-import { isProductLine } from "../lib/cart-helpers"
-import { cn } from "../lib/utils"
 import { variantCaption } from "../lib/variant-caption"
 import { useCheckoutLabels } from "./context"
 import { DiscountSection } from "./discount-section"
 import { GiftCardSection } from "./gift-card-section"
+import { checkoutTotals, isCompanyOrder } from "./summary-math"
 
 /**
  * OrderSummary — the right column of the checkout: scrollable list of
@@ -31,8 +30,10 @@ import { GiftCardSection } from "./gift-card-section"
  *    UNDER the (unchanged) total — tender never moves totals
  *    (docs/storefront/gift-cards.md). `GiftCardSection` mounts next to
  *    `DiscountSection`.
- *  - Line rows call `carts.updateLineItem` through the caller-supplied
- *    `client`; every mutation hands the decorated cart to `onCartChange`.
+ *  - **Line rows do not write.** The summary states the order; it cannot
+ *    change it (Alexander, 2026-09-18: a checkout is a checkout). The promo
+ *    and gift-card doors stay, because a code is part of paying, and each
+ *    still hands the decorated cart to `onCartChange`.
  *  - The flat `CheckoutLineItem` row (source: checkout-line-item.tsx,
  *    outside this batch's pre-declared file list) is ported INTO this file
  *    as the summary's row renderer and re-exported from the family barrel.
@@ -47,97 +48,35 @@ import { GiftCardSection } from "./gift-card-section"
  * LineItemCard (which is itself a card), this component is borderless:
  * rows sit on the parent card's surface with parent-provided dividers.
  *
- * Checkout is master-level: customers cannot remove items from the
- * order summary. Removal happens in the cart drawer only — the qty
- * pill here allows adjustment down to 1, not zero.
+ * **A CHECKOUT IS A CHECKOUT: the order cannot be edited from inside it**
+ * (Alexander, 2026-09-18). The row carried a quantity stepper, ported from
+ * the platform this kit came from, and it is gone: the cart is changed in
+ * the cart, and this column states what is being bought. A shopper who
+ * wants a different quantity goes back to the cart and returns, with
+ * everything they typed still in the form.
  *
- * Ported from `@1click/ui/src/checkout/checkout-line-item.tsx` (v2.3.1);
- * lucide-react's Minus/Plus icons are inlined as SVGs so the checkout
- * family carries no icon-kit dependency (mirrors lib/payment-constants'
- * no-icons rule). `variant.title` → the flat `variant_title` column.
+ * The quantity stays VISIBLE, as a count on the picture rather than a
+ * control, because a shopper about to pay must see what they are paying
+ * for. Nothing here calls the cart's write endpoints any more.
+ *
+ * Ported from `@1click/ui/src/checkout/checkout-line-item.tsx` (v2.3.1).
+ * `variant.title` → the flat `variant_title` column.
  */
 export function CheckoutLineItem({
-  client,
-  cartId,
   item,
   currencyCode,
-  onCartChange,
 }: {
-  client: StorefrontClient
-  cartId: string
   item: CartLineItem
   currencyCode: string
+  /** @deprecated Unused: the checkout summary no longer writes. Accepted so
+   * a store passing the old props keeps compiling; remove them at leisure. */
+  client?: StorefrontClient
+  /** @deprecated Unused — see `client`. */
+  cartId?: string
+  /** @deprecated Unused — see `client`. */
   onCartChange?: (cart: Cart) => void
 }) {
   const labels = useCheckoutLabels()
-  const [updating, setUpdating] = useState(false)
-
-  const handleQty = async (qty: number) => {
-    if (qty < 1) return
-    setUpdating(true)
-    try {
-      const { cart } = await updateLineItem(client, cartId, item.id, {
-        quantity: qty,
-      })
-      onCartChange?.(cart)
-    } catch {
-      // e.g. insufficient_inventory — the row snaps back to server truth
-      // on the next cart render.
-    } finally {
-      setUpdating(false)
-    }
-  }
-
-  // `self-start`: in the desktop column the pill is a flex item, and a flex
-  // item stretches to the column's width unless told otherwise. Without it
-  // the border ran the full width of the row with the controls huddled at
-  // the left (evoo checkout, 2026-09-14).
-  const qtyPill = (
-    <div className="inline-flex self-start items-center rounded-[2px] border border-border bg-card">
-      <button
-        type="button"
-        onClick={() => handleQty(item.quantity - 1)}
-        disabled={item.quantity <= 1 || updating}
-        aria-label={labels.qty}
-        className="w-8 h-8 flex items-center justify-center text-foreground hover:bg-muted disabled:opacity-30 disabled:cursor-not-allowed"
-      >
-        <svg
-          className="w-3.5 h-3.5"
-          fill="none"
-          viewBox="0 0 24 24"
-          stroke="currentColor"
-          strokeWidth={2.25}
-        >
-          <path strokeLinecap="round" strokeLinejoin="round" d="M5 12h14" />
-        </svg>
-      </button>
-      <span className="min-w-[1.75rem] px-1 text-center text-xs font-semibold tabular-nums">
-        {item.quantity}
-      </span>
-      <button
-        type="button"
-        onClick={() => handleQty(item.quantity + 1)}
-        disabled={updating}
-        aria-label={labels.qty}
-        className="w-8 h-8 flex items-center justify-center text-foreground hover:bg-muted disabled:opacity-30 disabled:cursor-not-allowed"
-      >
-        <svg
-          className="w-3.5 h-3.5"
-          fill="none"
-          viewBox="0 0 24 24"
-          stroke="currentColor"
-          strokeWidth={2.25}
-        >
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            d="M12 5v14m-7-7h14"
-          />
-        </svg>
-      </button>
-    </div>
-  )
-
   const caption = variantCaption(item.variant_title)
   const titleBlock = (
     <div className="min-w-0">
@@ -151,12 +90,7 @@ export function CheckoutLineItem({
   )
 
   return (
-    <div
-      className={cn(
-        "relative flex gap-4 transition-opacity",
-        updating && "opacity-40 pointer-events-none"
-      )}
-    >
+    <div className="relative flex gap-4">
       <div className="relative w-16 h-16 rounded-xl overflow-hidden flex-shrink-0 bg-muted border border-border">
         {item.thumbnail ? (
           // eslint-disable-next-line @next/next/no-img-element
@@ -166,35 +100,35 @@ export function CheckoutLineItem({
             className="w-full h-full object-cover"
           />
         ) : null}
+        {/* How many, on the picture: the count a locked summary states
+            instead of offering. Hidden at one, where it says nothing. */}
+        {item.quantity > 1 && (
+          <span
+            aria-label={labels.qty}
+            className="absolute -top-1.5 -right-1.5 min-w-[1.25rem] h-5 px-1 rounded-full bg-foreground text-card text-[11px] font-semibold flex items-center justify-center tabular-nums"
+          >
+            {item.quantity}
+          </span>
+        )}
       </div>
 
-      {/* DESKTOP layout —
-          row 1: title (left)  ·  price right-aligned, baseline of title line 1
-          row 2: qty pill (left) */}
-      <div className="hidden sm:flex flex-1 min-w-0 flex-col gap-2.5">
-        <div className="flex items-baseline justify-between gap-3">
-          {titleBlock}
-          <Price
-            amount={item.total ?? 0}
-            currencyCode={currencyCode}
-            className="text-sm font-bold text-foreground text-right flex-shrink-0"
-          />
-        </div>
-        {qtyPill}
-      </div>
-
-      {/* MOBILE layout — title takes full content width, qty+price share
-          the row underneath. */}
-      <div className="sm:hidden flex-1 min-w-0 flex flex-col gap-2">
+      <div className="flex flex-1 min-w-0 items-baseline justify-between gap-3">
         {titleBlock}
-        <div className="flex items-center justify-between gap-3">
-          {qtyPill}
+        {/* Never €0.00 on a line that costs nothing. A gift a promotion
+            added, or a line a discount took to zero, reads as a pricing
+            fault at the moment of paying, and the cart drawer already says
+            the word (Alenika's rule, ported 2026-09-18). */}
+        {(item.total ?? 0) <= 0 ? (
+          <span className="text-xs font-bold text-success text-right flex-shrink-0 uppercase">
+            {labels.lineFree}
+          </span>
+        ) : (
           <Price
             amount={item.total ?? 0}
             currencyCode={currencyCode}
-            className="text-sm font-bold text-foreground text-right"
+            className="text-sm font-bold text-foreground text-right flex-shrink-0"
           />
-        </div>
+        )}
       </div>
     </div>
   )
@@ -258,58 +192,26 @@ export function OrderSummary({
 }: OrderSummaryProps) {
   const labels = useCheckoutLabels()
 
-  // Product rows only. Cartbase's COD fee is cart-level decoration (never a
-  // line item), so this filter is defensive — it also hides any
-  // metadata-flagged fee line a legacy/ported cart might still carry.
-  const allItems = cart.items ?? []
-  const productItems = useMemo(
-    () => allItems.filter(isProductLine),
-    [allItems]
-  )
-  const itemCount = productItems.reduce((s, i) => s + i.quantity, 0)
-
-  const shippingCost =
-    optimisticShippingCost !== null ? optimisticShippingCost : cart.shipping_total
-  const shippingKnown = shippingCost !== null && shippingCost !== undefined
-
-  // Effective method fee: optimistic prediction wins until the cart
-  // catches up. Three states (null / 0 / positive). Server truth is
-  // `cart.payment_method_fee_total` (folded into cart.total while a live
-  // method session exists — docs/storefront/checkout.md).
+  // Every printed number comes from `checkoutTotals`, the same function the
+  // two mobile bars call, so a shopper cannot be shown one total at the top
+  // of a phone and another one here (summary-math.ts). It filters to product
+  // rows, sorts newest first, applies the optimistic overrides and reads the
+  // method fee from the cart's own decoration.
+  const {
+    productItems,
+    itemCount,
+    productSubtotal,
+    shippingCost,
+    shippingKnown,
+    methodFeeAmount,
+    displayTotal,
+    giftCardTotal,
+    giftCardRemainder,
+  } = checkoutTotals({ cart, optimisticShippingCost, optimisticMethodFee })
+
+  // Server truth for the clear-the-override effects below: the prediction
+  // is dropped the moment the cart itself carries the same figure.
   const realMethodFeeAmount = cart.payment_method_fee_total ?? 0
-  const effectiveMethodFee =
-    optimisticMethodFee !== null && optimisticMethodFee !== undefined
-      ? optimisticMethodFee
-      : realMethodFeeAmount
-
-  const displayTotal = useMemo(() => {
-    let total = cart.total ?? 0
-    if (optimisticShippingCost !== null) {
-      total = total - (cart.shipping_total ?? 0) + optimisticShippingCost
-    }
-    if (optimisticMethodFee !== null && optimisticMethodFee !== undefined) {
-      total = total - realMethodFeeAmount + effectiveMethodFee
-    }
-    return total
-  }, [
-    cart.total,
-    cart.shipping_total,
-    optimisticShippingCost,
-    optimisticMethodFee,
-    effectiveMethodFee,
-    realMethodFeeAmount,
-  ])
-
-  // Subtotal: Cartbase's `item_total` is products-only (the fee is not a
-  // line item), so no fee subtraction is needed — direct server truth.
-  const productSubtotal = cart.item_total ?? 0
-
-  const methodFeeAmount = effectiveMethodFee
-
-  // Gift-card tender decoration — SERVER truth, rendered as-is. Totals
-  // never move; the tender rows sit under the total.
-  const giftCardTotal = cart.gift_card_total ?? 0
-  const giftCardRemainder = cart.gift_card_remainder ?? 0
 
   // Clear optimistic override once server cart reflects the new shipping cost
   useEffect(() => {
@@ -344,20 +246,14 @@ export function OrderSummary({
         {/* Items section — bg-muted accent so the items zone reads as a
             distinct surface from the totals section below. */}
         <div className="bg-muted px-5 sm:px-6 py-2 divide-y divide-border border-b border-border">
-          {productItems
-            .slice()
-            .sort((a, b) => ((a.created_at ?? "") > (b.created_at ?? "") ? -1 : 1))
-            .map((item) => (
-              <div key={item.id} className="py-5 first:pt-3 last:pb-3">
-                <CheckoutLineItem
-                  client={client}
-                  cartId={cart.id}
-                  item={item}
-                  currencyCode={cart.currency_code}
-                  onCartChange={onCartChange}
-                />
-              </div>
-            ))}
+          {productItems.map((item) => (
+            <div key={item.id} className="py-5 first:pt-3 last:pb-3">
+              <CheckoutLineItem
+                item={item}
+                currencyCode={cart.currency_code}
+              />
+            </div>
+          ))}
         </div>
 
         <div className="px-5 sm:px-6 mt-4 space-y-3">
@@ -434,6 +330,15 @@ export function OrderSummary({
             </div>
           )}
 
+          {/* THE VAT ROW IS FOR A COMPANY (Alexander, 2026-09-18). A
+              consumer sees the price they pay: the VAT is already inside it,
+              there is nothing they can do about it, and a row for it is
+              noise where they are deciding to buy. It used to print whatever
+              the cart said, which before an address was a flat 0.00 beside
+              prices containing 20% — false, not merely useless. A company
+              buyer reclaims the VAT and must see it, so for them it prints,
+              and only when the figure is actually known. */}
+          {isCompanyOrder(cart) && (cart.tax_total ?? 0) > 0 && (
           <div className="flex justify-between text-sm">
             {/* The tax row's NAME always shows: it names the number beside
                 it. The explanation only shows if the store wrote one, because
@@ -469,6 +374,7 @@ export function OrderSummary({
               className="font-medium text-foreground"
             />
           </div>
+          )}
         </div>
 
         <div className="mx-5 sm:mx-6 mt-4 pt-4 border-t border-border">

package/src/checkout/payment-button.tsx

@@ -62,6 +62,14 @@ type PaymentButtonProps = {
   /** Structural cart — only `id`, `total`, `currency_code` are read. */
   cart: { id: string; total?: number | null; currency_code: string }
   paymentTab: "card" | "cod"
+  /**
+   * Nothing is left to pay (a promotion or gift cards cover the whole
+   * total). The button reads "Complete order" and carries no amount, and
+   * it never waits on Stripe: no card form was mounted, so waiting for one
+   * to be complete would leave the shopper with a button that can never
+   * enable.
+   */
+  nothingToPay?: boolean
   notReady: boolean
   performBuyClick: (stripeBundle?: BuyClickStripeBundle) => Promise<void>
   /**
@@ -170,6 +178,7 @@ function OrderButton({
 export function PaymentButton({
   cart,
   paymentTab,
+  nothingToPay = false,
   notReady,
   performBuyClick,
   paymentElementComplete = true,
@@ -197,6 +206,11 @@ export function PaymentButton({
   const [submitting, setSubmitting] = useState(false)
   const [errorMessage, setErrorMessage] = useState<string | null>(null)
 
+  // A cart with nothing left to pay takes no card path, whichever tab was
+  // selected before the total fell to zero: prepare mints no session and
+  // the cart completes on what already covers it.
+  const isCardPath = paymentTab === "card" && !nothingToPay
+
   // ── Processing-state cycling messages ───────────────────────────────
   // While `submitting` is true, cycle through a short list of messages
   // narrating what's actually happening server-side. Loops back to 0
@@ -214,17 +228,19 @@ export function PaymentButton({
       setMessageIndex(0)
       return
     }
-    const messages =
-      paymentTab === "card" ? labels.processingCard : labels.processingCod
+    const messages = isCardPath ? labels.processingCard : labels.processingCod
     if (!messages || messages.length === 0) return
     const id = setInterval(() => {
       setMessageIndex((i) => (i + 1) % messages.length)
     }, PROCESSING_MESSAGE_INTERVAL_MS)
     return () => clearInterval(id)
-  }, [submitting, paymentTab, labels.processingCard, labels.processingCod])
+  }, [submitting, isCardPath, labels.processingCard, labels.processingCod])
 
-  const processingMessages =
-    paymentTab === "card" ? labels.processingCard : labels.processingCod
+  // No bank is being talked to when there is nothing to pay, so the
+  // narration is the one that does not mention one.
+  const processingMessages = isCardPath
+    ? labels.processingCard
+    : labels.processingCod
   const currentProcessingMessage =
     submitting && processingMessages?.length
       ? processingMessages[messageIndex % processingMessages.length]
@@ -236,7 +252,6 @@ export function PaymentButton({
   // flips synchronously and blocks the second click cold.
   const inFlightRef = useRef(false)
 
-  const isCardPath = paymentTab === "card"
   const cardReady = !isCardPath || (stripeReady && !!stripe && !!elements)
   const cardComplete = !isCardPath || paymentElementComplete
 
@@ -334,10 +349,12 @@ export function PaymentButton({
         onClick={handleClick}
         disabled={disabled}
         loading={submitting}
-        total={total ?? cart.total ?? undefined}
+        // No amount beside a Complete order button: "· 0.00" is noise on
+        // the one order where the number carries no meaning.
+        total={nothingToPay ? undefined : total ?? cart.total ?? undefined}
         currencyCode={cart.currency_code}
         testId={dataTestId}
-        label={labels.placeOrder}
+        label={nothingToPay ? labels.completeOrder : labels.placeOrder}
       />
       {/*
         Cycling processing message. Fixed-height wrapper prevents layout

package/src/checkout/payment-method-list.tsx

@@ -72,13 +72,29 @@ type CheckoutPaymentMethodListProps = {
    * instead of reading a greyed button as broken. Only rendered while
    * `buyButtonNotReady`. Omit / null to show no hint. */
   buyButtonNotReadyReason?: "address" | "delivery" | null
-  /** Gate the whole payment section behind delivery-readiness (the
-   * classic flow: payment stays dimmed + hidden until a shipping method
-   * is chosen). Default `true` keeps that behavior. Pass `false` to keep
-   * the payment section ALWAYS visible + interactive (Shopify-style
-   * "everything on screen"); the Buy button still can't fire because
-   * `buyButtonNotReady` gates it independently. */
+  /**
+   * Gate the whole payment section behind delivery-readiness: it stays
+   * dimmed and unusable until a courier is chosen.
+   *
+   * DEFAULT `false` since 2026-09-18 (Alexander, from Alenika's checkout):
+   * everything a shopper has to do is on screen from arrival, and the Buy
+   * button carries the gate on its own, saying which step is missing. A
+   * dimmed block teaches nothing and reads as broken. Pass `true` for the
+   * older flow.
+   */
   gatePaymentUntilDelivery?: boolean
+  /**
+   * The order asks the shopper for no money: a promotion covered it
+   * entirely, or gift cards cover the whole total. Pass the hook's
+   * `nothingToPay`.
+   *
+   * There is no payment to choose, so no tender is offered and no card
+   * form is mounted; the section says the order is covered and the button
+   * becomes Complete order. Before this the payment block still ruled a
+   * zero-total checkout, so a shopper who owed nothing was shown a card
+   * field and could not finish without filling it in.
+   */
+  nothingToPay?: boolean
   /** Optional content rendered directly above the Place Order button. */
   beforePaymentButton?: React.ReactNode
   /** Display total in main currency units. Forwarded to `PaymentButton`.
@@ -111,7 +127,8 @@ export function CheckoutPaymentMethodList({
   performBuyClick,
   buyButtonNotReady,
   buyButtonNotReadyReason,
-  gatePaymentUntilDelivery = true,
+  gatePaymentUntilDelivery = false,
+  nothingToPay = false,
   beforePaymentButton,
   total,
   logError,
@@ -176,7 +193,16 @@ export function CheckoutPaymentMethodList({
     logError?.("elements_load_error", message, {})
   }
 
+  // What a layout puts between the payment choice and the Buy button: on a
+  // phone the order overview and the code field. It is rendered ONCE, and
+  // never inside the dimmed block, because a shopper who has not picked a
+  // courier yet must still be able to open their order and type a code.
+  const slot = beforePaymentButton ? (
+    <div className="mt-5">{beforePaymentButton}</div>
+  ) : null
+
   return (
+    <>
     <div
       className={cn(
         "mt-8 transition-opacity duration-300",
@@ -214,7 +240,16 @@ export function CheckoutPaymentMethodList({
         // whole point of moving away from PaymentWrapper-wraps-all.
         <StripeElementsScope passthrough>
           <div className="space-y-2">
-            {hasCard && (
+            {nothingToPay && (
+              // One line instead of a tender list. The shopper owes
+              // nothing, so every radio here would be a question with no
+              // answer and the card form a demand for details that will
+              // never be charged.
+              <div className="p-4 bg-muted rounded-lg border border-border">
+                <p className="text-sm text-foreground">{labels.nothingToPay}</p>
+              </div>
+            )}
+            {!nothingToPay && hasCard && (
               <div
                 className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
@@ -293,7 +328,7 @@ export function CheckoutPaymentMethodList({
               </div>
             )}
 
-            {hasCod && (
+            {!nothingToPay && hasCod && (
               <div
                 className={cn(
                   "rounded-lg border overflow-hidden transition-colors duration-150",
@@ -334,7 +369,7 @@ export function CheckoutPaymentMethodList({
               </div>
             )}
 
-            {extraTabs?.map((tab) => (
+            {!nothingToPay && extraTabs?.map((tab) => (
               <div
                 key={tab.id}
                 className={cn(
@@ -375,9 +410,7 @@ export function CheckoutPaymentMethodList({
             data-testid="payment-error-message"
           />
 
-          {beforePaymentButton && (
-            <div className="mt-5">{beforePaymentButton}</div>
-          )}
+          {slot}
 
           {!extraTab && buyButtonNotReady && buyButtonNotReadyReason && (
             <div className="mt-4 flex items-center justify-center gap-1.5 text-muted-foreground">
@@ -407,6 +440,7 @@ export function CheckoutPaymentMethodList({
               <PaymentButton
                 cart={cart}
                 paymentTab={paymentTab}
+                nothingToPay={nothingToPay}
                 notReady={buyButtonNotReady}
                 performBuyClick={performBuyClick}
                 paymentElementComplete={
@@ -421,5 +455,9 @@ export function CheckoutPaymentMethodList({
         </StripeElementsScope>
       )}
     </div>
+    {/* Gated: the block above is the notice, dimmed, so the slot stands
+        below it, live, instead of being greyed out with the payment cards. */}
+    {paymentGated && slot}
+    </>
   )
 }

package/src/checkout/payment-wrapper.tsx

@@ -1,9 +1,10 @@
 "use client"
 
-import type { Appearance, StripeElementsOptions } from "@stripe/stripe-js"
+import type { Appearance, Stripe, StripeElementsOptions } from "@stripe/stripe-js"
 import { loadStripe } from "@stripe/stripe-js"
 import type { ReactNode } from "react"
 
+import { envStripeAccountId, envStripeKey } from "../lib/stripe-env"
 import { StripeScopeProvider } from "./stripe-wrapper"
 
 /**
@@ -29,21 +30,43 @@ import { StripeScopeProvider } from "./stripe-wrapper"
  *     <CheckoutClient ... />
  *   </PaymentWrapper>
  *
- * Environment variables (read at module load time):
- *   - NEXT_PUBLIC_STRIPE_KEY
- *   - NEXT_PUBLIC_STRIPE_ACCOUNT_ID (optional, connect accounts)
+ * WHERE THE KEY COMES FROM (2026-09-18). The store tells us. The card entry
+ * of `GET /api/store/payment-providers` carries `publishable_key` and, for a
+ * Connect-linked store, `account_id`; `CheckoutClient` reads them off that
+ * entry and passes them here. That is the only correct source: under Stripe
+ * Connect the browser loads CARTBASE's publishable key and names the
+ * merchant's account, so neither value is something a merchant could know
+ * about their own shop.
+ *
+ * Until this release the pair came from `NEXT_PUBLIC_STRIPE_KEY` and
+ * `NEXT_PUBLIC_STRIPE_ACCOUNT_ID`, two env values every storefront had to
+ * set by hand. A merchant who connected Stripe in the admin and set no env
+ * got a checkout with no card option and no reason given. The env pair still
+ * works as a fallback, so a store that set it keeps running, and it is the
+ * escape hatch for a storefront pointed at a Stripe account the platform
+ * does not hold.
  */
 
-const stripeKey = process.env.NEXT_PUBLIC_STRIPE_KEY
-
-const stripeAccountId = process.env.NEXT_PUBLIC_STRIPE_ACCOUNT_ID
+/**
+ * One Stripe.js promise per key + account pair, for the life of the tab.
+ * `loadStripe` injects a script and must not run per render; memoising on
+ * the pair also means the Elements iframe survives re-renders, which is the
+ * whole point of the deferred-intent mount.
+ */
+const stripeCache = new Map<string, Promise<Stripe | null>>()
 
-const stripePromise = stripeKey
-  ? loadStripe(
-      stripeKey,
-      stripeAccountId ? { stripeAccount: stripeAccountId } : undefined
-    )
-  : null
+function stripeFor(
+  key: string | undefined,
+  account: string | undefined
+): Promise<Stripe | null> | null {
+  if (!key) return null
+  const cacheKey = `${key}::${account ?? ""}`
+  const hit = stripeCache.get(cacheKey)
+  if (hit) return hit
+  const promise = loadStripe(key, account ? { stripeAccount: account } : undefined)
+  stripeCache.set(cacheKey, promise)
+  return promise
+}
 
 type PaymentWrapperProps = {
   /** The decorated cart — only `currency_code` is read. */
@@ -68,6 +91,16 @@ type PaymentWrapperProps = {
    * font — the iframe cannot see the parent document's loaded fonts.
    */
   fonts?: StripeElementsOptions["fonts"]
+  /**
+   * The store's own card credentials, off the `pp_stripe` entry of
+   * `GET /api/store/payment-providers`. `CheckoutClient` passes them for
+   * you; a store mounting this wrapper by hand reads them from the same
+   * listing it already fetches for the checkout. Omitted falls back to
+   * `NEXT_PUBLIC_STRIPE_KEY` / `NEXT_PUBLIC_STRIPE_ACCOUNT_ID`.
+   */
+  publishableKey?: string
+  /** The merchant's linked Stripe account (`acct_…`) under Connect. */
+  stripeAccountId?: string
   children: ReactNode
 }
 
@@ -76,8 +109,19 @@ export function PaymentWrapper({
   amount,
   appearance,
   fonts,
+  publishableKey,
+  stripeAccountId,
   children,
 }: PaymentWrapperProps) {
+  // The store's answer wins; env is the fallback for a storefront that
+  // supplies its own Stripe. Taking the key and the account from the same
+  // source matters: a platform key paired with no account charges the
+  // platform, and a merchant account under the wrong key is rejected.
+  const fromStore = !!publishableKey
+  const stripePromise = fromStore
+    ? stripeFor(publishableKey, stripeAccountId)
+    : stripeFor(envStripeKey, envStripeAccountId)
+
   // "Ready" simply means: Stripe.js loadable. We no longer wait for a
   // backend payment_session — deferred-intent mode mounts straight away.
   const ready = !!stripePromise