@12-apps/payments-frontend 3.43.1 → 3.44.0

package/src/components/checkout/list/payment-list-step.tsx

@@ -1,8 +1,9 @@
-import { useCallback, useEffect, useMemo, useState, type JSX } from "react";
+import { useCallback, useEffect, useMemo, useState, type JSX, type ReactNode } from "react";
 
 import type { CheckoutBasketIdentity } from "../basket";
 import { CartChangedBoundary } from "../cart-changed";
 import { displayTotals } from "../checkout-totals";
+import type { CheckoutSummaryLine } from "../payment-summary";
 import { usePaymentPixStage } from "../payment-step-layout";
 import { PixStageProvider } from "../pix-stage";
 import { PixView } from "../pix-view";
@@ -13,6 +14,7 @@ import type { useCheckoutController } from "../use-checkout-controller";
 import { PaymentListProvider } from "./context";
 import { ListBar, WaitingLine } from "./list-bar";
 import { ListFace } from "./list-face";
+import { ListLayout } from "./summary-column";
 import type { ListCapability } from "./use-capability";
 import type { ListCharge } from "./use-list-charge";
 import type { ListState } from "./use-list-state";
@@ -26,7 +28,15 @@ type Controller = ReturnType<typeof useCheckoutController>;
 interface PaymentListStepProps {
   c: Controller;
   list: CheckoutPaymentList;
-  cart: { totalLabel: string; totalItems: number; identity?: CheckoutBasketIdentity };
+  cart: {
+    totalLabel: string;
+    totalItems: number;
+    identity?: CheckoutBasketIdentity;
+    /** The cart's lines, for the "Resumo do pedido" column on a computer (L4). */
+    lines?: CheckoutSummaryLine[];
+    /** The host's fee and discount rows, for the same column. */
+    discountLines?: ReactNode;
+  };
   /** Settling a balance: its totals win, and its basket is no signal. */
   totalOverride?: { label: string; items: number };
   providerConfig: CheckoutProviderConfig | null | undefined;
@@ -38,6 +48,11 @@ interface PaymentListStepProps {
   /** The Dados step's consent sentence — the list asks it beside the details it asks. */
   consentLabel: string;
   pollIntervalMs?: number;
+  /**
+   * The host's Apple Pay merchant-validation port (FUT-472), server-side.
+   * Without it the list offers no Apple Pay: its session could only abort.
+   */
+  validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
 }
 
 /** The store's provider name, as its chain head published it — `null` when it did not. */
@@ -80,13 +95,29 @@ function usePreferMethod(c: Controller, choose: ListState["choose"]): (method: P
   );
 }
 
+/**
+ * "Alterar" on the payer line opens the CPF at the top (E2 → E1); "Manter o
+ * CPF salvo" closes it, putting back the CPF the buyer arrived with — a CPF
+ * typed in between is dropped, never sent.
+ */
+function useReveal(c: Controller, arrivedWith: BuyerInfo | undefined) {
+  const [revealed, setRevealed] = useState(false);
+  const { buyer, setBuyer } = c;
+  const onKeepSavedCpf = useCallback(() => {
+    setBuyer({ ...buyer, taxId: arrivedWith?.taxId });
+    setRevealed(false);
+  }, [buyer, setBuyer, arrivedWith]);
+  return useMemo(() => ({ revealed, onRevealCpf: () => setRevealed(true), onKeepSavedCpf }), [revealed, onKeepSavedCpf]);
+}
+
 /** The list face, with what the step gathered for it. */
