@12-apps/payments-frontend 3.36.0 → 3.38.0

package/src/components/checkout/payment-phase.tsx

@@ -0,0 +1,119 @@
+import type { JSX } from "react";
+
+import type { CheckoutCartView, CheckoutFlowProps } from "./checkout-flow";
+import { PaymentStep } from "./checkout-steps";
+import { PaymentListStep } from "./list/payment-list-step";
+import { OneClickProvider } from "./one-click";
+import type { CheckoutProviderConfig, SettlementCheckout } from "./types";
+import type { useCheckoutController } from "./use-checkout-controller";
+
+/**
+ * Step 2 of `<CheckoutFlow>`, moved out of `./checkout-flow.tsx` at its size
+ * gate when the Pagamento step gained a second shape (FUT-3591): the method
+ * tabs it always had, or the one list a host opts into.
+ */
+
+/** The pay-bar total override when settling a settlement (else the cart's own totals). */
+export function settlementTotalOverride(
+  settlement: SettlementCheckout | null | undefined,
+): { label: string; items: number } | undefined {
+  return settlement ? { label: settlement.totalLabel, items: settlement.totalItems } : undefined;
+}
+
+/** Step 2, with the controller's facts and the host's money mapped onto it. */
+function PagamentoStep({
+  c,
+  cart,
+  settlement,
+  providerConfig,
+  tenantSlug,
+  validateApplePayMerchant,
+}: {
+  c: ReturnType<typeof useCheckoutController>;
+  cart: CheckoutCartView;
+  settlement: SettlementCheckout | null | undefined;
+  providerConfig: CheckoutProviderConfig | null | undefined;
+  tenantSlug: string | undefined;
+  validateApplePayMerchant: ((validationURL: string) => Promise<unknown>) | undefined;
+}): JSX.Element {
+  return (
+    <PaymentStep
+      method={c.method}
+      onMethodChange={c.setMethod}
+      order={c.order}
+      buyer={c.buyer}
+      creating={c.creating}
+      createError={c.createError}
+      errorField={c.errorField}
+      errorCode={c.errorCode}
+      onGenerate={(chosen) => void c.startPayment(chosen)}
+      refresh={c.refresh}
+      onUseEmail={c.payWithEmail}
+      // Set only for a skipped-Dados flow (the controller decides); the payer
+      // block hides itself when it is absent.
+      onEditBuyer={c.editBuyer}
+      providerConfig={providerConfig}
+      tenantSlug={tenantSlug}
+      // The amount, on the step that asks for it (FUT-1179).
+      cartTotals={cart}
+      totalOverride={settlementTotalOverride(settlement)}
+      discountLines={cart.discountLines}
+      // The order around the payment, for the summary (FUT-3525).
+      lines={cart.lines}
+      delivery={cart.delivery}
+      orderNote={cart.orderNote}
+      // Retrying a refused card: the failed saved card is not chosen again (FUT-1145).
+      freshInstrument={c.freshInstrument}
+      // The card path parks an order of its own for a 3-D Secure challenge, so
+      // it needs the same basket the flow was mounted for (FUT-1213).
+      basket={cart.identity}
+      validateApplePayMerchant={validateApplePayMerchant}
+      onResolved={c.handleResolved}
+    />
+  );
+}
+
+/**
+ * Step 2, in whichever shape the host asked for: the one list, or the tabs.
+ * The list never arms one-click — it raises nothing on its own, which is the
+ * one-click request's ordinary degraded outcome anyway.
+ */
+export function PaymentPhase({
+  props,
+  c,
+  armed,
+}: {
+  props: Omit<CheckoutFlowProps, "components">;
+  c: ReturnType<typeof useCheckoutController>;
+  armed: boolean;
+}): JSX.Element {
+  const { cart, settlement, providerConfig, tenantSlug, validateApplePayMerchant, paymentList } = props;
+  if (paymentList) {
+    return (
+      <PaymentListStep
+        c={c}
+        list={paymentList}
+        cart={cart}
+        totalOverride={settlementTotalOverride(settlement)}
+        providerConfig={providerConfig}
+        tenantSlug={tenantSlug}
+        taxIdOnFile={props.taxIdOnFile ?? false}
+        defaultBuyer={props.defaultBuyer}
+        saveBuyerContact={props.saveBuyerContact}
+        consentLabel={props.copy.dados.saveProfile}
+      />
+    );
+  }
+  return (
+    <OneClickProvider armed={armed}>
+      <PagamentoStep
+        c={c}
+        cart={cart}
+        settlement={settlement}
+        providerConfig={providerConfig}
+        tenantSlug={tenantSlug}
+        validateApplePayMerchant={validateApplePayMerchant}
+      />
+    </OneClickProvider>
+  );
+}

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

