@12-apps/payments-frontend 3.38.0 → 3.40.0

package/src/components/checkout/list/pix-banks.tsx

@@ -0,0 +1,178 @@
+import { Box } from "@mui/material";
+import { useCallback, useEffect, useRef, useState, type JSX } from "react";
+
+import { Emphasized } from "../pix-parts";
+import { useCheckoutComponents } from "../ui";
+
+import { BankLogo } from "./bank-logos";
+import { openBankApp, PIX_BANKS, type PhoneOs } from "./bank-apps";
+import type { CheckoutPixBank, PixBankId } from "./types";
+
+/**
+ * The after-copy face's way to the bank app (FUT-3612), on a phone: with no
+ * bank chosen, the six as a 2×3 grid of large buttons under "Abra seu banco e
+ * cole em Pix copia e cola"; with one, "Abrindo o **Nubank**…" and "Outro
+ * banco" in one row — or, when the app did not open, the sentence that says so
+ * with "Tentar de novo".
+ */
+
+export type BankStatus = "opening" | "failed";
+
+export interface PixBankState {
+  /** The bank this face opens, or `null` while the grid is shown. */
+  chosen: PixBankId | null;
+  status: BankStatus | null;
+  /** Open `bank` (a pick from the grid remembers it). */
+  open: (bank: PixBankId, remember: boolean) => void;
+  /** "Outro banco": the grid again. The stored bank is replaced only by the next pick. */
+  showGrid: () => void;
+}
+
+/**
+ * The bank face's state. It starts on the remembered bank — unless the press
+ * asked for the grid ("Abrir outro banco") — and never opens anything while
+ * the code is veiled (FUT-3535: an app opened then would paste the old amount).
+ */
+export function usePixBankState(
+  remembered: PixBankId | null,
+  onPick: (bank: PixBankId) => void,
+  os: PhoneOs | null,
+  stale: boolean,
+  startOnGrid: boolean,
+): PixBankState {
+  const [chosen, setChosen] = useState<PixBankId | null>(startOnGrid ? null : remembered);
+  const [status, setStatus] = useState<BankStatus | null>(null);
+  const live = useRef(true);
+  useEffect(() => {
+    // Set in the body too: a remount (StrictMode's, or a parent's) runs the
+    // cleanup first, and a flag left false would swallow every "não abriu".
+    live.current = true;
+    return () => {
+      live.current = false;
+    };
+  }, []);
+  const open = useCallback(
+    (next: PixBankId, remember: boolean) => {
+      if (stale || !os) return;
+      setChosen(next);
+      setStatus("opening");
+      if (remember) onPick(next);
+      void openBankApp(next, os).then((opened) => {
+        if (live.current && !opened) setStatus("failed");
+      });
+    },
+    [os, onPick, stale],
+  );
+  const showGrid = useCallback(() => {
+    setChosen(null);
+    setStatus(null);
+  }, []);
+  return { chosen, status, open, showGrid };
+}
+
+function OtherLink({ label, onClick, testId }: { label: string; onClick: () => void; testId: string }): JSX.Element {
+  const { Button } = useCheckoutComponents();
+  return (
+    <Box sx={{ ml: "auto", flex: "none", "& button": { textDecoration: "underline", minHeight: (t) => t.spacing(5.5), px: 0.5 } }}>
+      <Button variant="text" color="primary" size="sm" onClick={onClick} dataTestId={testId}>
+        {label}
+      </Button>
+    </Box>
+  );
+}
+
+/** "Abrindo o **Nubank**…" · "Outro banco" — or "Não conseguimos abrir…" · "Tentar de novo" · "Outro banco". */
+function Opening({ bank, state, chosen }: { bank: CheckoutPixBank; state: PixBankState; chosen: PixBankId }): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  const name = bank.copy.names[chosen];
+  const failed = state.status === "failed";
+  return (
+    <Box data-testid="pix-bank-opening" data-status={state.status ?? "opening"} sx={{ display: "flex", alignItems: "center", flexWrap: "wrap", gap: 1 }}>
+      <Box component="span" role={failed ? "alert" : "status"} sx={{ minWidth: 0 }}>
+        <Text variant="body" size="sm" as="span">
+          {failed ? bank.copy.notOpened(name) : <Emphasized text={bank.copy.opening(name)} />}
+        </Text>
+      </Box>
+      {failed ? (
+        <Box sx={{ "& button": { minHeight: (t) => t.spacing(5.5) } }}>
+          <Button variant="outline" color="primary" size="sm" onClick={() => state.open(chosen, false)} dataTestId="pix-bank-retry">
+            {bank.copy.retry}
+          </Button>
+        </Box>
+      ) : null}
+      <OtherLink label={bank.copy.other} onClick={state.showGrid} testId="pix-bank-other" />
+    </Box>
+  );
+}
+
+/** One of the six: the bank's logo at 32px and its name, ≈56px tall. */
+/** The grid's own width, never the window's: under it, a cell is too narrow for logo and name side by side. */
+const NARROW_GRID = "@container pixbanks (max-width: 289.95px)";
+
+function BankButton({ bank, id, onPick, disabled }: { bank: CheckoutPixBank; id: PixBankId; onPick: () => void; disabled: boolean }): JSX.Element {
+  const { Button } = useCheckoutComponents();
+  const name = bank.copy.names[id];
+  const label = bank.copy.open(name);
+  const lead = label.slice(0, label.lastIndexOf(name.name));
+  return (
+    <Box
+      sx={{
+        minWidth: 0,
+        "& button": {
+          width: "100%",
+          minHeight: (t) => t.spacing(7),
+          borderRadius: 1.5,
+          justifyContent: "flex-start",
+          textAlign: "left",
+          gap: 1.25,
+          px: 1.5,
+          color: "text.primary",
+          borderColor: "divider",
+          // A 320px phone gives the grid ~254px (each half ~123px): logo
+          // beside "Santander" no longer fits, so the logo goes above the name.
+          [NARROW_GRID]: {
+            flexDirection: "column",
+            justifyContent: "center",
+            textAlign: "center",
+            gap: 0.5,
+            px: 1,
+            py: 1,
+            "& .MuiButton-startIcon, & .MuiButton-start": { m: 0 },
+          },
+        },
+        "& button, & button *": { fontWeight: 600 },
+      }}
+    >
+      <Button variant="outline" color="neutral" size="md" fullWidth disabled={disabled} icon={<BankLogo bank={id} />} onClick={onPick} dataTestId={`pix-bank-${id}`}>
+        {/* The accessible name is "Abrir Nubank"; the eye reads the logo and "Nubank". */}
+        <Box component="span" sx={{ position: "absolute", width: "1px", height: "1px", overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" }}>
+          {lead}
+        </Box>
+        {name.name}
+      </Button>
+    </Box>
+  );
+}
+
+function Grid({ bank, state, stale }: { bank: CheckoutPixBank; state: PixBankState; stale: boolean }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  return (
+    <Box data-testid="pix-bank-grid" sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      <Text variant="body" size="md" weight="semibold" as="p" style={{ margin: 0 }}>
+        {bank.copy.listTitle}
+      </Text>
+      <Box sx={{ containerType: "inline-size", containerName: "pixbanks" }}>
+        <Box sx={{ display: "grid", gridTemplateColumns: "repeat(2, minmax(0, 1fr))", gap: 1 }}>
+          {PIX_BANKS.map((id) => (
+            <BankButton key={id} bank={bank} id={id} disabled={stale} onPick={() => state.open(id, true)} />
+          ))}
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+/** The grid, or the bank being opened. */
+export function PixBanks({ bank, state, stale }: { bank: CheckoutPixBank; state: PixBankState; stale: boolean }): JSX.Element {
+  return state.chosen ? <Opening bank={bank} state={state} chosen={state.chosen} /> : <Grid bank={bank} state={state} stale={stale} />;
+}

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

@@ -51,6 +51,7 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
     details: "Preencha seus dados para pagar pelo app.",
     chooseCard: "Escolha o cartão.",
     cardDetails: "Preencha os dados do cartão.",
+    repricing: "Atualizando o valor…",
   },
   actions: {
     choose: "Escolha como pagar",
@@ -62,6 +63,7 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
   payer: (name) => `Pagando como ${name} · CPF ✓`,
   payerChange: "Alterar",
   charging: (total, card) => `Pagando ${total} no ${card ?? "cartão informado"}…`,
+  chargingCovered: "Confirmando o pedido, pago com o seu saldo…",
   cancel: "Cancelar",
   pixFace: {
     title: (total) => `Pague ${total} com Pix`,

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

@@ -102,12 +102,126 @@ export interface CheckoutPaymentList {
   /** Told whenever the chosen option changes, including to nothing. */
   onChoiceChange?: (choice: CheckoutListChoice | null) => void;
   /**
-   * The amount the buyer is about to pay, in integer cents — 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. Absent ⇒ no Google Pay row. The charge
-   * is refused if the order raised after the sheet does not cost the same.
+   * 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`.
    */
   totalCents?: number;
+  /**
+   * The same amount, pre-formatted by the host ("R$ 22,00"), when it is not
+   * the cart's total — a balance the host holds pays part of it. The card's
+   * button, the 5-second bar and Google Pay's press name THIS while an online
+   * option is chosen; a door option and an empty choice keep the cart's total,
+   * since no balance pays at the door. Absent ⇒ the cart's total. It is also
+   * the amount the Pix face asks for.
+   *
+   * **A balance that covers everything** (`totalCents: 0`): the card option
+   * asks for no card, the bar says `copy.chargingCovered`, and the order the
+   * button raises must come back SETTLED by the host — paid from the balance,
+   * with no provider call — so the list goes to its paid screen. An order that
+   * comes back `AWAITING_PAYMENT` with `amountDueCents: 0` is never charged:
+   * the list returns to its rows.
+   */
+  amountDueLabel?: string;
+  /**
+   * The buyer's last ONLINE way to pay, as the host remembers it (FUT-3611) —
+   * chosen for them before they touch anything, when the store offers it: Pix
+   * as Pix; a card as the saved card used last. Absent or `null` ⇒ the saved
+   * card rule alone. A door tender is never chosen for the buyer.
+   */
+  lastMethod?: "PIX" | "CARD" | null;
+  /**
+   * "Pedir em 1 toque" opened this checkout (FUT-3611): the tap on the
+   * cardápio was the buyer's consent, so the card's 5-second bar starts by
+   * itself once the saved card is chosen and nothing holds the button — ONCE
+   * per step, and only within {@link ARMED_WINDOW_MS} of the step opening: a
+   * checkout that lands held (a field to fill) never charges by itself minutes
+   * later. Without a saved card it does nothing.
+   */
+  armedCharge?: boolean;
+  /**
+   * The saved card the host's consent named (the 1-tap offer's). Given, the
+   * armed charge fires only on THAT card; a different selection never charges
+   * by itself.
+   */
+  armedCardId?: string;
+  /**
+   * Host content under the 5-second bar's Cancelar while it counts — the
+   * storefront's "Cancelar e desativar a compra em 1 toque". It is handed the
+   * bar's own cancel, so a link there stops the charge before doing its own.
+   */
+  chargeFooter?: (cancel: () => void) => ReactNode;
+  /**
+   * Pix straight to the buyer's bank app (FUT-3612) — on a phone only: the
+   * button generates AND copies the code, a short message says so through
+   * `notify`, and the after-copy face offers the six banks (or opens the one
+   * remembered). Absent ⇒ today's Pix: "Gerar Pix", then a tap to copy.
+   */
+  pixBank?: CheckoutPixBank;
+  /** Says a short sentence in the host's own toast — "Código Pix copiado". */
+  notify?: (message: string) => void;
+}
+
+/** The six banks the Pix face offers to open, in the prototype's order. */
+export type PixBankId = "nubank" | "itau" | "bradesco" | "bb" | "caixa" | "santander";
+
+/** `CheckoutPaymentList.pixBank`. */
+export interface CheckoutPixBank {
+  /** The bank the buyer picked last time, as the host stored it — or `null`. */
+  remembered: PixBankId | null;
+  /** A bank was picked: the host remembers it for next time (a new pick replaces it). */
+  onPick: (bank: PixBankId) => void;
+  /** The words; ship with the list's pack (`PIX_BANK_COPY`). */
+  copy: PixBankCopy;
+  /**
+   * Whether this device can open a bank app — a phone. Absent ⇒ read from the
+   * browser (Android or iOS). A computer keeps today's face and gets only the
+   * generate-and-copy.
+   */
+  phone?: boolean;
+}
+
+/** A bank's name and the article pt-BR puts before it ("o Nubank", "a Caixa"). */
+export interface PixBankName {
+  name: string;
+  /** "Abrir o Nubank" / "Abrir a Caixa" — the article with its trailing space, or "" for none. */
+  the: string;
+}
+
+export interface PixBankCopy {
+  names: Record<PixBankId, PixBankName>;
+  /** The bar's button with no bank remembered — "Gerar e copiar o Pix". */
+  generateAndCopy: string;
+  /** With one remembered — "Gerar, copiar e abrir o Nubank". */
+  generateCopyAndOpen: (bank: PixBankName) => string;
+  /** The before-copy face's button with one remembered — "Copiar e abrir o Nubank". */
+  copyAndOpen: (bank: PixBankName) => string;
+  /** The link under the button — "Abrir outro banco". */
+  openOther: string;
+  /** Over the grid — "Abra seu banco e cole em Pix copia e cola". */
+  listTitle: string;
+  /** A bank button's accessible name — "Abrir Nubank". */
+  open: (bank: PixBankName) => string;
+  /** "Abrindo o **Nubank**…" — `**` marks the bold span. */
+  opening: (bank: PixBankName) => string;
+  /** "Outro banco". */
+  other: string;
+  /** "Não conseguimos abrir o Nubank. O app está instalado neste celular?" */
+  notOpened: (bank: PixBankName) => string;
+  /** "Tentar de novo". */
+  retry: string;
+  /** The toasts. */
+  copied: string;
+  copiedPick: string;
+  copiedOpening: (bank: PixBankName) => string;
 }
 
 /** The list's words — a pack per locale ships at `@12-apps/payments-frontend/locales`. */
@@ -155,6 +269,8 @@ export interface PaymentListCopy {
     details: string;
     chooseCard: string;
     cardDetails: string;
+    /** Google Pay is chosen while the host re-prices (`totalCents` briefly absent). Absent ⇒ no sentence. */
+    repricing?: string;
   };
   /** The button's verb, beside the total. */
   actions: {
@@ -169,6 +285,12 @@ export interface PaymentListCopy {
   payerChange: string;
   /** The 5-second bar: "Pagando R$ 27,00 no Visa final 4242…"; `card` is `null` for a card typed now. */
   charging: (total: string, card: string | null) => string;
+  /**
+   * The 5-second bar when the host's balance pays the WHOLE amount
+   * (`totalCents` 0), so no card is charged and none is named — "Confirmando
+   * o pedido, pago com o seu saldo…". Absent ⇒ `charging` as usual.
+   */
+  chargingCovered?: string;
   cancel: string;
   pixFace: {
     /** "Pague R$ 22,00 com Pix". */

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

@@ -21,24 +21,29 @@ export interface ListCapability extends OnlineCapability {
  * always had (FUT-471), so the list never offers a wallet that cannot work.
  *
  * The sheet must open inside the tap, before any order exists, so it is priced
- * with the host's `totalCents`; without one there is no row.
+ * 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.
  */
 export function useListCapability(
   config: CheckoutProviderConfig | null,
-  /** The host's price for the sheet — no price, no Google Pay row. */
+  /** The host's price for the sheet — no price (or zero), no Google Pay row. */
   totalCents: number | undefined,
 ): 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");
-  // Once the host has priced the sheet, a moment without a price (it is
-  // re-pricing — the credit was toggled) keeps the row and holds its button;
-  // only a host that never priced it offers no row.
-  const [priced, setPriced] = useState(false);
-  if (totalCents !== undefined && !priced) setPriced(true);
+  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;
@@ -46,8 +51,8 @@ export function useListCapability(
       handOff: methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config),
       offered: offeredMethods(config),
       cardUnavailable: !cardPathAvailable(config),
-      googlePayReady: usable !== null && (totalCents !== undefined || priced),
-      googlePay: totalCents === undefined ? null : usable,
+      googlePayReady: usable !== null && (priced || repricing),
+      googlePay: priced ? usable : null,
     };
-  }, [config, client, totalCents, priced]);
+  }, [config, client, priced, repricing]);
 }

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

@@ -32,6 +32,8 @@ interface RaisePorts {
   startPayment: (method: PaymentMethod) => Promise<void>;
   /** The amount the buyer is shown now (the cart's, or the balance's). */
   cartTotal: string;
+  /** What an online payment asks the provider for now, when the host prices it (`paymentList.totalCents`). */
+  dueCents?: number;
 }
 
 export interface ListCharge {
@@ -57,9 +59,23 @@ export interface ListCharge {
   chargeable: CheckoutOrder | null;
 }
 
-/** A held CARD order still awaiting payment AND priced as the buyer now sees — reusable for the charge. */
-function reusable(order: CheckoutOrder | null, cartTotal: string): boolean {
-  return order?.method === "CARD" && order.status === "AWAITING_PAYMENT" && order.totalLabel === cartTotal;
+/**
+ * A held CARD order still awaiting payment AND priced as the buyer now sees —
+ * reusable for the charge. A balance ticked or unticked moves what the charge
+ * asks for and not the order's total, so the amount due is compared too.
+ */
+function reusable(order: CheckoutOrder | null, cartTotal: string, dueCents: number | undefined): boolean {
+  if (order?.method !== "CARD" || order.status !== "AWAITING_PAYMENT" || order.totalLabel !== cartTotal) return false;
+  return dueCents === undefined || (order.amountDueCents ?? order.totalCents) === dueCents;
+}
+
+/**
+ * An awaiting CARD order that asks the provider for nothing: a balance the host
+ * holds covers it, and the host should have settled it (see `amountDueLabel`).
+ * It is never charged.
+ */
+function owesNothing(order: CheckoutOrder | null): boolean {
+  return order?.method === "CARD" && order.status === "AWAITING_PAYMENT" && order.amountDueCents === 0;
 }
 
 /** The order `send` meant: the one it reused, or the CARD order raised to replace a stale one. */
@@ -67,11 +83,24 @@ function chargeTarget(
   order: CheckoutOrder | null,
   target: { reuse: CheckoutOrder } | { replace: CheckoutOrder | null } | null,
 ): CheckoutOrder | null {
-  if (!order || !target || order.method !== "CARD" || order.status !== "AWAITING_PAYMENT") return null;
+  if (!order || !target || order.method !== "CARD" || order.status !== "AWAITING_PAYMENT" || owesNothing(order)) return null;
   if ("reuse" in target) return target.reuse === order ? order : null;
   return order !== target.replace ? order : null;
 }
 
+/**
+ * Back to the list when the press left nothing to charge: a raise that failed
+ * (the step's error panel says why), or a held order that owes the provider
+ * nothing — never charged, rather than waited on forever.
+ */
+function useSettleWhenNothingToCharge(phase: ListChargePhase, kind: ListChargeKind | null, ports: RaisePorts, settle: () => void): void {
+  const { order, creating, createError } = ports;
+  useEffect(() => {
+    if (phase !== "sending" || creating) return;
+    if ((!order && createError) || (kind === "CARD" && owesNothing(order))) settle();
+  }, [phase, kind, creating, order, createError, settle]);
+}
+
 /**
  * The bar's charge, after the button (FUT-3592): count down for a card, then
  * raise the order — or reuse the CARD order already held, after a refusal the
@@ -108,8 +137,8 @@ export function useListCharge(ports: RaisePorts): ListCharge {
     // must not let the bar's own timer charge past it.
     if (!allowed.current) return cancel();
     setPhase("sending");
-    const { order, cartTotal } = latest.current;
-    if (reusable(order, cartTotal) && order) {
+    const { order, cartTotal, dueCents } = latest.current;
+    if (reusable(order, cartTotal, dueCents) && order) {
       target.current = { reuse: order };
       return;
     }
@@ -148,12 +177,8 @@ export function useListCharge(ports: RaisePorts): ListCharge {
     if (timer.current) clearTimeout(timer.current);
   }, []);
 
-  // A raise that failed leaves nothing to charge: back to the list, where the
-  // step's error panel says why.
-  const { order, creating, createError } = ports;
-  useEffect(() => {
-    if (phase === "sending" && !creating && !order && createError) settle();
-  }, [phase, creating, order, createError, settle]);
+  const { order, creating } = ports;
+  useSettleWhenNothingToCharge(phase, kind, ports, settle);
 
   const sending = phase === "sending" || phase === "waiting";
   const chargeable = sending && !creating ? chargeTarget(order, target.current) : null;

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

@@ -5,7 +5,7 @@ import { useSavedCardList } from "../card-sources";
 import { useCheckoutCopy } from "../copy-context";
 import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig } from "../types";
 
-import { askedFields, cardComplete, onlineRows, preselection, raisedMethod, type OnlineCapability, type OnlineRow } from "./choice";
+import { askedFields, cardComplete, lastUsedCard, onlineRows, preselection, raisedMethod, type OnlineCapability, type OnlineRow } from "./choice";
 import type { CheckoutListChoice } from "./types";
 
 const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
@@ -59,6 +59,7 @@ function usePreselect(
   rows: readonly OnlineRow[],
   saved: readonly SavedCard[],
   fresh: boolean,
+  lastMethod: "PIX" | "CARD" | null,
   apply: (choice: CheckoutListChoice, selection: string | null) => void,
   touched: { current: boolean },
 ): void {
@@ -66,18 +67,18 @@ function usePreselect(
   useEffect(() => {
     if (done.current || touched.current || !loaded) return;
     done.current = true;
-    const pick = preselection(rows, saved, fresh);
+    const pick = preselection(rows, saved, fresh, lastMethod);
     if (pick) apply(pick.choice, pick.selection);
-  }, [loaded, rows, saved, fresh, apply, touched]);
+  }, [loaded, rows, saved, fresh, lastMethod, apply, touched]);
 }
 
 /**
- * The card chosen again: the head of the saved list — or, for a buyer back from
- * a refused card (FUT-1145), no saved card at all (the head may be the one that
- * failed), or the fields when nothing is saved.
+ * The card chosen again: the one used last (else the head of the saved list) —
+ * or, for a buyer back from a refused card (FUT-1145), no saved card at all
+ * (that one may be the card that failed), or the fields when nothing is saved.
  */
 function reopenedSelection(cards: readonly SavedCard[], fresh: boolean): string | null {
-  const head = cards[0];
+  const head = lastUsedCard(cards);
   if (!head) return NEW_CARD;
   return fresh ? null : head.id;
 }
@@ -96,6 +97,8 @@ export function useListState(input: {
   fresh: boolean;
   arrivedWith: BuyerInfo | undefined;
   taxIdOnFile: boolean;
+  /** The buyer's last online method, from the host (FUT-3611). */
+  lastMethod?: "PIX" | "CARD" | null;
   onChoiceChange?: (choice: CheckoutListChoice | null) => void;
 }): ListState {
   const { capability } = input;
@@ -112,7 +115,7 @@ export function useListState(input: {
     },
     [setSelection],
   );
-  usePreselect(loaded, rows, cards, input.fresh, apply, touched);
+  usePreselect(loaded, rows, cards, input.fresh, input.lastMethod ?? null, apply, touched);
   const choose = useCallback(
     (next: CheckoutListChoice) => {
       touched.current = true;

package/src/components/checkout/pix-after-copy.tsx

@@ -123,6 +123,12 @@ interface PixAfterCopyProps {
   onPreferCard?: () => void;
   /** The poll's line ("Verificando…", or the stalled panel that replaces it). */
   footer: ReactNode;
+  /**
+   * The way to the bank app, on a phone (FUT-3612): drawn where the heading
+   * was — the toast already said the code was copied and the bar says what it
+   * waits for — and, while it is the six banks, in place of the checklist.
+   */
+  banks?: { node: ReactNode; replacesChecklist: boolean };
 }
 
 /** The narrow layout's two secondaries side by side; wide, the card link joins the row. */
@@ -164,8 +170,8 @@ export function PixAfterCopy(props: PixAfterCopyProps): JSX.Element {
   return (
     <Box data-testid="pix-after-copy" sx={{ display: "flex", flexWrap: "wrap", gap: 4, alignItems: "flex-start" }}>
       <Box sx={{ flex: "999 1 420px", minWidth: 0, display: "flex", flexDirection: "column", gap: 2.5 }}>
-        <Heading words={words} totalLabel={totalLabel} />
-        <Checklist words={words} deadline={deadline} />
+        {props.banks ? props.banks.node : <Heading words={words} totalLabel={totalLabel} />}
+        {props.banks?.replacesChecklist ? null : <Checklist words={words} deadline={deadline} />}
         <Actions {...props} />
         {footer}
         {onPreferCard ? (

package/src/components/checkout/pix-parts.tsx

@@ -82,6 +82,62 @@ export function useClipboardCopy(text: string): { copy: () => Promise<boolean>;
   return { copy, justCopied };
 }
 
+/** A copy opened inside a tap whose text arrives later (FUT-3612) — see {@link deferredCopy}. */
+export interface DeferredCopy {
+  /** The text has arrived: write it. */
+  resolve: (text: string) => void;
+  /** There will be no text (the raise was refused): give the clipboard up. */
+  fail: () => void;
+  /** `true` once the clipboard holds the text; `false` when it refused or there was none. */
+  done: Promise<boolean>;
+}
+
+/**
+ * Open the clipboard NOW, inside the buyer's tap, for a text the server has
+ * not answered yet. Safari lets a page write to the clipboard only inside the
+ * gesture, so the write is started here with a promise of the text
+ * (`ClipboardItem`); where that is missing or refused, the plain write is
+ * tried once the text arrives — Chrome takes it from a focused page.
+ */
+export function deferredCopy(): DeferredCopy {
+  let give: (text: string | null) => void = () => undefined;
+  const text = new Promise<string | null>((resolve) => {
+    give = resolve;
+  });
+  const plain = async (): Promise<boolean> => {
+    const value = await text;
+    if (value === null || !navigator.clipboard) return false;
+    try {
+      await navigator.clipboard.writeText(value);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const Item = typeof window === "undefined" ? undefined : (window as { ClipboardItem?: typeof ClipboardItem }).ClipboardItem;
+  let done: Promise<boolean> = Promise.resolve(false);
+  let opened = false;
+  if (Item && navigator.clipboard && typeof navigator.clipboard.write === "function") {
+    const blob = text.then((value) => {
+      if (value === null) throw new Error("no text");
+      return new Blob([value], { type: "text/plain" });
+    });
+    // An unanswered blob must not surface as an unhandled rejection.
+    blob.catch(() => undefined);
+    try {
+      done = navigator.clipboard.write([new Item({ "text/plain": blob })]).then(
+        () => true,
+        async () => (await text) !== null && plain(),
+      );
+      opened = true;
+    } catch {
+      // A browser whose ClipboardItem takes no promise throws here, in the tap.
+    }
+  }
+  if (!opened) done = plain();
+  return { resolve: (value) => give(value), fail: () => give(null), done };
+}
+
 /**
  * A PIX's QR or code, veiled while the cart has changed under it (FUT-3535):
  * blurred past reading, out of reach of a pointer, a selection and a screen

package/src/components/checkout/pix-view.tsx

@@ -287,6 +287,8 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
         onShowQr={() => setAfterCopy(false)}
         onPreferCard={stage.preferCard}
         footer={poll.error || poll.timedOut ? footerLine(copy.verifying) : null}
+        writeClipboard={writeClipboard}
+        setAfterCopy={setAfterCopy}
       />
     );
   }

package/src/components/checkout/transport.ts

@@ -308,7 +308,9 @@ export function createCheckoutClient(transport: CheckoutTransport): CheckoutClie
       // offered for a Stone charge it would fail (or misroute).
       const query = tenantSlug ? `?tenantSlug=${encodeURIComponent(tenantSlug)}` : "";
       const result = await call<SavedCard[]>(`/cards${query}`, { method: "GET" });
-      return result.ok ? result.data : [];
+      // A route that answers `null` (or no list at all) has no saved card —
+      // every screen that reads this maps over it.
+      return result.ok && Array.isArray(result.data) ? result.data : [];
     },
 
     beginVault: () => call<BuyerVaultSession>("/cards/begin", { method: "POST" }),