-function ListFaceFor({ props, state, charge, cap, onHandOff }: {
+function ListFaceFor({ props, state, charge, cap, onHandOff, reveal }: {
   props: PaymentListStepProps;
   state: ListState;
   charge: ListCharge;
   cap: ListCapability;
   onHandOff: () => void;
+  reveal: { revealed: boolean; onRevealCpf: () => void; onKeepSavedCpf: () => void };
 }): JSX.Element {
   const { c, cart, totalOverride } = props;
   const config = props.providerConfig ?? null;
@@ -106,6 +137,9 @@ function ListFaceFor({ props, state, charge, cap, onHandOff }: {
       pollIntervalMs={props.pollIntervalMs ?? 2500}
       saveBuyerContact={props.saveBuyerContact}
       onHandOff={onHandOff}
+      revealed={reveal.revealed}
+      onRevealCpf={reveal.onRevealCpf}
+      onKeepSavedCpf={reveal.onKeepSavedCpf}
     />
   );
 }
@@ -122,7 +156,9 @@ function ListFaceFor({ props, state, charge, cap, onHandOff }: {
 export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
   const { c, list } = props;
   const config = props.providerConfig ?? null;
-  const cap = useListCapability(config, list.totalCents);
+  const cap = useListCapability(config, list.totalCents, props.validateApplePayMerchant);
+  const reveal = useReveal(c, props.defaultBuyer);
+  const { revealed } = reveal;
   const state = useListState({
     config,
     capability: cap,
@@ -132,6 +168,8 @@ export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
     taxIdOnFile: props.taxIdOnFile,
     lastMethod: list.lastMethod,
     onChoiceChange: list.onChoiceChange,
+    wallets: cap.wallets,
+    revealed,
   });
   const charge = useListCharge({ ...c, cartTotal: displayTotals(props.totalOverride, props.cart).label, dueCents: list.totalCents });
   const [handingOff, startHandOff] = useHandingOff(c.createError);
@@ -146,7 +184,14 @@ export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
   ) : handingOff ? (
     <HandOffFace props={props} method={c.method ?? "PIX"} />
   ) : (
-    <ListFaceFor props={props} state={state} charge={charge} cap={cap} onHandOff={startHandOff} />
+    <ListLayout
+      hostTarget={list.summaryTarget}
+      lines={props.totalOverride ? undefined : props.cart.lines}
+      moneyLines={props.cart.discountLines}
+      totalLabel={displayTotals(props.totalOverride, props.cart).label}
+    >
+      <ListFaceFor props={props} state={state} charge={charge} cap={cap} onHandOff={startHandOff} reveal={reveal} />
+    </ListLayout>
   );
   return (
     <PaymentListProvider list={list} onLeavePix={c.dropOrder} consent={consent}>

package/src/components/checkout/list/pt-BR.ts

@@ -28,6 +28,12 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
     hintNew: "Digite os dados do cartão",
   },
   googlePay: { label: "Google Pay", hint: "Com o cartão salvo no seu Google" },
+  wallets: {
+    heading: "Pagamento rápido",
+    googlePay: "Pagar com Google Pay",
+    applePay: "Pagar com Apple Pay",
+    or: "ou escolha como pagar",
+  },
   handOff: {
     label: "Pix ou cartão",
     hint: (provider) =>
@@ -41,6 +47,8 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
     name: "Nome",
     email: "E-mail",
     why: (provider) => (provider ? `(${the(provider)} pede para pagar pelo app)` : "(pedido para pagar pelo app)"),
+    cpfHint: (provider) => (provider ? `${the(provider)} pede para pagar pelo app` : "pedido para pagar pelo app"),
+    keepSavedCpf: "Manter o CPF salvo",
     cpfIncomplete: "O CPF tem 11 dígitos.",
     phoneIncomplete: "O celular precisa de DDD e 9 dígitos.",
   },

package/src/components/checkout/list/summary-column.tsx

@@ -0,0 +1,120 @@
+import { Box } from "@mui/material";
+import { createContext, useContext, useMemo, useState, type JSX, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+import { useCheckoutCopy } from "../copy-context";
+import { SummaryLines, SummaryTotal, type CheckoutSummaryLine } from "../payment-summary";
+import { useCheckoutLayout } from "../payment-step-layout";
+import { useCheckoutComponents } from "../ui";
+
+/**
+ * Where the bar's content goes on a computer (FUT-3685, L4): into the
+ * "Resumo do pedido" column — an element the column draws, which the bar's
+ * content is portalled into — or `null` on a phone, where the bar stays the
+ * host's sticky `ActionBar` (L2).
+ */
+const ColumnTarget = createContext<{ element: HTMLElement | null } | null>(null);
+
+const SummaryColumnTarget = ColumnTarget.Provider;
+
+/**
+ * `null` for the bar (a phone); otherwise the column's element to portal the
+ * bar's content into — itself `null` for the one render before the column
+ * mounts, when nothing is drawn rather than a bar that would flash.
+ */
+export function useSummaryColumnTarget(): { element: HTMLElement | null } | null {
+  return useContext(ColumnTarget);
+}
+
+/** The prototype's 680px steps column and 360px summary column, on the theme's spacing scale. */
+const STEPS_MAX = 85;
+const COLUMN_WIDTH = 45;
+
+/**
+ * The computer's two columns (L4): the steps on the left, at most ~680px, and
+ * the "Resumo do pedido" column on the right, ~360px, holding the lines, the
+ * fees, "Total", the host's context line and the pay button — so no bar sits
+ * at the bottom of the screen.
+ */
+function TwoColumns({ steps, column }: { steps: ReactNode; column: ReactNode }): JSX.Element {
+  return (
+    <Box data-testid="list-columns" sx={{ display: "flex", gap: 4, alignItems: "flex-start", justifyContent: "center", width: "100%" }}>
+      <Box sx={{ flex: 1, minWidth: 0, maxWidth: (t) => t.spacing(STEPS_MAX) }}>{steps}</Box>
+      <Box sx={{ flex: "none", width: (t) => t.spacing(COLUMN_WIDTH), position: "sticky", top: (t) => t.spacing(3) }}>{column}</Box>
+    </Box>
+  );
+}
+
+/**
+ * "Resumo do pedido" (T20): the cart's lines and the host's money rows (fees,
+ * discounts) as the host words them, a hairline, "Total" and the amount — and
+ * under them `slot`, the element the bar's content is portalled into.
+ */
+function SummaryColumn({ lines, moneyLines, totalLabel, slot }: {
+  lines?: CheckoutSummaryLine[];
+  /** The host's fee and discount rows (`CheckoutCartView.discountLines`). */
+  moneyLines?: ReactNode;
+  totalLabel: string;
+  slot: (element: HTMLElement | null) => void;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.layout;
+  const shown = lines ?? [];
+  return (
+    <Box
+      component="aside"
+      aria-label={copy.summaryTitle}
+      data-testid="list-summary-column"
+      sx={{ display: "flex", flexDirection: "column", gap: 1.75, p: 2.75, bgcolor: "background.paper", border: "1px solid", borderColor: "divider", borderRadius: 3.5 }}
+    >
+      <Text variant="heading" size="md" weight="bold" as="h2" style={{ margin: 0 }}>
+        {copy.summaryTitle}
+      </Text>
+      {shown.length > 0 ? <SummaryLines lines={shown} /> : null}
+      {moneyLines ? <Box data-testid="list-summary-money">{moneyLines}</Box> : null}
+      <Box sx={{ height: "1px", bgcolor: "divider" }} />
+      <SummaryTotal totalLabel={totalLabel} />
+      <Box ref={slot} data-testid="list-summary-action" sx={{ display: "flex", flexDirection: "column" }} />
+    </Box>
+  );
+}
+
+/**
+ * The list face's layout (FUT-3685, L4), in one of three shapes:
+ *
+ *  - the HOST lays out the page (`hostTarget` given — `paymentList.summaryTarget`):
+ *    the "Resumo do pedido" column is portalled into the host's element, beside
+ *    the host's own step cards, and the bar's action lands in it. While the
+ *    element is `null` (not mounted yet) the bar draws nothing rather than flash;
+ *  - a computer, the host silent: the step and the column side by side, here;
+ *  - a phone: the step alone, over the host's bar (L2).
+ *
+ * Only the list face is laid out this way: the Pix screen and the hand-off keep
+ * their bar (K9).
+ */
+export function ListLayout({ hostTarget, lines, moneyLines, totalLabel, children }: {
+  hostTarget: HTMLElement | null | undefined;
+  lines?: CheckoutSummaryLine[];
+  moneyLines?: ReactNode;
+  totalLabel: string;
+  children: ReactNode;
+}): JSX.Element {
+  const wide = useCheckoutLayout()?.wide ?? false;
+  const [slot, setSlot] = useState<HTMLElement | null>(null);
+  const target = useMemo(() => ({ element: slot }), [slot]);
+  const column = <SummaryColumn lines={lines} moneyLines={moneyLines} totalLabel={totalLabel} slot={setSlot} />;
+  if (hostTarget !== undefined) {
+    return (
+      <SummaryColumnTarget value={target}>
+        {children}
+        {hostTarget ? createPortal(column, hostTarget) : null}
+      </SummaryColumnTarget>
+    );
+  }
+  if (!wide) return <>{children}</>;
+  return (
+    <SummaryColumnTarget value={target}>
+      <TwoColumns steps={children} column={column} />
+    </SummaryColumnTarget>
+  );
+}

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

@@ -0,0 +1,94 @@
+/**
+ * The CPF asked ONCE, at the top of the Pagamento step (FUT-3685, contract E1,
+ * E2, E3, R2, R3).
+ *
+ * PagBank charges a wallet as a card and requires the buyer's tax id on every
+ * order, and neither wallet's sheet can supply one. So the CPF cannot wait
+ * inside the chosen row any more: a wallet button is pressed with no row
+ * chosen at all. It is asked above the wallets, when ANY way to pay the list
+ * offers online needs it under the chain rule (FUT-526) — the union over the
+ * offered methods, never the chosen row (R2) — and it gates the online ways to
+ * pay only: a door row never needs it (R3).
+ *
+ * Every other field a method asks for (the hand-off provider's mobile, K4)
+ * stays inside its own row.
+ */
+import { buyerFieldsFor, fieldSatisfied } from "../buyer-fields";
+import type { BuyerInfo, CheckoutChainLink, CheckoutCustomerField, PaymentMethod } from "../types";
+
+/** Whether a field asks for the buyer's CPF. */
+export function isTaxId(field: Pick<CheckoutCustomerField, "key">): boolean {
+  return field.key === "taxId";
+}
+
+/** The required CPF the chain asks for under any of `methods`, or `null` when none does. */
+function requiredTaxId(
+  chain: readonly CheckoutChainLink[] | undefined,
+  methods: readonly PaymentMethod[],
+): CheckoutCustomerField | null {
+  for (const method of methods) {
+    const field = buyerFieldsFor(chain, method).find((candidate) => isTaxId(candidate) && candidate.required);
+    if (field) return field;
+  }
+  return null;
+}
+
+/**
+ * The CPF field the top of Pagamento shows, or `null` for none (E1, E2).
+ *
+ *  - Decided against what the buyer ARRIVED with, never what they are typing,
+ *    so the field does not vanish under their thumb as it completes.
+ *  - A buyer with a CPF on file sees no field — until they press "Alterar" on
+ *    the payer line (`revealed`, E2 → E1). That field opens holding the CPF
+ *    the host passed (masked, editable) and is OPTIONAL: empty means "keep the
+ *    CPF the store holds" — a host that does not pass it (the field opens
+ *    empty) must not strand the buyer — and only a non-empty CPF that is not
+ *    valid holds the online ways to pay, with the reason (E3, K6). "Manter o
+ *    CPF salvo" closes it again.
+ */
+export function topCpfField(input: {
+  chain: readonly CheckoutChainLink[] | undefined;
+  /** Every online method the list offers, wallets included (they raise a CARD order). */
+  methods: readonly PaymentMethod[];
+  arrivedWith: BuyerInfo | undefined;
+  taxIdOnFile: boolean;
+  revealed: boolean;
+}): CheckoutCustomerField | null {
+  const field = requiredTaxId(input.chain, input.methods);
+  if (!field) return null;
+  if (input.taxIdOnFile) return input.revealed ? { ...field, required: false } : null;
+  if (fieldSatisfied(field, input.arrivedWith?.taxId)) return null;
+  return field;
+}
+
+/**
+ * Whether the top CPF holds a payment raised with `method`: the method's own
+ * chain needs it and it is not satisfied — or the buyer typed one that is not
+ * valid, which would go out with any online payment.
+ */
+export function cpfHolds(
+  top: CheckoutCustomerField | null,
+  buyer: BuyerInfo,
+  chain: readonly CheckoutChainLink[] | undefined,
+  method: PaymentMethod,
+): boolean {
+  if (!top || fieldSatisfied(top, buyer.taxId)) return false;
+  const typed = (buyer.taxId ?? "").trim() !== "";
+  return typed || requiredTaxId(chain, [method]) !== null;
+}
+
+/**
+ * The provider the hint names — "o PagBank pede para pagar pelo app" (T3): the
+ * first chain member that asks for the CPF under one of `methods` (or declares
+ * nothing, which reads as asking for it), else the chain head. `null` when the
+ * member published no name.
+ */
+export function cpfProvider(
+  chain: readonly CheckoutChainLink[] | undefined,
+  methods: readonly PaymentMethod[],
+): string | null {
+  const asks = (link: CheckoutChainLink): boolean =>
+    link.customerSchema === undefined || requiredTaxId([link], methods) !== null;
+  const link = chain?.find(asks) ?? chain?.[0];
+  return link?.displayName?.trim() || null;
+}

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

@@ -62,7 +62,12 @@ export interface CheckoutDoorOption {
   onSend: () => void;
 }
 
-/** The online ways to pay the list may offer, as the host is told about them. */
+/**
+ * The online ways to pay the list may offer, as the host is told about them.
+ * `"GOOGLE_PAY"` is never reported any more: the wallets are buttons above the
+ * list, not rows (FUT-3685). It stays in the union so a host's exhaustive
+ * switch still compiles.
+ */
 export type CheckoutOnlineChoice = "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
 
 /** What the buyer has chosen in the list. */
@@ -104,15 +109,14 @@ export interface CheckoutPaymentList {
   /**
    * The amount an ONLINE payment will ask the provider for, in integer cents —
    * the cart's total, or what is left of it after a balance the host holds
-   * (store credit). It is what Google Pay's sheet is priced with, since that
-   * sheet must open INSIDE the tap, before any order exists to read a price
-   * from. Never given, or zero (a balance covers everything) ⇒ no Google Pay
-   * row, and a Google Pay choice is dropped. Once given, a moment without it
-   * (the host re-pricing) keeps a chosen Google Pay with its button held —
-   * plainly, with `copy.reasons.repricing` — until it returns. The key is
-   * refused if the order raised behind the sheet asks the provider for another
-   * amount (`CheckoutOrder.amountDueCents`, else its total) — so a host that
-   * takes a balance off the charge MUST answer `amountDueCents`.
+   * (store credit). It is what the wallets' sheets are priced with (FUT-3685),
+   * since a sheet must open INSIDE the tap, before any order exists to read a
+   * price from. Never given, or zero (a balance covers everything) ⇒ no wallet
+   * buttons. Once given, a moment without it (the host re-pricing) keeps their
+   * place, held — plainly, with `copy.reasons.repricing` — until it returns. A
+   * key is refused if the order raised behind the sheet asks the provider for
+   * another amount (`CheckoutOrder.amountDueCents`, else its total) — so a host
+   * that takes a balance off the charge MUST answer `amountDueCents`.
    */
   totalCents?: number;
   /**
@@ -168,6 +172,17 @@ export interface CheckoutPaymentList {
   pixBank?: CheckoutPixBank;
   /** Says a short sentence in the host's own toast — "Código Pix copiado". */
   notify?: (message: string) => void;
+  /**
+   * The host lays out the computer's two columns itself (FUT-3685, L4): its
+   * step cards on the left, and this element on the right — the list portals
+   * the "Resumo do pedido" column into it (the lines, the money rows, "Total",
+   * `summary`, the extras and the pay button), so no bar is drawn at the
+   * bottom. `null` while the element is not mounted yet: the bar waits rather
+   * than flash. Leave it OUT (undefined) on a phone, or to keep the list's own
+   * layout — the step and the column side by side once the flow's frame is
+   * wide, the bar otherwise. The Pix screen and the hand-off keep their bar.
+   */
+  summaryTarget?: HTMLElement | null;
 }
 
 /** The six banks the Pix face offers to open, in the prototype's order. */
@@ -240,7 +255,26 @@ export interface PaymentListCopy {
     /** "Digite os dados do cartão". */
     hintNew: string;
   };
+  /**
+   * @deprecated Google Pay is no longer a row (FUT-3685): it is a button in
+   * the "PAGAMENTO RÁPIDO" block — see {@link PaymentListCopy.wallets}. Kept so
+   * a host's own pack still type-checks; nothing draws it.
+   */
   googlePay: { label: string; hint: string };
+  /**
+   * The "PAGAMENTO RÁPIDO" block above the list (FUT-3685, T5–T8): the wallet
+   * buttons' accessible names and the words around them.
+   */
+  wallets: {
+    /** "Pagamento rápido" — drawn in capitals by CSS. */
+    heading: string;
+    /** "Pagar com Google Pay". */
+    googlePay: string;
+    /** "Pagar com Apple Pay". */
+    applePay: string;
+    /** "ou escolha como pagar" — the divider between the wallets and the rows. */
+    or: string;
+  };
   handOff: {
     label: string;
     /** "Você paga na página da InfinitePay e volta" — `null` when the store published no name. */
@@ -258,6 +292,17 @@ export interface PaymentListCopy {
     email: string;
     /** "(o PagBank pede para pagar pelo app)" — `null` when no name was published. */
     why: (provider: string | null) => string;
+    /**
+     * The line under "CPF" at the top of Pagamento (FUT-3685, T3) — "o PagBank
+     * pede para pagar pelo app"; `null` when no name was published.
+     */
+    cpfHint: (provider: string | null) => string;
+    /**
+     * The link under the CPF opened by "Alterar" over a CPF on file, closing it
+     * again — "Manter o CPF salvo" (FUT-3685). Both packs carry it; absent ⇒ no
+     * link (an empty field keeps the saved CPF either way).
+     */
+    keepSavedCpf?: string;
     cpfIncomplete: string;
     phoneIncomplete: string;
   };

package/src/components/checkout/list/use-capability.ts

@@ -1,58 +1,136 @@
-import { useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 
+import { applePaySessionClass, applePaySupported, type ApplePaySessionClass } from "../apple-pay-button";
 import { useGooglePayClient, type GooglePayGatewayParams, type GooglePaymentsClient } from "../google-pay-button";
-import { cardPathAvailable, googlePayConfig, offeredMethods } from "../method-capability";
+import { applePayDeclared, cardPathAvailable, googlePayConfig, offeredMethods } from "../method-capability";
 import { methodChosenAtProvider } from "../providers/registry";
-import type { CheckoutProviderConfig } from "../types";
+import type { CheckoutProviderConfig, PaymentMethod } from "../types";
 
 import type { OnlineCapability } from "./choice";
 
-/** What the store's chain lets THIS browser offer in the list, Google Pay's client included. */
+/** Apple Pay, ready to start a session inside the tap. */
+export interface ListApplePay {
+  Session: ApplePaySessionClass;
+  /** The host's merchant-validation port (server-side). */
+  validateMerchant: (validationURL: string) => Promise<unknown>;
+}
+
+/** What the store's chain lets THIS browser offer in the list, the wallets included. */
 export interface ListCapability extends OnlineCapability {
-  /** Google Pay, ready to open its sheet — `null` when there is no row, or while the host re-prices. */
+  /** Google Pay, ready to open its sheet — `null` when it is not offered, or while the host re-prices. */
   googlePay: { client: GooglePaymentsClient; params: GooglePayGatewayParams } | null;
+  /** Apple Pay, ready to start its session — `null` when it is not offered, or while the host re-prices. */
+  applePay: ListApplePay | null;
+  /**
+   * The wallets the "PAGAMENTO RÁPIDO" block draws, in the prototype's order.
+   * A wallet drawn while the host re-prices has its button held
+   * (`googlePay`/`applePay` is `null` for that moment).
+   */
+  wallets: ListWallet[];
+}
+
+export type ListWallet = "GOOGLE_PAY" | "APPLE_PAY";
+
+/**
+ * The host priced the sheet once and, for a moment, has no price (re-pricing:
+ * the credit was toggled) — a wallet keeps its place, held, until the price
+ * returns. An explicit zero (a balance covers everything) withdraws it.
+ */
+function useRepricing(totalCents: number | undefined): { priced: boolean; repricing: boolean } {
+  const priced = totalCents !== undefined && totalCents > 0;
+  const [wasPriced, setWasPriced] = useState(false);
+  if (priced && !wasPriced) setWasPriced(true);
+  if (totalCents === 0 && wasPriced) setWasPriced(false);
+  return { priced, repricing: totalCents === undefined && wasPriced };
+}
+
+/** Apple Pay's session class, when the chain head declares the wallet and this device can pay (R5). */
+function appleSession(config: CheckoutProviderConfig | null, port: ListApplePay["validateMerchant"] | undefined): ListApplePay | null {
+  if (!port || !applePayDeclared(config) || !applePaySupported()) return null;
+  const Session = applePaySessionClass();
+  return Session ? { Session, validateMerchant: port } : null;
+}
+
+/** Whether the card is offered and available on THIS page — what a wallet is another way of producing. */
+function cardHere(handOff: boolean, offered: PaymentMethod[] | null, cardUnavailable: boolean): boolean {
+  return !handOff && !cardUnavailable && (offered === null || offered.includes("CARD"));
+}
+
+/** The wallets the block draws: each ready one, while the card is here and the sheet is (or was) priced. */
+function walletsShown(shown: boolean, google: unknown, apple: unknown): ListWallet[] {
+  if (!shown) return [];
+  const wallets: ListWallet[] = [];
+  if (google) wallets.push("GOOGLE_PAY");
+  if (apple) wallets.push("APPLE_PAY");
+  return wallets;
+}
+
+/** Google Pay's client and the head's gateway parameters, when both are there. */
+function googleSheet(config: CheckoutProviderConfig | null, client: GooglePaymentsClient | null): ListCapability["googlePay"] {
+  const params = googlePayConfig(config);
+  return params && client ? { client, params } : null;
+}
+
+/** {@link useListCapability}'s answer, from what it read. */
+function capabilityOf(
+  config: CheckoutProviderConfig | null,
+  client: GooglePaymentsClient | null,
+  price: { priced: boolean; repricing: boolean },
+  port: ListApplePay["validateMerchant"] | undefined,
+): ListCapability {
+  const offered = offeredMethods(config);
+  const cardUnavailable = !cardPathAvailable(config);
+  const handOff = methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config);
+  const card = cardHere(handOff, offered, cardUnavailable);
+  const google = googleSheet(config, client);
+  const apple = appleSession(config, port);
+  const live = card && price.priced;
+  return {
+    handOff,
+    offered,
+    cardUnavailable,
+    wallets: walletsShown(card && (price.priced || price.repricing), google, apple),
+    googlePay: live ? google : null,
+    applePay: live ? apple : null,
+  };
 }
 
 /**
  * The capability reads the tabs layout already makes (`method-capability.ts`,
- * `providers/registry.ts`), plus the one the list adds: Google Pay as its own
- * row, offered only when the chain head declares it AND this browser's
- * `isReadyToPay` said yes — the same two gates the Google Pay button has
- * always had (FUT-471), so the list never offers a wallet that cannot work.
+ * `providers/registry.ts`), plus the two wallets of the "PAGAMENTO RÁPIDO"
+ * block (FUT-3685, R5). A wallet is ready when the chain head declares it AND
+ * this device can pay with it — Google's `isReadyToPay`, Apple's
+ * `canMakePayments` — AND the card is offered and available here, since a
+ * wallet is another way of producing the card (so a Pix-only store never shows
+ * the block). Apple also needs the host's merchant-validation port: without it
+ * the session could only abort.
  *
- * The sheet must open inside the tap, before any order exists, so it is priced
+ * Both sheets open inside the tap, before any order exists, so they are priced
  * with the host's `totalCents` — the amount DUE. A host that never priced it,
- * or prices it at zero (a balance it holds covers everything), offers no row.
- * Once priced, a moment without a price (the host re-pricing — the credit was
- * toggled) keeps the row, and the list holds a chosen Google Pay's button,
- * plainly, until the price returns.
- *
- * Apple Pay is not a row here: its sheet must open synchronously inside the
- * tap, before any order could be raised for it. The tabs layout keeps it.
+ * or prices it at zero (a balance covers everything), offers no wallet.
  */
 export function useListCapability(
   config: CheckoutProviderConfig | null,
-  /** The host's price for the sheet — no price (or zero), no Google Pay row. */
+  /** The host's price for the sheets — no price (or zero), no wallet. */
   totalCents: number | undefined,
+  validateApplePayMerchant?: ListApplePay["validateMerchant"],
 ): ListCapability {
   const declared = googlePayConfig(config) !== null;
   // `null` tells the client hook not to load pay.js at all.
   const client = useGooglePayClient(declared ? undefined : null, "TEST");
-  const priced = totalCents !== undefined && totalCents > 0;
-  // Priced once, and not since withdrawn by an explicit zero.
-  const [wasPriced, setWasPriced] = useState(false);
-  if (priced && !wasPriced) setWasPriced(true);
-  if (totalCents === 0 && wasPriced) setWasPriced(false);
-  const repricing = totalCents === undefined && wasPriced;
-  return useMemo(() => {
-    const params = googlePayConfig(config);
-    const usable = params && client ? { client, params } : null;
-    return {
-      handOff: methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config),
-      offered: offeredMethods(config),
-      cardUnavailable: !cardPathAvailable(config),
-      googlePayReady: usable !== null && (priced || repricing),
-      googlePay: priced ? usable : null,
-    };
-  }, [config, client, priced, repricing]);
+  const { priced, repricing } = useRepricing(totalCents);
+  // The port is read at the press, through a ref: a host passing a new
+  // function each render must not rebuild the capability (and the wallets'
+  // buttons) every time. Only whether there IS one changes what is offered.
+  const port = useRef(validateApplePayMerchant);
+  port.current = validateApplePayMerchant;
+  const hasPort = validateApplePayMerchant !== undefined;
+  const stablePort = useCallback((validationURL: string): Promise<unknown> => {
+    const current = port.current;
+    return current ? current(validationURL) : Promise.reject(new Error("no merchant validation port"));
+  }, []);
+  return useMemo(
+    () => capabilityOf(config, client, { priced, repricing }, hasPort ? stablePort : undefined),
+    [config, client, priced, repricing, hasPort, stablePort],
+  );
 }