@@ -1,9 +1,10 @@
 import { Box } from "@mui/material";
 import type { JSX, ReactNode } from "react";
 
+import { usePaymentStale } from "./cart-changed";
 import { useCheckoutCopy } from "./copy-context";
 import { CheckIcon, ContentCopyIcon, CreditCardIcon, QrCodeIcon, ScheduleIcon } from "./icons";
-import { Emphasized, PIX_WIDE, PixQr } from "./pix-parts";
+import { Emphasized, PIX_WIDE, PixQr, StaleVeil } from "./pix-parts";
 import type { PixAfterCopyCopy } from "./screens-copy";
 import type { PixCharge } from "./types";
 import { useCheckoutComponents } from "./ui";
@@ -128,11 +129,14 @@ interface PixAfterCopyProps {
 function Actions({ justCopied, onCopyAgain, onShowQr, onPreferCard }: Pick<PixAfterCopyProps, "justCopied" | "onCopyAgain" | "onShowQr" | "onPreferCard">): JSX.Element {
   const { Button } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
+  // The code already copied is the OLD order's once the cart changed
+  // (FUT-3535): copying it again would only hand the buyer the wrong amount.
+  const stale = usePaymentStale();
   return (
     <Box sx={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))", gap: 1.25, "& button": { minHeight: 48, height: "100%" }, "& button, & button *": { fontWeight: 700 }, [PIX_WIDE]: { display: "flex", flexWrap: "wrap", alignItems: "center", gap: 1.5, "& button": { height: "auto" } } }}>
       {/* Narrow, a grid cell; wide, its own width beside the link (the prototype's row). */}
       <Box sx={{ minWidth: 0, [PIX_WIDE]: { flex: "none", "& > *": { width: "auto" } } }}>
-        <Button variant="outline" color="neutral" size="md" fullWidth icon={<ContentCopyIcon fontSize="small" />} onClick={onCopyAgain} dataTestId="pix-copy-again">
+        <Button variant="outline" color="neutral" size="md" fullWidth icon={<ContentCopyIcon fontSize="small" />} onClick={onCopyAgain} disabled={stale} dataTestId="pix-copy-again">
           {justCopied ? copy.copiedAction : copy.copyAgainAction}
         </Button>
       </Box>
@@ -156,6 +160,7 @@ export function PixAfterCopy(props: PixAfterCopyProps): JSX.Element {
   const { Button, Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
   const { pix, words, totalLabel, deadline, onPreferCard, footer } = props;
+  const stale = usePaymentStale();
   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 }}>
@@ -175,7 +180,9 @@ export function PixAfterCopy(props: PixAfterCopyProps): JSX.Element {
         <Text variant="body" size="xs" weight="bold" color="secondary" as="p" style={{ margin: 0, textTransform: "uppercase", letterSpacing: "0.04em" }}>
           {copy.notPaidYet}
         </Text>
-        <PixQr payload={pix.copyPaste} size={168} alt={copy.qrAlt} />
+        <StaleVeil stale={stale}>
+          <PixQr payload={pix.copyPaste} size={168} alt={copy.qrAlt} />
+        </StaleVeil>
         <Text variant="body" size="xs" color="secondary" as="p" style={{ margin: 0, textAlign: "center" }}>
           {copy.scanFromPhone}
         </Text>

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

@@ -1,10 +1,11 @@
 import { Box } from "@mui/material";
 import type { JSX, ReactNode } from "react";
 
+import { usePaymentStale } from "./cart-changed";
 import { useCheckoutCopy } from "./copy-context";
 import { ContentCopyIcon } from "./icons";
 import { StickyPayBar, useCheckoutLayout } from "./payment-step-layout";
-import { Emphasized, PIX_WIDE, PixQr } from "./pix-parts";
+import { Emphasized, PIX_WIDE, PixQr, StaleVeil } from "./pix-parts";
 import type { PixCharge } from "./types";
 import { useCheckoutComponents } from "./ui";
 
@@ -64,6 +65,7 @@ function ColumnHeading({
 function QrPanel({ pix }: { pix: PixCharge }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
+  const stale = usePaymentStale();
   return (
     <Box
       data-testid="pix-qr-panel"
@@ -100,12 +102,14 @@ function QrPanel({ pix }: { pix: PixCharge }): JSX.Element {
           [PIX_WIDE]: { "& svg": { width: 232, height: 232 } },
         }}
       >
-        <PixQr
-          payload={pix.copyPaste}
-          size={232}
-          alt={copy.qrAlt}
-          testId="pix-qr"
-        />
+        <StaleVeil stale={stale}>
+          <PixQr
+            payload={pix.copyPaste}
+            size={232}
+            alt={copy.qrAlt}
+            testId="pix-qr"
+          />
+        </StaleVeil>
       </Box>
       <Text variant="body" size="sm" color="secondary" as="p" style={{ margin: 0, maxWidth: 280 }}>
         <Box component="span" sx={NARROW_ONLY}>{copy.qrTabCaption}</Box>
@@ -125,6 +129,9 @@ function QrPanel({ pix }: { pix: PixCharge }): JSX.Element {
 function CopyButton({ onCopy }: { onCopy: () => void }): JSX.Element {
   const { Button } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
+  // A changed cart makes this code the OLD order's (FUT-3535): nothing to copy
+  // until the step's "Atualizar pagamento" brings a new one.
+  const stale = usePaymentStale();
   return (
     <StickyPayBar>
       <Box
@@ -141,6 +148,7 @@ function CopyButton({ onCopy }: { onCopy: () => void }): JSX.Element {
           fullWidth
           icon={<ContentCopyIcon fontSize="small" />}
           onClick={onCopy}
+          disabled={stale}
           dataTestId="pix-copy"
         >
           {copy.copyAction}
@@ -162,6 +170,7 @@ function CopyPanel({
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
+  const stale = usePaymentStale();
   return (
     <Box
       data-testid="pix-copy-panel"
@@ -179,21 +188,23 @@ function CopyPanel({
         (a tinted chip, its own border and padding) is undone inside it:
         otherwise a wrapped code reads as a box inside a box.
       */}
-      <Box
-        sx={{
-          px: 2,
-          py: 1.5,
-          border: "1px solid",
-          borderColor: "divider",
-          borderRadius: 1.5,
-          bgcolor: "action.hover",
-          "&& > *": { bgcolor: "transparent", border: 0, borderRadius: 0, p: 0 },
-        }}
-      >
-        <Text variant="code" size="xs" as="p" data-testid="pix-code" style={{ margin: 0, wordBreak: "break-all", lineHeight: 1.55 }}>
-          {pix.copyPaste}
-        </Text>
-      </Box>
+      <StaleVeil stale={stale}>
+        <Box
+          sx={{
+            px: 2,
+            py: 1.5,
+            border: "1px solid",
+            borderColor: "divider",
+            borderRadius: 1.5,
+            bgcolor: "action.hover",
+            "&& > *": { bgcolor: "transparent", border: 0, borderRadius: 0, p: 0 },
+          }}
+        >
+          <Text variant="code" size="xs" as="p" data-testid="pix-code" style={{ margin: 0, wordBreak: "break-all", lineHeight: 1.55 }}>
+            {pix.copyPaste}
+          </Text>
+        </Box>
+      </StaleVeil>
       {inPanel ? <CopyButton onCopy={onCopy} /> : null}
       <Text
         variant="body"

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

@@ -1,7 +1,9 @@
 import { Box } from "@mui/material";
-import { Fragment, useCallback, useEffect, useRef, useState, type JSX } from "react";
+import { Fragment, useCallback, useEffect, useRef, useState, type JSX, type ReactNode } from "react";
 import QRCode from "react-qr-code";
 
+import { useCheckoutCopy } from "./copy-context";
+
 /**
  * The pieces the PIX pane and its after-copy face share (the 2026-10-06 Pix
  * redesign): the container-query switch, the QR, bold spans in a sentence, and
@@ -79,3 +81,50 @@ export function useClipboardCopy(text: string): { copy: () => Promise<boolean>;
   }, [text]);
   return { copy, justCopied };
 }
+
+/**
+ * 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
+ * reader, with "Atualize para gerar um novo Pix" over it. The step's warning
+ * above says why and carries the control that brings a new code. One tree
+ * shape either way, so lifting the veil redraws nothing.
+ */
+export function StaleVeil({ stale, children }: { stale: boolean; children: ReactNode }): JSX.Element {
+  const words = useCheckoutCopy().screens.cartChanged.pixVeil;
+  return (
+    <Box sx={{ position: "relative", minWidth: 0 }} data-testid={stale ? "pix-stale-veil" : undefined}>
+      <Box
+        aria-hidden={stale || undefined}
+        sx={stale ? { filter: "blur(6px)", opacity: 0.5, pointerEvents: "none", userSelect: "none" } : undefined}
+      >
+        {children}
+      </Box>
+      {stale ? (
+        <Box
+          sx={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center", p: 1.5 }}
+        >
+          <Box
+            component="p"
+            // An opaque overlay over the blurred code (ADR 0121): it covers
+            // what is under it on purpose, so the review probe reads it so.
+            data-ui-overlay=""
+            sx={{
+              m: 0,
+              px: 1.5,
+              py: 0.75,
+              borderRadius: 999,
+              bgcolor: "background.paper",
+              boxShadow: 1,
+              color: "text.primary",
+              fontSize: "0.8125rem",
+              fontWeight: 600,
+              textAlign: "center",
+            }}
+          >
+            {words}
+          </Box>
+        </Box>
+      ) : null}
+    </Box>
+  );
+}

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

@@ -2,6 +2,8 @@ import { Box } from "@mui/material";
 import { useEffect, useMemo, useRef, type JSX } from "react";
 
 import { useCheckoutCopy } from "./copy-context";
+import { usePaymentListMode } from "./list/context";
+import { ListPixFace } from "./list/list-pix";
 import { PixAfterCopy } from "./pix-after-copy";
 import { PixPane } from "./pix-pane";
 import { useCheckoutLayout } from "./payment-step-layout";
@@ -221,15 +223,19 @@ function PixTitle(): JSX.Element | null {
   );
 }
 
-function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; poll: ReturnType<typeof usePixPolling> }): JSX.Element {
-  const copy = useCheckoutCopy().screens.pix;
-  const stage = usePixStage();
-  const { copy: writeClipboard, justCopied } = useClipboardCopy(pix.copyPaste);
-  // Leaving the payment step (a method switch, a terminal status) ends the
-  // after-copy face with it: the next pane starts on the code.
-  const { setAfterCopy } = stage;
-  // A clipboard write that settles after the pane is gone must not reopen the
-  // after-copy face over whatever replaced it (it would hide the picker).
+/**
+ * The clipboard, and the copy that moves the pane on to its after-copy face.
+ *
+ * Leaving the payment step (a method switch, a terminal status) ends the
+ * after-copy face with it: the next pane starts on the code. And a clipboard
+ * write that settles after the pane is gone must not reopen the after-copy
+ * face over whatever replaced it (it would hide the picker).
+ */
+function useCopyThenWait(
+  payload: string,
+  setAfterCopy: (afterCopy: boolean) => void,
+): { writeClipboard: () => Promise<boolean>; justCopied: boolean; copyThenWait: () => void } {
+  const { copy: writeClipboard, justCopied } = useClipboardCopy(payload);
   const mounted = useRef(true);
   useEffect(() => {
     mounted.current = true;
@@ -238,6 +244,22 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
       setAfterCopy(false);
     };
   }, [setAfterCopy]);
+  // Only a copy the clipboard TOOK moves on: the next face opens on "Código
+  // Pix copiado", and a failed write leaves the code on screen to select by hand.
+  const copyThenWait = (): void => {
+    void writeClipboard().then((ok) => {
+      if (ok && mounted.current) setAfterCopy(true);
+    });
+  };
+  return { writeClipboard, justCopied, copyThenWait };
+}
+
+function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; poll: ReturnType<typeof usePixPolling> }): JSX.Element {
+  const copy = useCheckoutCopy().screens.pix;
+  const stage = usePixStage();
+  const listMode = usePaymentListMode();
+  const { writeClipboard, justCopied, copyThenWait } = useCopyThenWait(pix.copyPaste, stage.setAfterCopy);
+  const { setAfterCopy } = stage;
 
   // The locale is the HOST's (FUT-760): it decides what a buyer reads off the
   // clock, so it travels with the sentence it feeds rather than being frozen
@@ -247,6 +269,27 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
   const footerLine = (awaiting: string): JSX.Element => (
     <PixPollFooter error={poll.error} timedOut={poll.timedOut} onCheckAgain={poll.checkAgain} awaiting={awaiting} />
   );
+  // Inside the one list (FUT-3592), the code itself is the pane and the bar
+  // carries the copy; the wait is said by the bar, so only a STALLED poll
+  // draws here.
+  if (listMode) {
+    return (
+      <ListPixFace
+        mode={listMode}
+        order={order}
+        pix={pix}
+        time={time}
+        afterCopy={stage.afterCopy}
+        words={sentences.afterCopy}
+        justCopied={justCopied}
+        onCopy={copyThenWait}
+        onCopyAgain={() => void writeClipboard()}
+        onShowQr={() => setAfterCopy(false)}
+        onPreferCard={stage.preferCard}
+        footer={poll.error || poll.timedOut ? footerLine(copy.verifying) : null}
+      />
+    );
+  }
 
   if (stage.afterCopy) {
     return (
@@ -267,17 +310,7 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
   return (
     <>
       <PixTitle />
-      <PixPane
-        pix={pix}
-        onCopy={() => {
-          // Only a copy the clipboard TOOK moves on: the next face opens on
-          // "Código Pix copiado", and a failed write leaves the code on screen
-          // to select by hand.
-          void writeClipboard().then((ok) => {
-            if (ok && mounted.current) setAfterCopy(true);
-          });
-        }}
-      />
+      <PixPane pix={pix} onCopy={copyThenWait} />
       <PixFooter deadline={sentences.validUntil(time)}>{footerLine(sentences.awaiting)}</PixFooter>
     </>
   );

package/src/components/checkout/screens-copy.ts

@@ -284,6 +284,12 @@ export interface CartChangedCopy {
   refreshAction: string;
   /** The heading over a refresh that failed; the host's own sentence is the body. */
   refreshFailed: string;
+  /**
+   * Drawn over a PIX's QR and code while they are veiled (FUT-3535): the code
+   * on screen asks for the old amount, so it cannot be copied or scanned until
+   * the payment is updated.
+   */
+  pixVeil: string;
 }
 
 /** What the browser says when the wire itself failed. */

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

@@ -159,6 +159,7 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     support: 'This payment was prepared for your previous cart. Update it to pay the right amount.',
     refreshAction: 'Update payment',
     refreshFailed: 'Could not update the payment',
+    pixVeil: 'Update to get a new Pix code',
   },
   validation: {
     taxIdInvalid: 'That CPF is not valid.',

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

@@ -145,6 +145,7 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     support: 'O pagamento foi preparado para o carrinho anterior. Atualize para pagar o valor certo.',
     refreshAction: 'Atualizar pagamento',
     refreshFailed: 'Não foi possível atualizar o pagamento',
+    pixVeil: 'Atualize para gerar um novo Pix',
   },
   validation: {
     taxIdInvalid: 'CPF inválido.',

package/src/components/checkout/use-card-checkout.ts

@@ -4,7 +4,6 @@ import {
   NEW_CARD,
   detectBrand,
   onlyDigits,
-  tokenizerFor,
   validateCardNumber,
   validateCvv,
   validateExpiry,
@@ -23,6 +22,7 @@ import {
   type RefreshBrowserKey,
 } from "./card-instruments";
 import { handOverToChallenge, reportResolved, type ChallengeScope } from "./card-outcome";
+import { useCardPublicKey, useSavedCards } from "./card-sources";
 import { useCheckoutClientApi } from "./client-context";
 import { useCheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
@@ -34,80 +34,6 @@ import { useCheckoutCopy } from "./copy-context";
 
 const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
 
-/**
- * Saved-card list + current selection, loaded once on mount — scoped to the
- * current store (FUT-697), so only cards the store's active provider can
- * actually charge are offered. The slug arrives as an argument (the host's
- * routing owns it); absent, the list is unscoped, exactly as before FUT-697.
- */
-function useSavedCards(
-  tenantSlug: string | undefined,
-  /**
-   * The buyer is here because a card was REFUSED (FUT-1145), so the saved card
-   * this would otherwise preselect is the one that just failed. The list is
-   * still offered — another saved card may well work — but nothing is chosen
-   * for them, which puts the form in front of a buyer whose only untried
-   * instrument is a new one.
-   */
-  freshInstrument: boolean,
-): {
-  savedCards: SavedCard[];
-  selection: string;
-  setSelection: (id: string) => void;
-} {
-  const [savedCards, setSavedCards] = useState<SavedCard[]>([]);
-  const [selection, setSelection] = useState<string>(NEW_CARD);
-  const client = useCheckoutClientApi();
-
-  useEffect(() => {
-    let active = true;
-    void client.listInstruments(tenantSlug).then((cards) => {
-      if (!active) return;
-      setSavedCards(cards);
-      const first = cards[0];
-      if (first && !freshInstrument) setSelection(first.id);
-    });
-    return () => {
-      active = false;
-    };
-  }, [tenantSlug, client, freshInstrument]);
-
-  return { savedCards, selection, setSelection };
-}
-
-/**
- * The store's card public key for this order. The checkout config resolved the
- * initial key server-side (`GET /api/checkout/config`, FUT-697); the SPA
- * fetches through the order-scoped refresh route only when the ACTIVE provider
- * is PagBank — the sole provider that can mint a key on demand — and the
- * config arrived without one. A `null` key never means "mock": stub permission
- * travels separately as `mockTokenization`.
- */
-function useCardPublicKey(
-  orderId: string,
-  config: CardTokenizationConfig,
-): {
-  publicKey: string | null;
-  setPublicKey: (key: string) => void;
-} {
-  const [publicKey, setPublicKey] = useState<string | null>(config.publicKey);
-  const client = useCheckoutClientApi();
-  const refreshable =
-    config.provider !== null && tokenizerFor(config.provider) === "pagbank-sdk";
-
-  useEffect(() => {
-    if (config.publicKey !== null || !refreshable) return undefined;
-    let active = true;
-    void client.refreshBrowserKey({ orderId }).then((result) => {
-      if (active && result.ok && result.data.publicKey) setPublicKey(result.data.publicKey);
-    });
-    return () => {
-      active = false;
-    };
-  }, [orderId, config.publicKey, refreshable, client]);
-
-  return { publicKey, setPublicKey };
-}
 
 /** Everything the card view renders — all checkout state + the submit handler. */
 export interface CardCheckout {
@@ -137,6 +63,12 @@ export interface CardCheckout {
   pollTimedOut: boolean;
   /** Ask now and restart the wait — the buyer's "verificar de novo". */
   pollCheckAgain: () => void;
+  /**
+   * The order-scoped key refresh has not answered yet (`./card-sources.ts`): a
+   * charge started now would tokenize a new card with no key. A screen that
+   * starts the charge itself waits for this to clear.
+   */
+  keyPending: boolean;
   handlePay: () => Promise<void>;
 }
 
@@ -160,6 +92,7 @@ type CardSubmit = Pick<
   | "pollError"
   | "pollTimedOut"
   | "pollCheckAgain"
+  | "keyPending"
   | "handlePay"
 >;
 
@@ -246,7 +179,7 @@ function useCardWait(
  * poll for the async confirmation, bubbling the terminal status up via
  * {@link onResolved}.
  */
-function useCardSubmit(
+export function useCardSubmit(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   providerConfig: CardTokenizationConfig,
@@ -264,7 +197,7 @@ function useCardSubmit(
   const [errorCode, setErrorCode] = useState<string | null>(null);
   // The active key: resolved by the checkout config, overridden by the
   // rotated-key self-heal for the rest of the session.
-  const { publicKey, setPublicKey } = useCardPublicKey(order.orderId, providerConfig);
+  const { publicKey, setPublicKey, keyPending } = useCardPublicKey(order.orderId, providerConfig);
   const client = useCheckoutClientApi();
   const navigate = useCheckoutNavigate();
   const cardCopy = useCheckoutCopy().card;
@@ -323,7 +256,7 @@ function useCardSubmit(
     else setSubmitted(true);
   };
 
-  return { submitting, submitted, error, errorCode, ...wait, handlePay };
+  return { submitting, submitted, error, errorCode, ...wait, keyPending, handlePay };
 }
 
 /**

package/src/components/checkout/use-checkout-controller.ts

@@ -5,6 +5,7 @@ import {
   resumeSurface,
   useCheckoutNav,
   useCreateFailure,
+  useDropOrder,
   useGoToPayment,
   useResumedCheckout,
   useRetryAction,
@@ -135,6 +136,7 @@ export function useCheckoutController(
       return next;
     });
   }, [clearError, tenantSlug]);
+  const dropOrder = useDropOrder(setOrder, tenantSlug, clearError);
   const goToPayment = useGoToPayment({
     buyer, buyerFields, taxIdOnFile, saveProfile, saveBuyerContact, validation, failure, setStep,
   });
@@ -170,6 +172,6 @@ export function useCheckoutController(
     ...resumeSurface(resume, confirming),
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
-    goToPayment, startPayment, refresh, payWithEmail, handleResolved, retry, completed,
+    goToPayment, startPayment, refresh, payWithEmail, handleResolved, retry, completed, dropOrder,
   };
 }

package/src/flows/create-payment-flows.tsx

@@ -68,6 +68,11 @@ function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
   };
 }
 
+/** The host's one-list Pagamento (FUT-3591), when it opted in — a hook, read every render. */
+function useHostPaymentList(runtime: FlowsRuntime) {
+  return runtime.config.usePaymentList?.();
+}
+
 /** The whole three-step flow, with the config fetched and availability decided. */
 function buildCheckout(
   runtime: FlowsRuntime,
@@ -80,6 +85,7 @@ function buildCheckout(
     const cart = runtime.config.useCart();
     const defaults = runtime.config.useBuyerDefaults?.() ?? {};
     const hostSettlement = runtime.config.useSettlement?.() ?? null;
+    const paymentList = useHostPaymentList(runtime);
     const { config, pending } = useResolvedConfig(runtime);
     const availability = runtime.useAvailability();
     const tenantSlug = runtime.useTenantSlug();
@@ -108,6 +114,7 @@ function buildCheckout(
         confirmationExtra={runtime.config.confirmation?.extra}
         confirmationHero={runtime.config.confirmation?.hero}
         validateApplePayMerchant={ports.validateApplePayMerchant}
+        paymentList={paymentList}
       />
     );
   }