@12-apps/payments-frontend 3.43.0 → 3.44.0

package/src/components/checkout/list/list-bar.tsx

@@ -1,11 +1,11 @@
 import { Box } from "@mui/material";
 import { keyframes } from "@mui/material/styles";
 import { useEffect, useRef, type JSX, type ReactNode } from "react";
+import { createPortal } from "react-dom";
 
-import { useCheckoutCopy } from "../copy-context";
-import type { GooglePaymentsClient } from "../google-pay-button";
 import { useCheckoutComponents } from "../ui";
 
+import { useSummaryColumnTarget } from "./summary-column";
 import { CHARGE_WINDOW_MS } from "./use-list-charge";
 
 /** The prototype's 52px action and 44px secondary, on the theme's spacing scale. */
@@ -23,7 +23,9 @@ function focusButtonIn(scope: HTMLElement | null): void {
  * is paying, the ONE action — or what replaced it — and why it is held.
  *
  * Drawn through the host's `ActionBar` slot, which is what pins it to the
- * bottom of the screen: the storefront passes its sticky action bar.
+ * bottom of the screen: the storefront passes its sticky action bar. On a
+ * computer (FUT-3685, L4) the same content goes into the "Resumo do pedido"
+ * column instead, and there is no bar at the bottom.
  *
  * ONE live region, always mounted, says what changes under the button — the
  * reason it is held, the charge under way, the wait — because a region that
@@ -39,29 +41,30 @@ export function ListBar({ summary, extras, payer, reason, live, children }: {
   live?: string | null;
   /** The action, or the charge bar, or the wait. */
   children: ReactNode;
-}): JSX.Element {
+}): JSX.Element | null {
   const { ActionBar, Text } = useCheckoutComponents();
-  return (
-    <ActionBar dataTestId="list-pay-bar">
-      <Box sx={{ display: "flex", flexDirection: "column", gap: 1, width: "100%", minWidth: 0 }}>
-        {summary ? <Box data-testid="list-bar-summary">{summary}</Box> : null}
-        {extras ? <Box data-testid="list-bar-extras">{extras}</Box> : null}
-        {payer}
-        {children}
-        <Box role="status" aria-live="polite" data-testid="list-bar-live">
-          {reason ? (
-            <Text variant="body" size="sm" color="danger" as="p" style={{ margin: 0 }} data-testid="list-blocked-reason">
-              {reason}
-            </Text>
-          ) : (
-            <Box component="span" sx={{ position: "absolute", width: "1px", height: "1px", overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" }}>
-              {live ?? ""}
-            </Box>
-          )}
-        </Box>
+  const column = useSummaryColumnTarget();
+  const content = (
+    <Box data-testid={column ? "list-pay-bar" : undefined} sx={{ display: "flex", flexDirection: "column", gap: 1, width: "100%", minWidth: 0 }}>
+      {summary ? <Box data-testid="list-bar-summary">{summary}</Box> : null}
+      {extras ? <Box data-testid="list-bar-extras">{extras}</Box> : null}
+      {payer}
+      {children}
+      <Box role="status" aria-live="polite" data-testid="list-bar-live">
+        {reason ? (
+          <Text variant="body" size="sm" color="danger" as="p" style={{ margin: 0 }} data-testid="list-blocked-reason">
+            {reason}
+          </Text>
+        ) : (
+          <Box component="span" sx={{ position: "absolute", width: "1px", height: "1px", overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" }}>
+            {live ?? ""}
+          </Box>
+        )}
       </Box>
-    </ActionBar>
+    </Box>
   );
+  if (column) return column.element ? createPortal(content, column.element) : null;
+  return <ActionBar dataTestId="list-pay-bar">{content}</ActionBar>;
 }
 
 /** "Pagar" on the left, "R$ 22,00" on the right — the prototype's 52px bar of a button. */
@@ -135,7 +138,9 @@ export function ChargeBar({ text, full, cancelLabel, onCancel }: {
             animation: full ? "none" : `${fill} ${CHARGE_WINDOW_MS}ms linear forwards`,
           }}
         />
-        <Box component="span" sx={{ position: "relative", color: "common.white", typography: "body1", fontWeight: 600 }}>
+        {/* One line, whatever the column's width: a sentence that wrapped inside the
+            52px bar ran over its edges (FUT-3685 review). The live region reads it whole. */}
+        <Box component="span" sx={{ position: "relative", minWidth: 0, color: "common.white", typography: "body1", fontWeight: 600, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
           {text}
         </Box>
       </Box>
@@ -164,23 +169,3 @@ export function WaitingLine({ text }: { text: string }): JSX.Element {
     </Box>
   );
 }
-
-/**
- * Google Pay's own button in the action's place (FUT-471's brand rule: the
- * buyer presses Google's button, drawn by `createButton`, never a look-alike).
- * Its press opens the sheet SYNCHRONOUSLY — inside the tap, as the browser
- * requires — through `onPress`.
- */
-export function GooglePayAction({ client, onPress }: { client: GooglePaymentsClient; onPress: () => void }): JSX.Element {
-  const mount = useRef<HTMLDivElement | null>(null);
-  const latest = useRef(onPress);
-  latest.current = onPress;
-  const locale = useCheckoutCopy().screens.wallet.googlePay.buttonLocale;
-  useEffect(() => {
-    const element = mount.current;
-    if (!element) return undefined;
-    element.replaceChildren(client.createButton({ onClick: () => latest.current(), buttonSizeMode: "fill", buttonLocale: locale }));
-    return () => element.replaceChildren();
-  }, [client, locale]);
-  return <Box ref={mount} data-testid="list-google-pay" sx={{ minHeight: (t) => t.spacing(ACTION_HEIGHT), "& > *": { width: "100%" } }} />;
-}

package/src/components/checkout/list/list-face.tsx

@@ -2,25 +2,25 @@ import { Box } from "@mui/material";
 import { useCallback, useEffect, useRef, useState, type JSX } from "react";
 
 import { cardChain, cardTokenization, handOffMethod } from "../method-capability";
-import { paymentDataRequest, sheetDismissed } from "../google-pay-button";
 import { PaymentErrorPanel } from "../payment-error-panel";
 import { UNRESOLVED_CODE } from "../failure-codes";
 import type { CheckoutBasketIdentity } from "../basket";
-import type { BuyerContact, CheckoutProviderConfig } from "../types";
+import type { BuyerContact, CheckoutProviderConfig, PaymentMethod } from "../types";
 import type { useCheckoutController } from "../use-checkout-controller";
-import { useCheckoutComponents } from "../ui";
 
-
-import { actionLabel, blockedReason, cardName } from "./choice";
+import { actionLabel, blockedReason, cardName, raisedMethod } from "./choice";
 import { usePaymentListMode, type PaymentListMode } from "./context";
 import { armPixCopy, armedReady, otherBankShown, pixBankLabel, useArmedCharge, useDropRefusedCopy } from "./list-memory";
 import { OtherBankLink } from "./list-pix";
 import { ChoiceList } from "./choice-list";
-import { CardRun, WalletRun, type ListChargeFailure } from "./charge-runners";
-import { ActionButton, ChargeBar, GooglePayAction, ListBar } from "./list-bar";
+import { CardRun, WalletRun, type ListChargeFailure, type WalletSheet } from "./charge-runners";
+import { ActionButton, ChargeBar, ListBar } from "./list-bar";
+import { ListTop, gateFields, walletsHeld } from "./list-top";
+import { PayerLine } from "./payer-line";
 import type { ListCapability } from "./use-capability";
 import type { ListCharge } from "./use-list-charge";
 import type { ListState } from "./use-list-state";
+import { useApplePayPress, useCloseOrphanSheet, useGooglePayPress, type WalletPressInput } from "./wallet-press";
 import type { CheckoutDoorOption, CheckoutOnlineChoice, CheckoutPaymentList } from "./types";
 
 type Controller = ReturnType<typeof useCheckoutController>;
@@ -43,12 +43,11 @@ interface ListFaceProps {
   saveBuyerContact?: (contact: BuyerContact) => void;
   /** The hand-off was started: the step shows where the buyer is going. */
   onHandOff: () => void;
-}
-
-/** Google Pay's sheet, opened in the tap: its answer and the amount it showed. */
-interface OpenSheet {
-  answer: Promise<string | null>;
-  cents: number;
+  /** "Alterar" on the payer line opened the CPF at the top (E2 → E1). */
+  revealed: boolean;
+  onRevealCpf: () => void;
+  /** "Manter o CPF salvo": close the revealed CPF, keeping the one on file. */
+  onKeepSavedCpf: () => void;
 }
 
 function chosenDoor(props: ListFaceProps): CheckoutDoorOption | undefined {
@@ -66,7 +65,10 @@ function inFlight(props: ListFaceProps): boolean {
 /** Remember the asked details for next time, as the Dados step's "Continuar" did — only with the buyer's consent. */
 function saveAsked(props: ListFaceProps): void {
   const { c, state, saveBuyerContact } = props;
-  if (state.asked.length === 0 || !c.saveProfile) return;
+  // The CPF at the top counts once the buyer typed one: a field revealed over a
+  // CPF on file and left empty asks the host to remember nothing new.
+  const typedCpf = state.top !== null && (c.buyer.taxId ?? "").trim() !== "";
+  if ((state.asked.length === 0 && !typedCpf) || !c.saveProfile) return;
   saveBuyerContact?.({ name: c.buyer.name, phone: c.buyer.phone, taxId: c.buyer.taxId });
 }
 
@@ -106,58 +108,47 @@ function useAct(props: ListFaceProps, clearFailure: () => void): (pick?: boolean
   };
 }
 
+/** The press facts both wallets share — see `./wallet-press.ts`. */
+function walletInput(
+  props: ListFaceProps,
+  held: string | null,
+  clearFailures: () => void,
+  onFailed: (failure: ListChargeFailure) => void,
+  pressed: WalletPressInput["pressed"],
+): WalletPressInput {
+  return {
+    pressed,
+    cap: props.cap,
+    charge: props.charge,
+    cents: props.list.totalCents,
+    total: onlineTotal(props),
+    blocked: held !== null || inFlight(props),
+    before: () => {
+      clearFailures();
+      saveAsked(props);
+    },
+    onFailed,
+  };
+}
+
 /**
- * Google Pay's press, from Google's own button: the sheet opens HERE, inside
- * the tap, priced with the host's amount due — then the order is raised behind it.
+ * A payment made HERE is still possible: the list offers an online way to pay
+ * (a row or a ready wallet) and no door row is chosen — nothing chosen counts,
+ * since a wallet pays with no row chosen at all (FUT-3685 review). What the
+ * host offers for a payment made here (store credit) and who is paying are
+ * shown while this holds.
  */
-function useGooglePayPress(props: ListFaceProps, clearFailure: () => void, sheet: { current: OpenSheet | null }): () => void {
-  return () => {
-    const { cap, list, charge } = props;
-    const cents = list.totalCents;
-    if (!cap.googlePay || cents === undefined || inFlight(props)) return;
-    clearFailure();
-    saveAsked(props);
-    const answer = cap.googlePay.client
-      .loadPaymentData(paymentDataRequest(cap.googlePay.params, { totalCents: cents }))
-      .then(
-        (data) => data.paymentMethodData.tokenizationData.token,
-        (error: unknown) => {
-          if (sheetDismissed(error)) return null;
-          throw error;
-        },
-      );
-    sheet.current = { answer, cents };
-    charge.start("GOOGLE_PAY", onlineTotal(props));
-  };
+function payingHere(props: ListFaceProps): boolean {
+  const offersOnline = props.state.rows.length > 0 || props.cap.wallets.length > 0;
+  return offersOnline && props.state.choice?.kind !== "door";
 }
 
-/** Who is paying, when the store already holds their CPF (FUT-465): "Pagando como … · CPF ✓ Alterar". */
-function PayerLine({ props }: { props: ListFaceProps }): JSX.Element | null {
-  const { Button, Text } = useCheckoutComponents();
-  const { c, list, taxIdOnFile, state } = props;
+/** "Pagando como … · CPF ✓ Alterar" — while a payment here is possible and the CPF is not open. */
+function Payer({ props }: { props: ListFaceProps }): JSX.Element | null {
+  const { c, list, taxIdOnFile } = props;
   const name = c.buyer.name?.trim();
-  if (!taxIdOnFile || !name || state.choice?.kind !== "online") return null;
-  return (
-    // Left-aligned, "Alterar" ~4px after "CPF ✓" and wrapping under it when
-    // the name is long; the link keeps a 40px target and a visible focus ring.
-    <Box data-testid="list-payer" sx={{ display: "flex", alignItems: "center", justifyContent: "flex-start", flexWrap: "wrap", columnGap: 0 }}>
-      <Text variant="body" size="sm" color="secondary" as="span">
-        {list.copy.payer(name)}
-      </Text>
-      {c.editBuyer ? (
-        <Box
-          sx={{
-            "& button": { textDecoration: "underline", minHeight: (t) => t.spacing(5), minWidth: 0, px: 0.5, py: 0 },
-            "& button:focus-visible": { outline: (t) => `${t.spacing(0.25)} solid ${t.palette.primary.main}`, outlineOffset: (t) => t.spacing(0.25) },
-          }}
-        >
-          <Button variant="text" color="primary" size="sm" onClick={c.editBuyer} dataTestId="list-payer-change">
-            {list.copy.payerChange}
-          </Button>
-        </Box>
-      ) : null}
-    </Box>
-  );
+  if (!taxIdOnFile || !name || props.revealed || !payingHere(props)) return null;
+  return <PayerLine copy={list.copy} name={name} onChange={props.onRevealCpf} />;
 }
 
 /** The card's charge is past the button: counting down, or going out. */
@@ -188,22 +179,6 @@ function buttonFacts(props: ListFaceProps): { label: string; total: string; busy
   };
 }
 
-/**
- * Google Pay chosen while the host re-prices (or for the one render before the
- * list drops a choice nobody prices any more): a plain disabled button, never
- * a spinner, with `copy.reasons.repricing` under it.
- */
-function googlePayUnpriced(props: ListFaceProps): boolean {
-  const { choice } = props.state;
-  return choice?.kind === "online" && choice.method === "GOOGLE_PAY" && !props.cap.googlePay;
-}
-
-/** Google Pay is chosen and nothing holds it: Google's own button takes the action's place. */
-function googlePayLive(props: ListFaceProps, reason: string | null, busy: boolean): boolean {
-  const { choice } = props.state;
-  return choice?.kind === "online" && choice.method === "GOOGLE_PAY" && props.cap.googlePay !== null && reason === null && !busy;
-}
-
 /** The 5-second bar (or the charge going out), and the host's footer while it counts. */
 function ChargingBar({ props, onCancel }: { props: ListFaceProps; onCancel: () => void }): JSX.Element {
   const { charge, list } = props;
@@ -235,34 +210,29 @@ function PressButton({ props, act, reason, returnFocus }: {
   );
 }
 
-/** The button, the 5-second bar, Google's own button, or nothing for a charge nobody can confirm yet. */
-function BarAction({ props, failure, act, onGooglePay, onCancel, reason, returnFocus }: {
+/** The button, the 5-second bar, or nothing for a charge nobody can confirm yet. */
+function BarAction({ props, failure, act, onCancel, reason, returnFocus }: {
   props: ListFaceProps;
   failure: ListChargeFailure | null;
   act: (pick?: boolean) => void;
-  onGooglePay: () => void;
   onCancel: () => void;
   reason: string | null;
   returnFocus: boolean;
 }): JSX.Element | null {
-  const { charge, cap } = props;
-  if (cardCharging(charge)) return <ChargingBar props={props} onCancel={onCancel} />;
+  if (cardCharging(props.charge)) return <ChargingBar props={props} onCancel={onCancel} />;
   // An UNRESOLVED charge may be holding the buyer's money: no pay control at
   // all under "não pague de novo" (FUT-563), as the card pane does today.
   if (failure?.code === UNRESOLVED_CODE) return null;
-  if (googlePayUnpriced(props)) {
-    const { label, total } = buttonFacts(props);
-    return <ActionButton label={label} total={total} disabled loading={false} onClick={() => act()} />;
-  }
-  if (googlePayLive(props, reason, inFlight(props)) && cap.googlePay) return <GooglePayAction client={cap.googlePay.client} onPress={onGooglePay} />;
   return <PressButton props={props} act={act} reason={reason} returnFocus={returnFocus} />;
 }
 
 /** The charge under way, once there is an order to run it against. */
-function Runners({ props, sheet, onFailed }: {
+function Runners({ props, sheet, onFailed, onWalletFailed }: {
   props: ListFaceProps;
-  sheet: OpenSheet | null;
+  sheet: WalletSheet | null;
   onFailed: (failure: ListChargeFailure | null) => void;
+  /** A wallet's refusal is said under the wallet buttons, not in a row. */
+  onWalletFailed: (failure: ListChargeFailure | null) => void;
 }): JSX.Element | null {
   const { c, charge, config } = props;
   const order = charge.chargeable;
@@ -274,7 +244,7 @@ function Runners({ props, sheet, onFailed }: {
   if (charge.kind === "CARD") {
     return <CardRun {...common} card={props.state.card} config={cardTokenization(config)} chain={cardChain(config)} />;
   }
-  if (charge.kind === "GOOGLE_PAY" && sheet) return <WalletRun {...common} sheet={sheet.answer} sheetCents={sheet.cents} />;
+  if (charge.kind !== null && charge.kind === sheet?.type) return <WalletRun {...common} onFailed={onWalletFailed} sheet={sheet} />;
   return null;
 }
 
@@ -289,14 +259,24 @@ function coveredByHost(list: CheckoutPaymentList): boolean {
   return list.totalCents === 0;
 }
 
-/** Why the button is held: the host's hold, then the list's own reasons, in the prototype's order. */
+/**
+ * Why the button is held: the host's hold, then the list's own reasons, in the
+ * prototype's order — the CPF at the top first, for an online choice that needs
+ * it (E3); a door choice never does (R3).
+ */
 function reasonOf(props: ListFaceProps, door: CheckoutDoorOption | undefined): string | null {
-  const { c, list, state } = props;
-  const reason = blockedReason({
-    copy: list.copy, hold: list.hold?.reason ?? null, choice: state.choice, door, asked: state.asked,
+  const { c, list, state, config } = props;
+  return blockedReason({
+    copy: list.copy, hold: list.hold?.reason ?? null, choice: state.choice, door,
+    asked: gateFields(state, c.buyer, config, raisedOf(props)),
     buyer: c.buyer, selection: state.card.selection, cardIsComplete: state.card.complete, covered: coveredByHost(list),
   });
-  return reason ?? (googlePayUnpriced(props) ? (list.copy.reasons.repricing ?? null) : null);
+}
+
+/** The chain method the chosen online option would raise, or `null`. */
+function raisedOf(props: ListFaceProps): PaymentMethod | null {
+  const { choice } = props.state;
+  return choice?.kind === "online" ? raisedMethod(choice.method, props.cap.offered) : null;
 }
 
 /**
@@ -306,11 +286,10 @@ function reasonOf(props: ListFaceProps, door: CheckoutDoorOption | undefined): s
  */
 function barFacts(props: ListFaceProps, door: CheckoutDoorOption | undefined, reason: string | null) {
   const charging = props.charge.phase !== "idle";
-  const online = props.state.choice?.kind === "online";
   return {
     charging,
     locked: inFlight(props),
-    extras: online && !charging ? props.list.onlineExtras : undefined,
+    extras: payingHere(props) && !charging ? props.list.onlineExtras : undefined,
     underButton: charging ? null : (door?.error ?? reason),
     live: cardCharging(props.charge) ? chargingText(props) : null,
   };
@@ -342,6 +321,29 @@ function useCancelWithFocus(charge: ListCharge): { returnFocus: boolean; onCance
   return { returnFocus, onCancel };
 }
 
+/**
+ * The wallets' sheet, their refusal and the presses that open one. A refusal
+ * (or a sheet that could not open) is said under the wallet buttons; a closed
+ * sheet (`null`) never clears one the wallet already gave.
+ */
+function useWallets(props: ListFaceProps, clearFailure: () => void) {
+  const sheet = useRef<WalletSheet | null>(null);
+  const [failure, setFailure] = useState<ListChargeFailure | null>(null);
+  const { settle } = props.charge;
+  const onFailed = useCallback((next: ListChargeFailure | null) => { setFailure((previous) => next ?? previous); settle(); }, [settle]);
+  const held = walletsHeld({ state: props.state, buyer: props.c.buyer, list: props.list, cap: props.cap, config: props.config });
+  const before = () => {
+    setFailure(null);
+    clearFailure();
+  };
+  const pressed = useRef(false);
+  const input = walletInput(props, held, before, onFailed, pressed);
+  const onGoogle = useGooglePayPress(input, sheet);
+  const onApple = useApplePayPress(input, sheet);
+  useCloseOrphanSheet(props.charge.phase, sheet, pressed);
+  return { sheet, held, failure, onFailed, clearWalletFailure: () => setFailure(null), onGoogle, onApple };
+}
+
 /** The list, the charge under way, and the bar. */
 export function ListFace(props: ListFaceProps): JSX.Element {
   const { c, list, state, charge } = props;
@@ -349,9 +351,12 @@ export function ListFace(props: ListFaceProps): JSX.Element {
   const clearFailure = useCallback(() => setFailure(null), []);
   const { settle } = charge;
   const onFailed = useCallback((next: ListChargeFailure | null) => { setFailure(next); settle(); }, [settle]);
-  const sheet = useRef<OpenSheet | null>(null);
-  const act = useAct(props, clearFailure);
-  const onGooglePay = useGooglePayPress(props, clearFailure, sheet);
+  const wallets = useWallets(props, clearFailure);
+  const { clearWalletFailure } = wallets;
+  const act = useAct(props, () => {
+    clearFailure();
+    clearWalletFailure();
+  });
   const door = chosenDoor(props);
   const reason = reasonOf(props, door);
   useChargeGuard(props, reason);
@@ -361,16 +366,17 @@ export function ListFace(props: ListFaceProps): JSX.Element {
   const { returnFocus, onCancel } = useCancelWithFocus(charge);
   const shown = charge.phase !== "waiting";
   const facts = barFacts(props, door, reason);
+  const top = <ListTop props={props} held={wallets.held} failure={wallets.failure} onGoogle={wallets.onGoogle} onApple={wallets.onApple} />;
   return (
     <Box data-testid="payment-list-step" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       {shown ? (
-        <ChoiceList copy={list.copy} state={state} door={list.door ?? []} buyer={c.buyer} onBuyerChange={c.setBuyer} provider={props.provider} failure={failure} locked={facts.locked} covered={coveredByHost(list)} />
+        <ChoiceList copy={list.copy} state={state} door={list.door ?? []} buyer={c.buyer} onBuyerChange={c.setBuyer} provider={props.provider} failure={failure} locked={facts.locked} covered={coveredByHost(list)} top={top} />
       ) : null}
-      <Runners props={props} sheet={sheet.current} onFailed={onFailed} />
+      <Runners props={props} sheet={wallets.sheet.current} onFailed={onFailed} onWalletFailed={wallets.onFailed} />
       <RaiseError c={c} onRetry={() => act()} />
       {shown ? (
-        <ListBar summary={list.summary} extras={facts.extras} payer={facts.charging ? null : <PayerLine props={props} />} reason={facts.underButton} live={facts.live}>
-          <BarAction props={props} failure={failure} act={act} onGooglePay={onGooglePay} onCancel={onCancel} reason={reason} returnFocus={returnFocus} />
+        <ListBar summary={list.summary} extras={facts.extras} payer={facts.charging ? null : <Payer props={props} />} reason={facts.underButton} live={facts.live}>
+          <BarAction props={props} failure={failure ?? wallets.failure} act={act} onCancel={onCancel} reason={reason} returnFocus={returnFocus} />
         </ListBar>
       ) : null}
     </Box>

package/src/components/checkout/list/list-top.tsx

@@ -0,0 +1,99 @@
+import { Box } from "@mui/material";
+import { useRef, type JSX } from "react";
+
+import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig, PaymentMethod } from "../types";
+
+import type { ListChargeFailure } from "./charge-runners";
+import { CpfTop } from "./cpf-top";
+import { cpfHolds, cpfProvider } from "./top-cpf";
+import type { CheckoutPaymentList } from "./types";
+import type { ListCapability } from "./use-capability";
+import type { ListState } from "./use-list-state";
+import { WalletBlock } from "./wallet-block";
+
+/**
+ * The fields that hold the bar's button for the chosen online option, in the
+ * order they are asked: the CPF at the top when this method's chain needs it
+ * (or a typed one is not valid), then the row's own (E3). `method` is `null`
+ * for a door choice or none — a door row never needs the CPF (R3).
+ */
+export function gateFields(
+  state: Pick<ListState, "top" | "asked">,
+  buyer: BuyerInfo,
+  config: CheckoutProviderConfig | null,
+  method: PaymentMethod | null,
+): CheckoutCustomerField[] {
+  if (method === null || !state.top) return state.asked;
+  return cpfHolds(state.top, buyer, config?.chain, method) ? [state.top, ...state.asked] : state.asked;
+}
+
+/**
+ * Why the wallet buttons cannot act yet, or `null`: the host's hold (a step
+ * before this one is open), the CPF the provider needs (E3 — a wallet raises a
+ * card order), the host re-pricing the sheet.
+ */
+export function walletsHeld(input: {
+  state: Pick<ListState, "top">;
+  buyer: BuyerInfo;
+  list: CheckoutPaymentList;
+  cap: ListCapability;
+  config: CheckoutProviderConfig | null;
+}): string | null {
+  const { list, cap } = input;
+  if (list.hold) return list.hold.reason;
+  if (cpfHolds(input.state.top, input.buyer, input.config?.chain, "CARD")) return list.copy.reasons.cpf;
+  const priced = cap.wallets.every((wallet) => (wallet === "GOOGLE_PAY" ? cap.googlePay : cap.applePay) !== null);
+  return priced ? null : (list.copy.reasons.repricing ?? list.copy.reasons.choose);
+}
+
+/** Move the focus to "Número do cartão" — the next thing to type once the CPF is complete. */
+function focusCardNumber(scope: HTMLElement | null): void {
+  scope?.closest('[data-testid="payment-list"]')?.querySelector<HTMLInputElement>('input[data-testid="card-number"]')?.focus();
+}
+
+/** What the top of the list reads, gathered by the face. */
+interface ListTopFacts {
+  list: CheckoutPaymentList;
+  state: ListState;
+  cap: ListCapability;
+  config: CheckoutProviderConfig | null;
+  c: { buyer: BuyerInfo; setBuyer: (buyer: BuyerInfo) => void };
+  revealed: boolean;
+  /** Close a CPF opened over the one on file, keeping that one. */
+  onKeepSavedCpf: () => void;
+}
+
+/**
+ * The top of Pagamento (FUT-3685): the CPF, asked once (E1, L7), then the
+ * "PAGAMENTO RÁPIDO" block (C5, C6) — both above the rows.
+ */
+export function ListTop({ props, held, failure, onGoogle, onApple }: {
+  props: ListTopFacts;
+  held: string | null;
+  /** The last wallet charge's refusal, said under the buttons. */
+  failure: ListChargeFailure | null;
+  onGoogle: () => void;
+  onApple: () => void;
+}): JSX.Element | null {
+  const scope = useRef<HTMLDivElement | null>(null);
+  const { list, state, cap, config, c } = props;
+  if (!state.top && cap.wallets.length === 0) return null;
+  const typingCard = state.choice?.kind === "online" && state.choice.method === "CARD";
+  return (
+    <Box ref={scope} data-testid="list-top" sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      {state.top ? (
+        <CpfTop
+          field={state.top}
+          buyer={c.buyer}
+          onBuyerChange={c.setBuyer}
+          copy={list.copy.buyer}
+          provider={cpfProvider(config?.chain, state.methods)}
+          onComplete={typingCard ? () => focusCardNumber(scope.current) : undefined}
+          focusOnMount={props.revealed}
+          onKeepSaved={props.revealed ? props.onKeepSavedCpf : undefined}
+        />
+      ) : null}
+      <WalletBlock cap={cap} copy={list.copy} held={held} failure={failure} onGoogle={onGoogle} onApple={onApple} />
+    </Box>
+  );
+}

package/src/components/checkout/list/online-content.tsx

@@ -102,6 +102,7 @@ export function OnlineContent({
   provider,
   failure,
   covered = false,
+  withConsent = true,
 }: {
   method: "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
   asked: readonly CheckoutCustomerField[];
@@ -113,6 +114,8 @@ export function OnlineContent({
   failure: ListChargeFailure | null;
   /** The host's balance pays the whole amount — no chips, no card fields. */
   covered?: boolean;
+  /** Offer "Salvar meus dados…" beside the asked fields — not when the top of Pagamento does. */
+  withConsent?: boolean;
 }): JSX.Element {
   const scope = useRef<HTMLDivElement | null>(null);
   const isCard = method === "CARD" && !covered;
@@ -125,6 +128,7 @@ export function OnlineContent({
         copy={copy.buyer}
         provider={provider}
         onComplete={isCard ? () => focusCardNumber(scope.current) : undefined}
+        withConsent={withConsent}
       />
       {isCard ? <SavedChips card={card} copy={copy} /> : null}
       {isCard && card.selection === NEW_CARD ? (

package/src/components/checkout/list/option-row.tsx

@@ -78,8 +78,11 @@ export function OptionRow({
     >
       <Box
         component="label"
-        // 48 + the border = the prototype's 50px row, with or without a hint (L3).
-        sx={{ display: "flex", alignItems: "center", gap: 1.5, minHeight: (t) => t.spacing(6), py: 0, cursor: disabled ? "default" : "pointer" }}
+        // The prototype's `.opt` padding, 12px above and below the label and its
+        // hint (FUT-3685 review): a row with a hint is ~62px, and the hint never
+        // touches — or is clipped by — the row's border. 48px is the floor, for
+        // a row with no hint.
+        sx={{ display: "flex", alignItems: "center", gap: 1.5, minHeight: (t) => t.spacing(6), py: 1.5, cursor: disabled ? "default" : "pointer" }}
       >
         <Radio
           name={name}

package/src/components/checkout/list/payer-line.tsx

@@ -0,0 +1,39 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { useCheckoutComponents } from "../ui";
+
+import type { PaymentListCopy } from "./types";
+
+/**
+ * Who is paying, when the store already holds their CPF (FUT-465): "Pagando
+ * como … · CPF ✓ Alterar". "Alterar" reveals the CPF field at the top of
+ * Pagamento (FUT-3685, E2 → E1) — never a Dados step: the list has none
+ * (R9). Shown only while an online option is chosen and the CPF is not open.
+ */
+export function PayerLine({ copy, name, onChange }: {
+  copy: PaymentListCopy;
+  name: string;
+  onChange: () => void;
+}): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  return (
+    // Left-aligned, "Alterar" ~4px after "CPF ✓" and wrapping under it when
+    // the name is long; the link keeps a 40px target and a visible focus ring.
+    <Box data-testid="list-payer" sx={{ display: "flex", alignItems: "center", justifyContent: "flex-start", flexWrap: "wrap", columnGap: 0 }}>
+      <Text variant="body" size="sm" color="secondary" as="span">
+        {copy.payer(name)}
+      </Text>
+      <Box
+        sx={{
+          "& button": { textDecoration: "underline", minHeight: (t) => t.spacing(5), minWidth: 0, px: 0.5, py: 0 },
+          "& button:focus-visible": { outline: (t) => `${t.spacing(0.25)} solid ${t.palette.primary.main}`, outlineOffset: (t) => t.spacing(0.25) },
+        }}
+      >
+        <Button variant="text" color="primary" size="sm" onClick={onChange} dataTestId="list-payer-change">
+          {copy.payerChange}
+        </Button>
+      </Box>
+    </Box>
+  );
+}