@12-apps/payments-frontend 3.21.3 → 3.22.0

package/src/components/checkout/checkout-flow.tsx

@@ -1,8 +1,10 @@
 import { Box } from "@mui/material";
 import { useMemo, type JSX, type ReactNode } from "react";
 
+import type { CheckoutBasketIdentity } from "./basket";
 import { buyerFieldsFor } from "./buyer-fields";
-import { DadosStep, EmptyCart, PaymentStep } from "./checkout-steps";
+import { EmptyCart, PaymentStep } from "./checkout-steps";
+import { DadosStep } from "./dados-step";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
@@ -29,6 +31,18 @@ export interface CheckoutCartView {
   totalItems: number;
   /** Host-rendered discount itemization under the pay-bar total (FUT-246). */
   discountLines?: ReactNode;
+  /**
+   * WHICH basket this is, so a payment raised from another one cannot resume
+   * itself over it (FUT-1213).
+   *
+   * Optional, and absent means the pre-1213 behaviour — a parked payment
+   * resumes on whatever checkout mounts next, which is what shipped and what
+   * this ticket exists to bound. A host supplies it by calling
+   * `basketSignature(lines)` on its own cart and passing `ready: false` while
+   * that cart is still loading; see `./basket.ts` for why the identity is the
+   * LINES and not the cart's id.
+   */
+  identity?: CheckoutBasketIdentity;
 }
 
 /**
@@ -84,6 +98,16 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   components?: Partial<CheckoutComponents>;
 }
 
+/**
+ * Whether the host's cart has actually answered yet.
+ *
+ * `true` for every host that wires no identity, which is what it meant before
+ * there was one to wire.
+ */
+function cartLoaded(cart: CheckoutCartView): boolean {
+  return cart.identity?.ready !== false;
+}
+
 /** The pay-bar total override when settling a settlement (else the cart's own totals). */
 function settlementTotalOverride(
   settlement: SettlementCheckout | null | undefined,
@@ -179,6 +203,87 @@ function StatusStep({
       // so nothing is being polled here.
       awaitingError={c.resumeError}
       onCheckAgain={c.resumeCheckAgain}
+      // The buyer's own way out of a hosted wait with no terminal state
+      // (FUT-1146). Absent — and so unrendered — until the resumed leg has one
+      // to offer, which is every checkout that never left this tab.
+      onNotPaid={c.resumeRelease}
+      releasing={c.resumeReleasing}
+      // WHY a card was refused, when the server said (FUT-1145). Read on
+      // FAILED only, where it picks the sentence and decides whether a retry
+      // could work at all.
+      decline={c.decline}
+    />
+  );
+}
+
+/**
+ * Nothing to check out — and the cart has ANSWERED, which is the half FUT-1213
+ * added.
+ *
+ * A settlement pays already-sent items, so the cart is legitimately empty
+ * there. The guard cannot key on the Dados step either: skipping it (FUT-465)
+ * makes Pagamento the first screen. And it holds until an order exists — once
+ * one does, its lines are snapshotted server-side and the cart no longer speaks
+ * for it.
+ *
+ * A cart still being FETCHED is empty in exactly the way a real one is not, so
+ * a host that wires `identity` gets this screen when its cart is empty rather
+ * than when it is late — which is also the moment the resume decision waits for.
+ */
+function nothingToPayFor(
+  settlement: SettlementCheckout | null | undefined,
+  cart: CheckoutCartView,
+  c: ReturnType<typeof useCheckoutController>,
+): boolean {
+  if (settlement || !cart.empty || !cartLoaded(cart)) return false;
+  return !c.order && c.step !== "status";
+}
+
+/** Step 2, with the controller's facts and the host's money mapped onto it. */
+function PagamentoStep({
+  c,
+  cart,
+  settlement,
+  providerConfig,
+  tenantSlug,
+  validateApplePayMerchant,
+}: {
+  c: ReturnType<typeof useCheckoutController>;
+  cart: CheckoutCartView;
+  settlement: SettlementCheckout | null | undefined;
+  providerConfig: CheckoutProviderConfig | null | undefined;
+  tenantSlug: string | undefined;
+  validateApplePayMerchant: ((validationURL: string) => Promise<unknown>) | undefined;
+}): JSX.Element {
+  return (
+    <PaymentStep
+      method={c.method}
+      onMethodChange={c.setMethod}
+      order={c.order}
+      buyer={c.buyer}
+      creating={c.creating}
+      createError={c.createError}
+      errorField={c.errorField}
+      errorCode={c.errorCode}
+      onGenerate={(chosen) => void c.startPayment(chosen)}
+      onUseEmail={c.payWithEmail}
+      // Set only for a skipped-Dados flow (the controller decides); the payer
+      // block hides itself when it is absent.
+      onEditBuyer={c.editBuyer}
+      providerConfig={providerConfig}
+      tenantSlug={tenantSlug}
+      // The amount, on the step that asks for it (FUT-1179).
+      cartTotals={cart}
+      totalOverride={settlementTotalOverride(settlement)}
+      discountLines={cart.discountLines}
+      // Retrying a refused card: the saved card that failed is not chosen for
+      // them again (FUT-1145).
+      freshInstrument={c.freshInstrument}
+      // The card path parks an order of its own for a 3-D Secure challenge, so
+      // it needs the same basket the flow was mounted for (FUT-1213).
+      basket={cart.identity}
+      validateApplePayMerchant={validateApplePayMerchant}
+      onResolved={c.handleResolved}
     />
   );
 }
@@ -190,7 +295,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   // any chain member may need rather than re-opening after the choice. A chain
   // that declares nothing degrades to CPF-required, never to "ask nothing".
   const buyerFields = useMemo(() => buyerFieldsFor(providerConfig?.chain, null), [providerConfig]);
-  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields, tenantSlug);
+  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields, tenantSlug, cart.identity);
   const armed = useOneClick({ requested: oneClick, config: providerConfig, taxIdOnFile, step: c.step, method: c.method, setMethod: c.setMethod });
 
   // A settlement settlement pays already-sent kitchen items — the cart is
