@12-apps/payments-frontend 3.37.0 → 3.39.0

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

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type Dispatch, type SetStateAction } from "react";
+
+import { NEW_CARD, type CardDetails, type CardFieldErrors, type SavedCard } from "../../../card";
+import { useSavedCardList } from "../card-sources";
+import { useCheckoutCopy } from "../copy-context";
+import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig } from "../types";
+
+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: "" };
+
+/** The card the buyer pays with, as the list holds it before any order exists. */
+export interface ListCard {
+  saved: SavedCard[];
+  /** A saved card's id, `NEW_CARD` for the fields, or `null` when none is chosen. */
+  selection: string | null;
+  setSelection: (selection: string | null) => void;
+  card: CardDetails;
+  setCard: Dispatch<SetStateAction<CardDetails>>;
+  fieldErrors: CardFieldErrors;
+  setFieldErrors: Dispatch<SetStateAction<CardFieldErrors>>;
+  saveCard: boolean;
+  setSaveCard: (save: boolean) => void;
+  complete: boolean;
+}
+
+/** Everything the one list holds, and nothing it raises. */
+export interface ListState {
+  rows: OnlineRow[];
+  choice: CheckoutListChoice | null;
+  choose: (next: CheckoutListChoice) => void;
+  card: ListCard;
+  /** The buyer's own details the chosen online option must ask for (M11). */
+  asked: CheckoutCustomerField[];
+}
+
+/**
+ * The card the buyer is typing or has picked. It outlives every order raised
+ * under it: the charge reads it when the 5-second bar fills, and a refusal
+ * brings the buyer back to it as they left it.
+ */
+function useListCard(saved: SavedCard[]): ListCard {
+  const fieldCopy = useCheckoutCopy().card.fields;
+  const [selection, setSelection] = useState<string | null>(null);
+  const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
+  const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
+  const [saveCard, setSaveCard] = useState(false);
+  const complete = useMemo(() => cardComplete(card, fieldCopy), [card, fieldCopy]);
+  return { saved, selection, setSelection, card, setCard, fieldErrors, setFieldErrors, saveCard, setSaveCard, complete };
+}
+
+/**
+ * Preselect ONCE, when the saved cards answer — never over a choice the buyer
+ * already made, and never again after they made one (M7).
+ */
+function usePreselect(
+  loaded: boolean,
+  rows: readonly OnlineRow[],
+  saved: readonly SavedCard[],
+  fresh: boolean,
+  apply: (choice: CheckoutListChoice, selection: string | null) => void,
+  touched: { current: boolean },
+): void {
+  const done = useRef(false);
+  useEffect(() => {
+    if (done.current || touched.current || !loaded) return;
+    done.current = true;
+    const pick = preselection(rows, saved, fresh);
+    if (pick) apply(pick.choice, pick.selection);
+  }, [loaded, rows, saved, fresh, apply, touched]);
+}
+
+/**
+ * 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 = lastUsedCard(cards);
+  if (!head) return NEW_CARD;
+  return fresh ? null : head.id;
+}
+
+/**
+ * The one list's state (FUT-3591). Picking an option changes THIS and nothing
+ * else: no order, no charge, no request — the bar's button is the only thing
+ * that raises (M7). The host hears about every change through
+ * `onChoiceChange`, which is how its door options learn they are chosen.
+ */
+export function useListState(input: {
+  config: CheckoutProviderConfig | null;
+  capability: OnlineCapability;
+  tenantSlug: string | undefined;
+  /** Back here after a refused card (FUT-1145): no saved card is selected for them. */
+  fresh: boolean;
+  arrivedWith: BuyerInfo | undefined;
+  taxIdOnFile: boolean;
+  onChoiceChange?: (choice: CheckoutListChoice | null) => void;
+}): ListState {
+  const { capability } = input;
+  const rows = useMemo(() => onlineRows(capability), [capability]);
+  const { cards, loaded } = useSavedCardList(input.tenantSlug);
+  const card = useListCard(cards);
+  const [choice, setChoice] = useState<CheckoutListChoice | null>(null);
+  const touched = useRef(false);
+  const { setSelection } = card;
+  const apply = useCallback(
+    (next: CheckoutListChoice, selection: string | null) => {
+      setChoice(next);
+      if (selection !== null) setSelection(selection);
+    },
+    [setSelection],
+  );
+  usePreselect(loaded, rows, cards, input.fresh, apply, touched);
+  const choose = useCallback(
+    (next: CheckoutListChoice) => {
+      touched.current = true;
+      setChoice((previous) => {
+        // Coming back to the card from another option starts on the head of
+        // the saved list again (FN:420), or on the fields when there is none;
+        // what was typed in them is kept.
+        const reopensCard = next.kind === "online" && next.method === "CARD" && !(previous?.kind === "online" && previous.method === "CARD");
+        if (reopensCard) setSelection(reopenedSelection(cards, input.fresh));
+        return next;
+      });
+    },
+    [cards, setSelection, input.fresh],
+  );
+  // A choice the chain no longer offers (a config that resolved to a hand-off
+  // store after the card was preselected) is no choice at all.
+  useEffect(() => {
+    if (choice?.kind === "online" && !rows.some((row) => row.method === choice.method && !row.disabled)) setChoice(null);
+  }, [choice, rows]);
+  const { onChoiceChange } = input;
+  useEffect(() => {
+    onChoiceChange?.(choice);
+  }, [choice, onChoiceChange]);
+  const asked = useMemo(
+    () =>
+      choice?.kind === "online"
+        ? askedFields({
+            chain: input.config?.chain,
+            method: raisedMethod(choice.method, capability.offered),
+            arrivedWith: input.arrivedWith,
+            taxIdOnFile: input.taxIdOnFile,
+          })
+        : [],
+    [choice, input.config, capability.offered, input.arrivedWith, input.taxIdOnFile],
+  );
+  return { rows, choice, choose, card, asked };
+}

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-parts.tsx

