@12-apps/payments-frontend 3.43.1 → 3.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.43.1",
+  "version": "3.45.0",
   "type": "module",
   "sideEffects": false,
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.33.1",
+    "@12-apps/payments-backend": "^4.34.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/checkout/apple-pay-button.tsx

@@ -68,7 +68,7 @@ export interface ApplePaySessionClass {
 }
 
 /** The native constructor, where Safari (or a harness) provides one. */
-function applePaySessionClass(): ApplePaySessionClass | null {
+export function applePaySessionClass(): ApplePaySessionClass | null {
   if (typeof window === "undefined") return null;
   const scope = window as unknown as { ApplePaySession?: ApplePaySessionClass };
   return scope.ApplePaySession ?? null;
@@ -89,8 +89,8 @@ export function applePaySupported(): boolean {
   }
 }
 
-/** The sheet's payment request, from the server-authoritative order total. */
-function paymentRequest(order: CheckoutOrder, copy: ApplePayCopy): ApplePayPaymentRequest {
+/** The sheet's payment request, priced at `cents` — the amount the charge will ask for. */
+function paymentRequest(cents: number, copy: ApplePayCopy): ApplePayPaymentRequest {
   return {
     countryCode: "BR",
     currencyCode: "BRL",
@@ -99,12 +99,25 @@ function paymentRequest(order: CheckoutOrder, copy: ApplePayCopy): ApplePayPayme
     // The one line Apple's own sheet renders from us, so it is the host's
     // (FUT-760) — the rest of that sheet is Apple's, in the buyer's own
     // system language.
-    total: { label: copy.orderTotal, amount: (order.totalCents / 100).toFixed(2) },
+    total: { label: copy.orderTotal, amount: (cents / 100).toFixed(2) },
   };
 }
 
-export interface ApplePayButtonProps {
-  order: CheckoutOrder;
+/**
+ * What the sheet is priced from — exactly one of the two:
+ *
+ *  - `order`: the raised order (`order.totalCents`) — the tabs layout's case;
+ *  - `totalCents`: the amount, in integer cents, when no order exists yet — the
+ *    one list's case (FUT-3685): the session must start INSIDE the tap, so it
+ *    is priced with the host's amount due and the order is raised in parallel.
+ */
+type ApplePayButtonPrice = { order: CheckoutOrder; totalCents?: never } | { totalCents: number; order?: never };
+
+/** {@link ApplePayButton}'s props: its price, and the handlers below. */
+export type ApplePayButtonProps = ApplePayButtonPrice & ApplePayButtonHandlers;
+
+/** The handlers every Apple Pay button takes, however it is priced. */
+interface ApplePayButtonHandlers {
   /**
    * The payment authorized on the sheet — charge this key. Resolves `true`
    * when the charge was accepted (paid, or confirming), `false` on a refusal,
@@ -123,40 +136,75 @@ export interface ApplePayButtonProps {
   validateMerchant?: (validationURL: string) => Promise<unknown>;
 }
 
-/** Wire one session run. Split from the component for the size gate. */
-function runSession(
-  Session: ApplePaySessionClass,
-  order: CheckoutOrder,
-  handlers: ApplePayButtonProps,
-  copy: ApplePayCopy,
-): void {
-  const session = new Session(APPLE_PAY_VERSION, paymentRequest(order, copy));
+/** What one started session hands back: the wallet key, and the way to close the sheet. */
+interface ApplePaySheet {
+  /** Apple's `token.paymentData`, serialized verbatim — or `null` when the buyer closed the sheet. */
+  answer: Promise<string | null>;
+  /** Close the sheet with the charge's honest outcome. */
+  complete: (accepted: boolean) => void;
+}
+
+/**
+ * Start ONE Apple Pay session, SYNCHRONOUSLY — call it from inside the buyer's
+ * tap, which Safari requires for `new ApplePaySession(…).begin()`. Priced at
+ * `cents`; the merchant is validated through the host's port, server-side.
+ * A validation that cannot run aborts the session and reports why through
+ * `onError` (the answer then resolves `null`).
+ */
+export function startApplePaySession(input: {
+  Session: ApplePaySessionClass;
+  cents: number;
+  copy: ApplePayCopy;
+  validateMerchant: ((validationURL: string) => Promise<unknown>) | undefined;
+  onError: (message: string) => void;
+}): ApplePaySheet {
+  const { Session, copy } = input;
+  const session = new Session(APPLE_PAY_VERSION, paymentRequest(input.cents, copy));
+  let settle: (key: string | null) => void = () => undefined;
+  const answer = new Promise<string | null>((resolve) => {
+    settle = resolve;
+  });
+  const fail = (message: string): void => {
+    session.abort();
+    settle(null);
+    input.onError(message);
+  };
   session.onvalidatemerchant = (event) => {
-    const validate = handlers.validateMerchant;
-    if (!validate) {
-      session.abort();
-      handlers.onError(copy.cannotStart);
-      return;
-    }
+    const validate = input.validateMerchant;
+    if (!validate) return fail(copy.cannotStart);
     validate(event.validationURL)
       .then((merchantSession) => session.completeMerchantValidation(merchantSession))
-      .catch(() => {
-        session.abort();
-        handlers.onError(copy.cannotComplete);
-      });
-  };
-  session.onpaymentauthorized = (event) => {
-    // Apple's `token.paymentData`, serialized VERBATIM — PagBank's `key`.
-    const key = JSON.stringify(event.payment.token.paymentData);
-    void handlers.onAuthorized(key).then((accepted) => {
-      session.completePayment({
-        status: accepted ? Session.STATUS_SUCCESS : Session.STATUS_FAILURE,
-      });
-    });
+      .catch(() => fail(copy.cannotComplete));
   };
+  // Apple's `token.paymentData`, serialized VERBATIM — PagBank's `key`.
+  session.onpaymentauthorized = (event) => settle(JSON.stringify(event.payment.token.paymentData));
   // Closing the sheet is a choice, not a failure to report.
-  session.oncancel = () => undefined;
-  session.begin();
+  session.oncancel = () => settle(null);
+  try {
+    session.begin();
+  } catch (error) {
+    // A session Safari would not begin must not stay open behind the next one.
+    try {
+      session.abort();
+    } catch {
+      // Nothing more to close.
+    }
+    throw error;
+  }
+  const complete = (accepted: boolean): void =>
+    session.completePayment({ status: accepted ? Session.STATUS_SUCCESS : Session.STATUS_FAILURE });
+  return { answer, complete };
+}
+
+/** One session run for the button: charge the authorized key, then close the sheet honestly. */
+function runSession(Session: ApplePaySessionClass, handlers: ApplePayButtonProps, copy: ApplePayCopy): void {
+  const cents = handlers.totalCents ?? handlers.order?.totalCents;
+  if (cents === undefined) return;
+  const sheet = startApplePaySession({ Session, cents, copy, validateMerchant: handlers.validateMerchant, onError: handlers.onError });
+  void sheet.answer.then(async (key) => {
+    if (key === null) return;
+    sheet.complete(await handlers.onAuthorized(key));
+  });
 }
 
 /**
@@ -180,7 +228,7 @@ export function ApplePayButton(props: ApplePayButtonProps): JSX.Element | null {
       type="button"
       aria-label={copy.payAction}
       data-testid="apple-pay-button"
-      onClick={() => runSession(Session, current.current.order, current.current, copy)}
+      onClick={() => runSession(Session, current.current, copy)}
       sx={{
         WebkitAppearance: "-apple-pay-button",
         // Apple draws the button; these only give it room. The fallback

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

@@ -97,7 +97,7 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
    * The host's Apple Pay merchant-validation port (FUT-472): exchange the
    * session's `validationURL` for an Apple merchant session, SERVER-SIDE.
    * Optional — without it the Apple Pay sheet cannot start, and the card form
-   * remains the way to pay.
+   * remains the way to pay (the one list then offers no Apple Pay at all).
  */
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** Host content shown on the paid confirmation (the storefront's install invite). */
@@ -118,7 +118,8 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
    * options and the host's door options in one radio group, nothing raised on
    * a pick, the bar's button the only way an order is made, and the card
    * charged after a 5-second bar the buyer can cancel (FUT-3592). The buyer's
-   * missing CPF is asked inside the option instead of on a Dados step first.
+   * missing CPF is asked once at the top of the step, above the wallet buttons
+   * (FUT-3685), instead of on a Dados step first.
    * Absent: the method tabs, the order summary and raise-on-pick, unchanged.
    * See `./list/types.ts`.
    */

package/src/components/checkout/google-pay-button.tsx

@@ -26,6 +26,12 @@ export interface GooglePaymentsClient {
     onClick: () => void;
     buttonSizeMode?: string;
     buttonLocale?: string;
+    /** "black" | "white" | "default" — Google's own palette for its button. */
+    buttonColor?: string;
+    /** "pay", "buy", "plain"… — which of Google's labels it draws. */
+    buttonType?: string;
+    /** The corner radius Google draws, in CSS pixels (Google's own parameter). */
+    buttonRadius?: number;
   }): HTMLElement;
   loadPaymentData(request: Record<string, unknown>): Promise<GooglePaymentData>;
 }

package/src/components/checkout/list/buyer-inline.tsx

@@ -12,9 +12,10 @@ import type { PaymentListCopy } from "./types";
 
 /**
  * The buyer's own details the chosen option needs, asked INSIDE it and ABOVE
- * the card fields (M11, the owner's "maybe.. we should ask cpf first"): only
- * the ones the store's chain requires for this method and the buyer arrived
- * without. A buyer with a CPF on file never sees the field.
+ * the card fields (M11): only the ones the store's chain requires for this
+ * method and the buyer arrived without — the hand-off provider's mobile (K4).
+ * The CPF is no longer one of them: it is asked once, at the top of Pagamento
+ * (`./cpf-top.tsx`, FUT-3685).
  *
  * When the last of them is complete, `onComplete` fires once — the card
  * option moves the focus to "Número do cartão" with it, so the buyer's next
@@ -34,18 +35,29 @@ function nameOf(field: CheckoutCustomerField, copy: Copy): string {
 }
 
 /** The sentence under a field the buyer has started and not finished. */
-function complaintOf(field: CheckoutCustomerField, value: string, copy: Copy, cpfInvalid: (v: string) => string | undefined): string | undefined {
+export function complaintOf(field: CheckoutCustomerField, value: string, copy: Copy, cpfInvalid: (v: string) => string | undefined): string | undefined {
   if (!value.trim() || fieldSatisfied(field, value)) return undefined;
   if (field.key === "taxId") return onlyDigits(value).length < 11 ? copy.cpfIncomplete : cpfInvalid(value);
   if (field.key === "phone") return copy.phoneIncomplete;
   return undefined;
 }
 
-const PLACEHOLDERS: Partial<Record<CheckoutCustomerField["key"], string>> = {
+export const PLACEHOLDERS: Partial<Record<CheckoutCustomerField["key"], string>> = {
   taxId: "000.000.000-00",
   phone: "(00) 00000-0000",
 };
 
+/** Call `onComplete` once each time `complete` turns true — the focus moves on to what is next. */
+export function useOnComplete(complete: boolean, onComplete: (() => void) | undefined): void {
+  const was = useRef(complete);
+  const latest = useRef(onComplete);
+  latest.current = onComplete;
+  useEffect(() => {
+    if (complete && !was.current) latest.current?.();
+    was.current = complete;
+  }, [complete]);
+}
+
 export function BuyerInline({
   asked,
   buyer,
@@ -53,6 +65,7 @@ export function BuyerInline({
   copy,
   provider,
   onComplete,
+  withConsent = true,
 }: {
   asked: readonly CheckoutCustomerField[];
   buyer: BuyerInfo;
@@ -61,18 +74,13 @@ export function BuyerInline({
   /** The store's provider, named in the "why" — `null` when it published no name. */
   provider: string | null;
   onComplete?: () => void;
+  /** Offer "Salvar meus dados…" here — not when the top of Pagamento already does (FUT-3685). */
+  withConsent?: boolean;
 }): JSX.Element | null {
   const { Checkbox, Input, Text } = useCheckoutComponents();
   const consent = usePaymentListMode()?.consent;
   const cardCopy = useCheckoutCopy().card;
-  const complete = asked.every((field) => fieldSatisfied(field, buyer[field.key]));
-  const was = useRef(complete);
-  const latest = useRef(onComplete);
-  latest.current = onComplete;
-  useEffect(() => {
-    if (complete && !was.current) latest.current?.();
-    was.current = complete;
-  }, [complete]);
+  useOnComplete(asked.every((field) => fieldSatisfied(field, buyer[field.key])), onComplete);
   if (asked.length === 0) return null;
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 1.25 }}>
@@ -112,7 +120,7 @@ export function BuyerInline({
           </Box>
         );
       })}
-      {consent ? (
+      {consent && withConsent ? (
         <Checkbox
           label={consent.label}
           checked={consent.checked}

package/src/components/checkout/list/charge-runners.tsx

@@ -1,7 +1,7 @@
 /**
- * The two charges the one list's button starts once an order is held
- * (FUT-3592): the CARD — the buyer's saved card or the one they typed — and
- * GOOGLE PAY's sheet. Each is the existing money path (`useCardSubmit`,
+ * The charges the one list starts once an order is held (FUT-3592,
+ * FUT-3685): the CARD — the buyer's saved card or the one they typed — and a
+ * wallet's sheet, Google Pay's or Apple Pay's. Each is the existing money path (`useCardSubmit`,
  * `useWalletCharge`), run with no button of its own: the list's bar already
  * was the button, and its 5-second window the buyer's chance to stop it.
  *
@@ -17,7 +17,7 @@ import { useRefreshOnCartChanged } from "../cart-changed";
 import { SubmittedState } from "../card-view";
 import type { ChallengeScope } from "../card-outcome";
 import { useCheckoutCopy } from "../copy-context";
-import type { BuyerInfo, CheckoutOrder, OnCheckoutResolved } from "../types";
+import type { BuyerInfo, CheckoutOrder, CheckoutWalletType, OnCheckoutResolved } from "../types";
 import { useCardSubmit } from "../use-card-checkout";
 import { useWalletCharge } from "../use-wallet-charge";
 
@@ -112,27 +112,45 @@ export function CardRun({
  * charge that the order view does not report. Said once in development; the
  * buyer still gets the refusal.
  */
-function warnMissingAmountDue(order: CheckoutOrder, sheetCents: number): void {
+function warnMissingAmountDue(order: CheckoutOrder, sheetCents: number, type: CheckoutWalletType): void {
   const development = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
   if (order.amountDueCents !== undefined || !development) return;
+  const wallet = type === "APPLE_PAY" ? "Apple Pay" : "Google Pay";
   console.warn(
-    `[payments-frontend] Google Pay refused: the order costs ${order.totalCents} cents and the sheet showed ${sheetCents}. ` +
+    `[payments-frontend] ${wallet} refused: the order costs ${order.totalCents} cents and the sheet showed ${sheetCents}. ` +
       "A host that takes a balance off the charge must answer CheckoutOrder.amountDueCents.",
   );
 }
 
+/** A wallet's sheet, opened inside the tap: its answer, the amount it showed, and how to close it. */
+export interface WalletSheet {
+  type: CheckoutWalletType;
+  /** The sheet's answer: the wallet key, or `null` when the buyer closed it. */
+  answer: Promise<string | null>;
+  cents: number;
+  /** Close the sheet with the charge's outcome — Apple's sheet waits for it; Google's closes itself. */
+  complete?: (accepted: boolean) => void;
+  /** A runner took the sheet: it, not the list, closes it. */
+  claimed?: boolean;
+}
+
+/** The sentence for a wallet charge that could not go out. */
+function useRefusedWords(type: CheckoutWalletType): string {
+  const words = useCheckoutCopy().screens.wallet;
+  return type === "APPLE_PAY" ? (words.applePay.paymentFailed ?? words.applePay.cannotComplete) : words.googlePay.cannotComplete;
+}
+
 /**
- * Google Pay: the sheet was opened INSIDE the buyer's tap (`sheet`, priced at
- * `sheetCents`) while the order was raised; its key is charged against that
- * order only if the order asks the provider for what the sheet showed — its
- * amount due, which a balance the host holds may have made less than its
- * total. A closed sheet sends nothing more.
+ * A wallet — Google Pay or Apple Pay (FUT-3685): the sheet was opened INSIDE
+ * the buyer's tap, priced at `sheet.cents`, while the order was raised; its
+ * key is charged against that order only if the order asks the provider for
+ * what the sheet showed — its amount due, which a balance the host holds may
+ * have made less than its total (R4). A closed sheet sends nothing more.
  */
 export function WalletRun({
   order,
   buyer,
   sheet,
-  sheetCents,
   scope,
   onResolved,
   pollIntervalMs,
@@ -141,28 +159,34 @@ export function WalletRun({
 }: RunnerCallbacks & {
   order: CheckoutOrder;
   buyer: BuyerInfo;
-  /** The sheet's answer: the wallet key, or `null` when the buyer closed it. */
-  sheet: Promise<string | null>;
-  sheetCents: number;
+  sheet: WalletSheet;
   scope: ChallengeScope;
   onResolved: OnCheckoutResolved;
   pollIntervalMs: number;
 }): JSX.Element | null {
-  const words = useCheckoutCopy().screens.wallet.googlePay;
+  const refusedWords = useRefusedWords(sheet.type);
   const wallet = useWalletCharge(order, buyer, onResolved, pollIntervalMs, scope);
   useFireOnce(true, () => {
-    const refused = { message: words.cannotComplete, code: null };
-    sheet
-      .then((key) => {
+    sheet.claimed = true;
+    const refused = { message: refusedWords, code: null };
+    sheet.answer
+      .then(async (key) => {
         if (key === null) return onFailed(null);
         // The sheet showed one amount; never charge another under it.
-        if ((order.amountDueCents ?? order.totalCents) !== sheetCents) {
-          warnMissingAmountDue(order, sheetCents);
+        if ((order.amountDueCents ?? order.totalCents) !== sheet.cents) {
+          warnMissingAmountDue(order, sheet.cents, sheet.type);
+          sheet.complete?.(false);
           return onFailed(refused);
         }
-        return void wallet.payWithKey("GOOGLE_PAY", key);
+        // Charged FIRST, then the sheet told: `complete?.(await …)` would skip
+        // the charge itself for a sheet with nothing to complete (Google's).
+        const accepted = await wallet.payWithKey(sheet.type, key);
+        sheet.complete?.(accepted);
       })
-      .catch(() => onFailed(refused));
+      .catch(() => {
+        sheet.complete?.(false);
+        onFailed(refused);
+      });
   });
   const { error, errorCode, phase } = wallet;
   useEffect(() => {

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

@@ -3,7 +3,6 @@ import { useId, type JSX, type ReactNode } from "react";
 
 import { useCheckoutCopy } from "../copy-context";
 import type { BuyerInfo } from "../types";
-import { useCheckoutComponents } from "../ui";
 
 import { cardName, type OnlineRow } from "./choice";
 import type { ListChargeFailure } from "./charge-runners";
@@ -66,6 +65,7 @@ function OnlineOptionRow({ row, props }: { row: OnlineRow; props: RowProps }): J
     >
       {opensContent(row.method, state.asked, props.failure, props.covered) ? (
         <OnlineContent
+        withConsent={!state.top}
         method={row.method}
         asked={state.asked}
         buyer={props.buyer}
@@ -85,6 +85,12 @@ function OnlineOptionRow({ row, props }: { row: OnlineRow; props: RowProps }): J
 function DoorOptionRow({ option, props }: { option: CheckoutDoorOption; props: RowProps }): JSX.Element {
   const { choice } = props.state;
   const chosen = choice?.kind === "door" && choice.id === option.id;
+  const choose = (): void => {
+    if (!chosen) props.state.choose({ kind: "door", id: option.id });
+  };
+  // A function content gets the row's own controls (FUT-3715): a chip inside
+  // it can choose the row in the tap that answers it.
+  const content = typeof option.content === "function" ? option.content({ chosen, choose }) : option.content;
   return (
     <OptionRow
       name={props.name}
@@ -92,14 +98,18 @@ function DoorOptionRow({ option, props }: { option: CheckoutDoorOption; props: R
       chosen={chosen}
       label={option.label}
       hint={chosen && option.hideHintWhileChosen ? undefined : option.hint}
-      onChoose={() => props.state.choose({ kind: "door", id: option.id })}
+      onChoose={choose}
       testId={`list-door-${option.id}`}
+      open={option.showContentWhileIdle === true}
     >
-      {option.content}
+      {content}
     </OptionRow>
   );
 }
 
+/** Read by a screen reader, not drawn. */
+const VISUALLY_HIDDEN = { position: "absolute", width: "1px", height: "1px", m: 0, overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" } as const;
+
 /** One heading and the rows under it, as a group named by the heading. */
 function Group({ id, heading, children }: { id: string; heading: string; children: ReactNode }): JSX.Element {
   return (
@@ -113,7 +123,9 @@ function Group({ id, heading, children }: { id: string; heading: string; childre
 /**
  * "Como você quer pagar?" — every way to pay as ONE radio group under two
  * headings (FUT-3591, M6): the store's online options, then the host's door
- * options. Choosing a row only chooses it; the bar's button acts.
+ * options. Choosing a row only chooses it; the bar's button acts. Above them,
+ * `top`: the CPF and the wallet block (FUT-3685), which are not part of the
+ * group (R1).
  *
  * One radio `name` across both groups keeps them one choice for the keyboard;
  * each heading names its own `role="group"`, and what opens inside a row sits
@@ -122,13 +134,15 @@ function Group({ id, heading, children }: { id: string; heading: string; childre
 export function ChoiceList({
   door,
   locked,
+  top,
   ...rest
 }: Omit<RowProps, "name"> & {
   door: readonly CheckoutDoorOption[];
   /** A charge or a send is under way: the list is inert. */
   locked: boolean;
+  /** The CPF and the wallets, above the rows (FUT-3685) — inert with them. */
+  top?: ReactNode;
 }): JSX.Element {
-  const { Text } = useCheckoutComponents();
   const base = useId();
   const props: RowProps = { ...rest, name: `${base}-choice` };
   const { copy, state } = props;
@@ -138,11 +152,15 @@ export function ChoiceList({
       data-locked={locked ? "true" : "false"}
       aria-disabled={locked || undefined}
       inert={locked || undefined}
+      aria-labelledby={`${base}-title`}
       sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}
     >
-      <Text variant="body" size="md" weight="bold" as="p" style={{ margin: 0 }}>
+      {/* The list's name, for a screen reader: the step's own heading is what a
+          sighted buyer reads (the host's "Pagamento" card, T1). */}
+      <Box component="p" id={`${base}-title`} sx={VISUALLY_HIDDEN}>
         {copy.title}
-      </Text>
+      </Box>
+      {top}
       {/* Each heading only over a group that has rows (a door-only store shows the door one alone). */}
       {state.rows.length > 0 ? (
         <Group id={`${base}-online`} heading={copy.onlineHeading}>

package/src/components/checkout/list/choice.ts

@@ -37,14 +37,13 @@ export interface OnlineCapability {
   /** The methods the chain declares, or `null` while unknown (fails OPEN). */
   offered: PaymentMethod[] | null;
   cardUnavailable: boolean;
-  /** Google Pay is declared AND this browser's `isReadyToPay` said yes. */
-  googlePayReady: boolean;
 }
 
 /**
- * The "PAGAR AGORA, PELO APP" rows, in the prototype's order: Pix, card,
- * Google Pay — or the single hand-off row for a store that takes the method
- * on its own page (N18).
+ * The "PAGAR AGORA, PELO APP" rows, in the prototype's order: Pix, then the
+ * card — or the single hand-off row for a store that takes the method on its
+ * own page (N18). The wallets are not rows: they are buttons in the block
+ * above the list (FUT-3685, R1), and pressing one never changes the choice.
  */
 export function onlineRows(cap: OnlineCapability): OnlineRow[] {
   if (cap.handOff) return [{ method: "HAND_OFF", disabled: false }];
@@ -52,7 +51,6 @@ export function onlineRows(cap: OnlineCapability): OnlineRow[] {
   const rows: OnlineRow[] = [];
   if (offers("PIX")) rows.push({ method: "PIX", disabled: false });
   if (offers("CARD")) rows.push({ method: "CARD", disabled: cap.cardUnavailable });
-  if (offers("CARD") && !cap.cardUnavailable && cap.googlePayReady) rows.push({ method: "GOOGLE_PAY", disabled: false });
   return rows;
 }
 

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

@@ -0,0 +1,98 @@
+import { Box } from "@mui/material";
+import { useEffect, useRef, type JSX } from "react";
+
+import { formatCpf, validateCpf } from "../../../card";
+import { fieldSatisfied } from "../buyer-fields";
+import { useCheckoutCopy } from "../copy-context";
+import { useCheckoutLayout } from "../payment-step-layout";
+import type { BuyerInfo, CheckoutCustomerField } from "../types";
+import { useCheckoutComponents } from "../ui";
+
+import { PLACEHOLDERS, complaintOf, useOnComplete } from "./buyer-inline";
+import { usePaymentListMode } from "./context";
+import type { PaymentListCopy } from "./types";
+
+/** The prototype's 280px CPF field on a computer (L7), on the theme's spacing scale. */
+const FIELD_WIDE_MAX = 35;
+
+/**
+ * The CPF at the TOP of Pagamento, above the wallets (FUT-3685, C3, C4, E1,
+ * L7): "CPF", the provider's reason under it ("o PagBank pede para pagar pelo
+ * app"), the field — masked, checked by its digits — and "Salvar meus dados
+ * para a próxima compra". Asked once, for every online way to pay the list
+ * offers (R2); full width on a phone, ~280px on a computer.
+ *
+ * When the CPF is complete, `onComplete` fires once — the list moves the focus
+ * to "Número do cartão" when a card typed now is chosen.
+ */
+export function CpfTop({ field, buyer, onBuyerChange, copy, provider, onComplete, focusOnMount = false, onKeepSaved }: {
+  field: CheckoutCustomerField;
+  buyer: BuyerInfo;
+  onBuyerChange: (buyer: BuyerInfo) => void;
+  copy: PaymentListCopy["buyer"];
+  provider: string | null;
+  onComplete?: () => void;
+  /** Opened by "Alterar" on the payer line: the field takes the focus as it appears. */
+  focusOnMount?: boolean;
+  /** Opened over a CPF on file: "Manter o CPF salvo" closes it and keeps that CPF. */
+  onKeepSaved?: () => void;
+}): JSX.Element {
+  const { Button, Checkbox, Input, Text } = useCheckoutComponents();
+  const consent = usePaymentListMode()?.consent;
+  const fieldCopy = useCheckoutCopy().card.fields;
+  const wide = useCheckoutLayout()?.wide ?? false;
+  // The CPF the store already holds, when the host passed it, shown masked and editable.
+  const value = formatCpf(buyer.taxId ?? "");
+  useOnComplete(value.trim() !== "" && fieldSatisfied(field, value), onComplete);
+  const scope = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (focusOnMount) scope.current?.querySelector<HTMLInputElement>("input")?.focus();
+  }, [focusOnMount]);
+  const complaint = complaintOf(field, value, copy, (typed) => validateCpf(typed, fieldCopy));
+  return (
+    <Box ref={scope} data-testid="list-cpf" sx={{ display: "flex", flexDirection: "column", gap: 1.25 }}>
+      {/* A native <label> around the words and the field names the input with both. */}
+      <Box component="label" sx={{ display: "flex", flexDirection: "column", gap: 0.75 }}>
+        <Box component="span" sx={{ display: "flex", flexDirection: "column" }}>
+          <Text variant="body" size="sm" as="span">
+            {copy.cpf}
+          </Text>
+          <Text variant="body" size="sm" color="secondary" as="span">
+            {copy.cpfHint(provider)}
+          </Text>
+        </Box>
+        <Box sx={{ width: "100%", maxWidth: (t) => (wide ? t.spacing(FIELD_WIDE_MAX) : "none") }}>
+          <Input
+            type="text"
+            inputMode="numeric"
+            variant="outlined"
+            size="md"
+            fullWidth
+            required={field.required}
+            placeholder={PLACEHOLDERS.taxId}
+            value={value}
+            error={Boolean(complaint)}
+            helperText={complaint}
+            onChange={(event) => onBuyerChange({ ...buyer, taxId: formatCpf(event.target.value) })}
+            data-testid="list-buyer-taxId"
+          />
+        </Box>
+      </Box>
+      {onKeepSaved && copy.keepSavedCpf ? (
+        <Box sx={{ alignSelf: "flex-start", ml: -1 }}>
+          <Button variant="text" color="primary" size="sm" onClick={onKeepSaved} dataTestId="list-cpf-keep">
+            {copy.keepSavedCpf}
+          </Button>
+        </Box>
+      ) : null}
+      {consent ? (
+        <Checkbox
+          label={consent.label}
+          checked={consent.checked}
+          onChange={(_event, checked) => consent.onChange(checked)}
+          data-testid="list-save-profile"
+        />
+      ) : null}
+    </Box>
+  );
+}

package/src/components/checkout/list/en-US.ts

@@ -12,6 +12,12 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
     hintNew: "Enter your card details",
   },
   googlePay: { label: "Google Pay", hint: "With the card saved in your Google account" },
+  wallets: {
+    heading: "Quick payment",
+    googlePay: "Pay with Google Pay",
+    applePay: "Pay with Apple Pay",
+    or: "or choose how to pay",
+  },
   handOff: {
     label: "Pix or card",
     hint: (provider) =>
@@ -25,6 +31,8 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
     name: "Name",
     email: "Email",
     why: (provider) => (provider ? `(${provider} asks for it to pay in the app)` : "(needed to pay in the app)"),
+    cpfHint: (provider) => (provider ? `${provider} asks for it to pay in the app` : "needed to pay in the app"),
+    keepSavedCpf: "Keep the saved CPF",
     cpfIncomplete: "A CPF has 11 digits.",
     phoneIncomplete: "The mobile number needs the area code and 9 digits.",
   },