@@ -200,7 +305,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   // Pagamento the first screen, so an empty cart would otherwise reach the
   // method picker. It holds until an order exists — once one does, its lines are
   // snapshotted server-side and the cart no longer speaks for it.
-  if (!settlement && cart.empty && !c.order && c.step !== "status") {
+  if (nothingToPayFor(settlement, cart, c)) {
     return <EmptyCart copy={copy.emptyCart} onBack={c.goToMenu} />;
   }
 
@@ -229,24 +334,13 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
 
       {c.step === "payment" ? (
         <OneClickProvider armed={armed}>
-          <PaymentStep
-            method={c.method}
-            onMethodChange={c.setMethod}
-            order={c.order}
-            buyer={c.buyer}
-            creating={c.creating}
-            createError={c.createError}
-            errorField={c.errorField}
-            errorCode={c.errorCode}
-            onGenerate={(chosen) => void c.startPayment(chosen)}
-            onUseEmail={c.payWithEmail}
-            // Set only for a skipped-Dados flow (the controller decides); the
-            // payer block hides itself when it is absent.
-            onEditBuyer={c.editBuyer}
+          <PagamentoStep
+            c={c}
+            cart={cart}
+            settlement={settlement}
             providerConfig={providerConfig}
             tenantSlug={tenantSlug}
             validateApplePayMerchant={validateApplePayMerchant}
-            onResolved={c.handleResolved}
           />
         </OneClickProvider>
       ) : null}

package/src/components/checkout/checkout-steps.tsx

@@ -1,9 +1,9 @@
 import { Box } from "@mui/material";
 import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
-import { BuyerInfoForm } from "./buyer-info-form";
+import type { CheckoutBasketIdentity } from "./basket";
+import { displayTotals, PayBarTotal } from "./checkout-totals";
 import { useCheckoutCopy } from "./copy-context";
-import { LockOutlinedIcon } from "./icons";
 import { useMethodChoice } from "./method-choice";
 import { MethodPicker } from "./method-picker";
 import { PaymentErrorPanel } from "./payment-error-panel";
@@ -12,13 +12,12 @@ import { resolveCheckoutScreen } from "./providers/registry";
 import type {
   BuyerField,
   BuyerInfo,
-  CheckoutCustomerField,
   CheckoutOrder,
   CheckoutProviderConfig,
-  OrderStatus,
+  OnCheckoutResolved,
   PaymentMethod,
 } from "./types";
-import type { DadosStepCopy, EmptyCartCopy } from "./view-copy";
+import type { EmptyCartCopy } from "./view-copy";
 import { useCheckoutComponents } from "./ui";
 
 /**
@@ -70,6 +69,8 @@ function PaymentBody({
   onStart,
   creating,
   pollIntervalMs,
+  freshInstrument,
+  basket,
   validateApplePayMerchant,
 }: {
   order: CheckoutOrder | null;
@@ -77,11 +78,13 @@ function PaymentBody({
   providerConfig: CheckoutProviderConfig | null;
   method: PaymentMethod | null;
   tenantSlug?: string;
-  onResolved: (status: OrderStatus) => void;
+  onResolved: OnCheckoutResolved;
   /** Set only when the shell hid its picker — see {@link PaymentStep}. */
   onStart?: () => void;
   creating: boolean;
   pollIntervalMs?: number;
+  freshInstrument?: boolean;
+  basket?: CheckoutBasketIdentity;
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
 }): JSX.Element | null {
   const Screen = resolveCheckoutScreen(providerConfig?.chain?.[0]?.checkoutScreen);
@@ -96,6 +99,8 @@ function PaymentBody({
       onStart={onStart}
       creating={creating}
       pollIntervalMs={pollIntervalMs}
+      freshInstrument={freshInstrument}
+      basket={basket}
       validateApplePayMerchant={validateApplePayMerchant}
     />
   );
@@ -116,162 +121,45 @@ export function EmptyCart({ copy, onBack }: { copy: EmptyCartCopy; onBack: () =>
   );
 }
 
-/**
- * The totals shown on the pay bar: the settled balance's when settling a settlement
- * one, otherwise the cart's own — both supplied by the host, which
- * is the only side that knows either.
- */
-function displayTotals(
-  override: { label: string; items: number } | undefined,
-  cart: { totalLabel: string; totalItems: number },
-): { label: string; items: number } {
-  return { label: override?.label ?? cart.totalLabel, items: override?.items ?? cart.totalItems };
-}
-
-/** The pay bar's money column: item count, grand total, host discount lines. */
-function PayBarTotal({
-  totalLabel,
-  totalItems,
-  children,
-}: {
-  totalLabel: string;
-  totalItems: number;
-  children?: ReactNode;
-}): JSX.Element {
-  const { Text } = useCheckoutComponents();
-  return (
-    <Box sx={{ display: "flex", flexDirection: "column", minWidth: 0 }}>
-      <Text variant="caption" size="xs" color="secondary" as="span">
-        Total · {totalItems} {totalItems === 1 ? "item" : "itens"}
-      </Text>
-      <Text variant="heading" size="md" weight="bold" color="primary" as="span" data-testid="pay-bar-total">
-        {totalLabel}
-      </Text>
-      {children}
-    </Box>
-  );
+/** What the step knows about the amount: the charge's, the balance's, the cart's. */
+interface StepMoney {
+  order: CheckoutOrder | null;
+  cartTotals?: { totalLabel: string; totalItems: number };
+  totalOverride?: { label: string; items: number };
+  discountLines?: ReactNode;
 }
 
 /**
- * Step 1 "Dados" — the buyer's register info (CPF plus optional name/email/
- * phone; contact pre-filled from the saved buyer profile). NO payment method
- * here (that's step 2); nav lives in the slim checkout header. "Continuar"
- * (sticky, with the live total) validates the CPF and advances to "Pagamento"
- * — no charge yet.
- */
-export function DadosStep({
-  copy,
-  buyer,
-  onBuyerChange,
-  saveProfile,
-  onSaveProfileChange,
-  createError,
-  errorField,
-  onContinue,
-  cartTotals,
-  buyerFields,
-  discountLines,
-  totalOverride,
-}: {
-  /** The step's own sentences — the HOST's words (see `./view-copy`). */
-  copy: DadosStepCopy;
-  buyer: BuyerInfo;
-  onBuyerChange: (buyer: BuyerInfo) => void;
-  saveProfile: boolean;
-  onSaveProfileChange: (value: boolean) => void;
-  createError: string | null;
-  errorField: BuyerField | null;
-  onContinue: () => void;
-  /** The host cart's own totals — what the pay bar shows in cart mode. */
-  cartTotals: { totalLabel: string; totalItems: number };
-  /** What the store's chain declares it needs (FUT-595); absent ⇒ CPF-required. */
-  buyerFields?: readonly CheckoutCustomerField[];
-  /**
-   * The saving, itemized under the total the buyer is about to authorize
-   * (FUT-246) — RENDERED BY THE HOST from its cart (the storefront passes its
-   * cart footer's money block), never re-implemented here, so the two surfaces
-   * can never word the same discount differently.
+ * The Pagamento step's own money line (FUT-1179).
+ *
+ * THE RAISED ORDER'S TOTAL WINS, exactly as the confirmation screen's does
+ * (`statusTotalLabel`). Once a charge exists, that charge's amount is what is
+ * being taken — a repriced cart, or an order resumed from a parked entry, makes
+ * the cart's total a different number from the one about to leave the buyer's
+ * account. Showing the cart's number above a QR for the order's would be this
+ * ticket's own defect in a new place: an amount on screen that is not the
+ * amount being charged.
+ *
+ * The item COUNT stays the cart's — an order carries no line count, and the
+ * caption is a description of the basket rather than of the charge.
+ *
+ * Renders nothing at all when the host supplied no totals and no order — a step
+ * that would otherwise print "Total ·" with a blank beside it is worse than the
+ * silence this ticket is about. Every host mounting `CheckoutFlow` gets them;
+ * only a hand-composed step can be missing them.
  */
-  discountLines?: ReactNode;
-  /** Settling an open balance: totals come from the settlement, not the cart. */
-  totalOverride?: { label: string; items: number };
-}): JSX.Element {
-  const { Checkbox } = useCheckoutComponents();
-  const { label: totalLabel, items: totalItems } = displayTotals(totalOverride, cartTotals);
-
+function PaymentStepTotal({ money }: { money: StepMoney }): JSX.Element | null {
+  const { order, cartTotals, totalOverride, discountLines } = money;
+  if (!cartTotals && !totalOverride && !order) return null;
+  const { label, items } = displayTotals(totalOverride, cartTotals ?? { totalLabel: "", totalItems: 0 });
   return (
-    <>
-      <Box sx={{ display: "flex", flexDirection: "column", gap: 3, pb: { xs: createError ? 22 : 14, sm: createError ? 20 : 12 } }}>
-        <BuyerInfoForm
-          value={buyer}
-          onChange={onBuyerChange}
-          fields={buyerFields}
-          fieldError={errorField && createError ? { field: errorField, message: createError } : null}
-        />
-        <Checkbox
-          checked={saveProfile}
-          onChange={(_event, checked) => onSaveProfileChange(checked)}
-          label={copy.saveProfile}
-          data-testid="buyer-save-profile"
-        />
-      </Box>
-
-      <DadosPayBar
-        copy={copy}
-        totalLabel={totalLabel}
-        totalItems={totalItems}
-        createError={createError}
-        onContinue={onContinue}
-      >
+    <Box data-testid="payment-step-total" sx={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start", gap: 2 }}>
+      <PayBarTotal totalLabel={order?.totalLabel ?? label} totalItems={items}>
         {/* Suppressed while settling a balance: those totals come from the
             frozen ticket, not the cart. */}
         {totalOverride ? null : discountLines}
-      </DadosPayBar>
-    </>
-  );
-}
-
-/** The sticky "Continuar" bar: the refusal, the money, and the one action. */
-function DadosPayBar({
-  copy,
-  totalLabel,
-  totalItems,
-  createError,
-  onContinue,
-  children,
-}: {
-  copy: DadosStepCopy;
-  totalLabel: string;
-  totalItems: number;
-  createError: string | null;
-  onContinue: () => void;
-  children?: ReactNode;
-}): JSX.Element {
-  const { ActionBar, Alert, Button, Text } = useCheckoutComponents();
-  return (
-    <ActionBar dataTestId="checkout-pay-bar">
-      <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
-        {createError ? (
-          <Alert variant="danger" title={copy.cannotContinueTitle} description={createError} showIcon data-testid="checkout-error" />
-        ) : null}
-        <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
-          <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>{children}</PayBarTotal>
-          <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
-            <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
-              {copy.continueAction}
-            </Button>
-            {copy.secureNotice ? (
-              <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
-                <LockOutlinedIcon sx={{ fontSize: 13 }} />
-                <Text variant="caption" size="xs" color="secondary" as="span">
-                  {copy.secureNotice}
-                </Text>
-              </Box>
-            ) : null}
-          </Box>
-        </Box>
-      </Box>
-    </ActionBar>
+      </PayBarTotal>
+    </Box>
   );
 }
 
@@ -305,10 +193,39 @@ interface PaymentStepProps {
   providerConfig?: CheckoutProviderConfig | null;
   /** Scopes the saved-card list to the store being paid (host routing owns it). */
   tenantSlug?: string;
+  /**
+   * WHAT THE BUYER IS ABOUT TO PAY (FUT-1179) — the host cart's own totals, or
+   * the settlement's where one is being settled.
+   *
+   * The Pagamento step showed no amount at all before a method was chosen, and
+   * a store that finishes on the provider's page sent a buyer with a CPF on
+   * file straight out to that provider with NO total ever having been on
+   * screen: the flow opens on Pagamento, the hand-off screen owns the only
+   * button, and the amount lived exclusively on the Dados step they skipped.
+   * Asking for money without showing the amount is the one thing a checkout
+   * may not do.
+   *
+   * Optional so a host composing this step by hand is not broken by the
+   * addition; absent, the step renders as it did.
+   */
+  cartTotals?: { totalLabel: string; totalItems: number };
+  /** Settling an open balance: totals come from the settlement, not the cart. */
+  totalOverride?: { label: string; items: number };
+  /** The host's own rendered discount itemization, under the total (FUT-246). */
+  discountLines?: ReactNode;
   pollIntervalMs?: number;
+  /** Retrying a refused card — preselect no saved instrument (FUT-1145). */
+  freshInstrument?: boolean;
+  /**
+   * WHICH basket this checkout is for (FUT-1213) — passed down because the
+   * card path can park an order too: a 3-D Secure challenge is a hand-off, and
+   * one parked without a basket resumes over any basket at any store, which is
+   * this ticket's own bug on a sibling path.
+   */
+  basket?: CheckoutBasketIdentity;
   /** The host's Apple Pay merchant-validation port (FUT-472) — see the screen contract. */
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
-  onResolved: (status: OrderStatus) => void;
+  onResolved: OnCheckoutResolved;
 }
 
 /**
@@ -341,18 +258,28 @@ export function PaymentStep({
   onEditBuyer,
   providerConfig,
   tenantSlug,
+  cartTotals,
+  totalOverride,
+  discountLines,
   pollIntervalMs,
+  freshInstrument,
+  basket,
   validateApplePayMerchant,
   onResolved,
 }: PaymentStepProps): JSX.Element {
-  const { LoadingState } = useCheckoutComponents();
-  const screens = useCheckoutCopy().screens;
   const config = providerConfig ?? null;
   const choice = useMethodChoice(config, method, onMethodChange);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
+      {/* THE AMOUNT, before anything asks for it (FUT-1179). At the top rather
+          than in a sticky bar of its own: this step's actions belong to the
+          pane below it — the PIX code, the card form's own pay bar, the
+          hand-off button — and a second bar would put two "pay" controls on
+          one screen. */}
+      <PaymentStepTotal money={{ order, cartTotals, totalOverride, discountLines }} />
+
       {/* Self-hiding: renders only for a flow whose Dados step was skipped. */}
       <PayerSummary name={buyer.name} taxId={buyer.taxId} onEdit={onEditBuyer} />
 
@@ -375,26 +302,74 @@ export function PaymentStep({
         onStart={choice.onStart}
         creating={creating}
         pollIntervalMs={pollIntervalMs}
+        freshInstrument={freshInstrument}
+        basket={basket}
         validateApplePayMerchant={validateApplePayMerchant}
       />
 
-      {/* The shell's own busy spinner, SUPPRESSED for a hand-off screen: that
-          screen renders its own "Preparando o pagamento" while the charge is
-          raised, and two stacked spinners saying the same thing is what the
-          buyer actually saw. */}
-      {!order && creating && !choice.atProvider ? (
-        <LoadingState variant="spinner" size="md" message={screens.generatingPayment} dataTestId="payment-generating" />
-      ) : null}
-
-      {!order && method && createError ? (
-        <PaymentErrorPanel
-          message={createError}
-          emailFlagged={errorField === "email"}
-          code={errorCode}
-          onUseEmail={onUseEmail}
-          onRetry={() => onGenerate(method)}
-        />
-      ) : null}
+      <RaisingState
+        order={order}
+        method={method}
+        creating={creating && !choice.atProvider}
+        createError={createError}
+        errorField={errorField}
+        errorCode={errorCode}
+        onUseEmail={onUseEmail}
+        onGenerate={onGenerate}
+      />
     </Box>
   );
 }
+
+/**
+ * What the shell says while the order is being raised, and if raising it
+ * failed.
+ *
+ * The spinner is SUPPRESSED for a hand-off screen — that screen renders its own
+ * "Preparando o pagamento" while the charge is raised, and two stacked spinners
+ * saying the same thing is what the buyer actually saw. The caller decides
+ * that; here `creating` is simply true or false.
+ */
+function RaisingState({
+  order,
+  method,
+  creating,
+  createError,
+  errorField,
+  errorCode,
+  onUseEmail,
+  onGenerate,
+}: {
+  order: CheckoutOrder | null;
+  method: PaymentMethod | null;
+  creating: boolean;
+  createError: string | null;
+  errorField: BuyerField | null;
+  errorCode?: string | null;
+  onUseEmail: (email: string) => void;
+  onGenerate: (method: PaymentMethod) => void;
+}): JSX.Element | null {
+  const { LoadingState } = useCheckoutComponents();
+  const screens = useCheckoutCopy().screens;
+  if (order) return null;
+  if (creating) {
+    return (
+      <LoadingState
+        variant="spinner"
+        size="md"
+        message={screens.generatingPayment}
+        dataTestId="payment-generating"
+      />
+    );
+  }
+  if (!method || !createError) return null;
+  return (
+    <PaymentErrorPanel
+      message={createError}
+      emailFlagged={errorField === "email"}
+      code={errorCode}
+      onUseEmail={onUseEmail}
+      onRetry={() => onGenerate(method)}
+    />
+  );
+}

package/src/components/checkout/checkout-totals.tsx

@@ -0,0 +1,51 @@
+import { Box } from "@mui/material";
+import type { JSX, ReactNode } from "react";
+
+import { useCheckoutCopy } from "./copy-context";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * THE MONEY LINE both steps show.
+ *
+ * Its own module because two steps now render it — the Dados bar always did,
+ * and the Pagamento step does since FUT-1179, which is the ticket about a
+ * checkout that asked for money without ever showing the amount. One
+ * implementation so the two can never word the same total differently.
+ */
+
+/**
+ * The totals shown on the pay bar: the settled balance's when settling a settlement
+ * one, otherwise the cart's own — both supplied by the host, which
+ * is the only side that knows either.
+ */
+export function displayTotals(
+  override: { label: string; items: number } | undefined,
+  cart: { totalLabel: string; totalItems: number },
+): { label: string; items: number } {
+  return { label: override?.label ?? cart.totalLabel, items: override?.items ?? cart.totalItems };
+}
+
+/** The pay bar's money column: item count, grand total, host discount lines. */
+export function PayBarTotal({
+  totalLabel,
+  totalItems,
+  children,
+}: {
+  totalLabel: string;
+  totalItems: number;
+  children?: ReactNode;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens;
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", minWidth: 0 }}>
+      <Text variant="caption" size="xs" color="secondary" as="span">
+        {copy.totalCaption(totalItems)}
+      </Text>
+      <Text variant="heading" size="md" weight="bold" color="primary" as="span" data-testid="pay-bar-total">
+        {totalLabel}
+      </Text>
+      {children}
+    </Box>
+  );
+}

package/src/components/checkout/client-context.tsx

@@ -47,6 +47,9 @@ function unboundClient(copy: CheckoutTransportCopy): CheckoutClient {
     // The vault pair (FUT-183) has no `client.ts` free function to bind — it is
     // newer than that module. Built lazily from the default transport instead,
     // which is the same wire: `/api/checkout`, ambient `fetch` resolved per call.
+    // Same lazy build as the vault pair below, and for the same reason: this
+    // row is newer than `client.ts`, so there is no free function to bind.
+    releaseCheckout: (input) => createCheckoutClient({ copy }).releaseCheckout(input),
     beginVault: () => createCheckoutClient({ copy }).beginVault(),
     completeVault: (input) => createCheckoutClient({ copy }).completeVault(input),
     refreshBrowserKey: (input) => refreshCardPublicKey(input, copy),