@@ -105,6 +105,9 @@ export function StaleVeil({ stale, children }: { stale: boolean; children: React
         >
           <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,

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/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" }),

package/src/components/checkout/types.ts

@@ -2,11 +2,10 @@
  * The buyer checkout's payment vocabulary (FUT-7 / FUT-44 / FUT-58, moved into
  * the library by FUT-564).
  *
- * Pure types with no runtime imports. Everything here is PAYMENT: what a
- * charge, an order-in-payment, a buyer identity or a provider protocol looks
- * like to the screens in this folder. The host-side halves — the cart, the
- * catalog, order CREATION — stay in the host app and reach the flow through
- * the ports declared on `CheckoutFlowProps`.
+ * Pure types with no runtime imports. Everything here is PAYMENT: what a charge, an
+ * order-in-payment, a buyer identity or a provider protocol looks like to the screens in
+ * this folder. The host-side halves — the cart, the catalog, order CREATION — stay in the
+ * host app and reach the flow through the ports declared on `CheckoutFlowProps`.
  */
 
 import type { CheckoutDecline, CheckoutDeclineReason } from "./decline";
@@ -15,10 +14,9 @@ import type { CheckoutDecline, CheckoutDeclineReason } from "./decline";
 export type PaymentMethod = "PIX" | "CARD";
 
 /**
- * The digital wallets a chain entry can charge (FUT-471/472). Mirrors the
- * backend's `WalletType` — a wallet is not a fourth method: it is another way
- * of producing the CARD instrument, so it rides the CARD tile and the CARD
- * charge.
+ * The digital wallets a chain entry can charge (FUT-471/472). Mirrors the backend's
+ * `WalletType` — a wallet is not a fourth method: it is another way of producing the
+ * CARD instrument, so it rides the CARD tile and the CARD charge.
  */
 export type CheckoutWalletType = "GOOGLE_PAY" | "APPLE_PAY";
 
@@ -114,6 +112,8 @@ export interface CheckoutOrder {
   appliedDiscounts: CheckoutDiscount[];
   /** Pre-formatted BRL grand total (e.g. `R$ 42,90`). */
   totalLabel: string;
+  /** Cents the provider is asked for when a balance the host holds pays part of {@link totalCents}; absent ⇒ the total. */
+  amountDueCents?: number;
   /** Present only when {@link method} is `"PIX"`. */
   pix?: PixCharge;
   /**

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}
       />
     );
   }

package/src/flows/types.ts

@@ -19,6 +19,7 @@
  * `chain[].provider`, looked up in the tokenizer registry and used verbatim as
  * a `tokensByProvider` key. A host never types one.
  */
+import type { CheckoutPaymentList } from "../components/checkout/list/types";
 import type { ComponentType, ReactNode } from "react";
 
 import type { SavedCard } from "../card";
@@ -115,6 +116,12 @@ export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
   useBuyerDefaults?(): { buyer?: BuyerInfo; taxIdOnFile?: boolean; pending?: boolean };
   /** Present ⇒ this checkout settles a settlement rather than the cart. */
   useSettlement?(): SettlementCheckout | null;
+  /**
+   * The Pagamento step as ONE list (FUT-3591) — `CheckoutFlowProps.paymentList`,
+   * read through a HOOK because the host's door options follow its own state.
+   * Absent, or answering `undefined`, keeps the method tabs.
+   */
+  usePaymentList?(): CheckoutPaymentList | undefined;
 
   /** Design-system slots, filled ONCE instead of per screen. */
   components?: Partial<CheckoutComponents>;

package/src/index.ts

@@ -54,11 +54,10 @@ export { PT_BR_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-pt-BR
 // mounted by a host in one line. See ADOPTING.md §3 for the ports and the
 // design-system slot contract.
 // ---------------------------------------------------------------------------
-export {
-  CheckoutFlow,
-  type CheckoutCartView,
-  type CheckoutFlowProps,
-} from './components/checkout/checkout-flow';
+export { CheckoutFlow, type CheckoutCartView, type CheckoutFlowProps } from './components/checkout/checkout-flow';
+// The Pagamento step as ONE list (FUT-3591/3592) — opt-in via `CheckoutFlowProps.paymentList`.
+export type { CheckoutDoorOption, CheckoutListChoice, CheckoutListHold, CheckoutOnlineChoice, CheckoutPaymentList, PaymentListCopy } from './components/checkout/list/types';
+export { PT_BR_PAYMENT_LIST_COPY } from './components/checkout/list/pt-BR';
 export type { BackActionEmphasis } from './components/checkout/payment-status-parts';
 export type { CheckoutDeliverySummary, CheckoutSummaryLine } from './components/checkout/payment-summary';