@12-apps/payments-frontend 3.38.0 → 3.39.0

package/package.json

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

package/src/card/types.ts

@@ -40,6 +40,12 @@ export interface SavedCard {
   expMonth: number;
   expYear: number;
   holder: string;
+  /**
+   * When the buyer last paid with it (ISO-8601), or `null`/absent when the
+   * host does not say. The one list preselects the card used LAST (FUT-3591);
+   * every other screen keeps the host's own order.
+   */
+  lastUsedAt?: string | null;
 }
 
 /** Per-field validation messages; `undefined` means the field is fine. */

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

@@ -13,6 +13,14 @@ import { useCheckoutClientApi } from "./client-context";
  * rather than after the buyer has spent a minute typing.
  */
 
+/**
+ * A list answer as a list: a host whose card route answers `null` (or
+ * nothing) has no saved card, and must not take the checkout down with it.
+ */
+function asList(cards: SavedCard[] | null | undefined): SavedCard[] {
+  return Array.isArray(cards) ? cards : [];
+}
+
 /**
  * The buyer's saved cards at this store (FUT-697), loaded once per store, and
  * whether the list has answered — "no saved card" and "not asked yet" are
@@ -29,7 +37,7 @@ export function useSavedCardList(tenantSlug: string | undefined): { cards: Saved
       .listInstruments(tenantSlug)
       .catch((): SavedCard[] => [])
       .then((cards) => {
-        if (active) setState({ cards, loaded: true });
+        if (active) setState({ cards: asList(cards), loaded: true });
       });
     return () => {
       active = false;
@@ -68,8 +76,9 @@ export function useSavedCards(
     void client
       .listInstruments(tenantSlug)
       .catch((): SavedCard[] => [])
-      .then((cards) => {
+      .then((answer) => {
         if (!active) return;
+        const cards = asList(answer);
         const first = cards[0];
         setState((prev) => ({ savedCards: cards, selection: first && !freshInstrument ? first.id : prev.selection }));
       });

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

@@ -106,11 +106,27 @@ export function CardRun({
   return submitted ? <SubmittedState card={submit} /> : null;
 }
 
+/**
+ * A refusal a host can fix: its order answers no `amountDueCents`, and its
+ * total is not what the sheet showed — the shape of a balance taken off the
+ * charge that the order view does not report. Said once in development; the
+ * buyer still gets the refusal.
+ */
+function warnMissingAmountDue(order: CheckoutOrder, sheetCents: number): void {
+  const development = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+  if (order.amountDueCents !== undefined || !development) return;
+  console.warn(
+    `[payments-frontend] Google Pay refused: the order costs ${order.totalCents} cents and the sheet showed ${sheetCents}. ` +
+      "A host that takes a balance off the charge must answer CheckoutOrder.amountDueCents.",
+  );
+}
+
 /**
  * Google Pay: the sheet was opened INSIDE the buyer's tap (`sheet`, priced at
  * `sheetCents`) while the order was raised; its key is charged against that
- * order only if the order costs what the sheet showed. A closed sheet sends
- * nothing more.
+ * order only if the order asks the provider for what the sheet showed — its
+ * amount due, which a balance the host holds may have made less than its
+ * total. A closed sheet sends nothing more.
  */
 export function WalletRun({
   order,
@@ -140,7 +156,10 @@ export function WalletRun({
       .then((key) => {
         if (key === null) return onFailed(null);
         // The sheet showed one amount; never charge another under it.
-        if (order.totalCents !== sheetCents) return onFailed(refused);
+        if ((order.amountDueCents ?? order.totalCents) !== sheetCents) {
+          warnMissingAmountDue(order, sheetCents);
+          return onFailed(refused);
+        }
         return void wallet.payWithKey("GOOGLE_PAY", key);
       })
       .catch(() => onFailed(refused));

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

@@ -43,6 +43,8 @@ interface RowProps {
   onBuyerChange: (buyer: BuyerInfo) => void;
   provider: string | null;
   failure: ListChargeFailure | null;
+  /** The host's balance pays the whole amount: the card asks for no card at all. */
+  covered?: boolean;
 }
 
 /** One of the store's online options, with what opens inside it. */
@@ -62,7 +64,7 @@ function OnlineOptionRow({ row, props }: { row: OnlineRow; props: RowProps }): J
       onChoose={() => state.choose({ kind: "online", method: row.method })}
       testId={`list-option-${row.method}`}
     >
-      {opensContent(row.method, state.asked, props.failure) ? (
+      {opensContent(row.method, state.asked, props.failure, props.covered) ? (
         <OnlineContent
         method={row.method}
         asked={state.asked}
@@ -72,6 +74,7 @@ function OnlineOptionRow({ row, props }: { row: OnlineRow; props: RowProps }): J
         copy={copy}
         provider={provider}
         failure={props.failure}
+        covered={props.covered}
         />
       ) : null}
     </OptionRow>

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

@@ -63,10 +63,28 @@ export function raisedMethod(choice: CheckoutOnlineChoice, offered: PaymentMetho
   return "CARD";
 }
 
+/**
+ * The saved card to choose for the buyer: the one used LAST (owner,
+ * 2026-10-15), or the list's head — the host's own order, newest first — when
+ * no card says when it was used. A card never used loses to any used one.
+ */
+export function lastUsedCard(saved: readonly SavedCard[]): SavedCard | undefined {
+  let pick: SavedCard | undefined;
+  let pickAt = -Infinity;
+  for (const card of saved) {
+    const at = card.lastUsedAt ? Date.parse(card.lastUsedAt) : Number.NaN;
+    if (!Number.isNaN(at) && at > pickAt) {
+      pick = card;
+      pickAt = at;
+    }
+  }
+  return pick ?? saved[0];
+}
+
 /**
  * What is chosen before the buyer touches anything (M7, owner 2026-10-15): a
  * saved card makes "Cartão de crédito" the choice with that card selected —
- * the list's head, which the host orders last-used first. Nothing else is ever
+ * the one used last ({@link lastUsedCard}). Nothing else is ever
  * preselected: never Pix, never a door tender (FUT-1478), and not a store's
  * only method either (that pick used to raise an order with no tap at all).
  *
@@ -82,7 +100,7 @@ export function preselection(
   const card = rows.find((row) => row.method === "CARD" && !row.disabled);
   if (!card) return null;
   if (fresh) return { choice: { kind: "online", method: "CARD" }, selection: saved.length > 0 ? null : NEW_CARD };
-  const head = saved[0];
+  const head = lastUsedCard(saved);
   if (!head) return null;
   return { choice: { kind: "online", method: "CARD" }, selection: head.id };
 }
@@ -157,6 +175,8 @@ export function blockedReason(input: {
   buyer: BuyerInfo;
   selection: string | null;
   cardIsComplete: boolean;
+  /** The host's balance pays the whole amount: no card needs choosing. */
+  covered?: boolean;
 }): string | null {
   const { copy, choice } = input;
   if (input.hold) return input.hold;
@@ -164,7 +184,7 @@ export function blockedReason(input: {
   if (choice.kind === "door") return input.door ? input.door.blocked : copy.reasons.choose;
   const buyer = buyerReason(input.asked, input.buyer, copy.reasons);
   if (buyer) return buyer;
-  if (choice.method !== "CARD") return null;
+  if (choice.method !== "CARD" || input.covered) return null;
   return cardReason(input.selection, input.cardIsComplete, copy.reasons);
 }
 

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

@@ -35,6 +35,7 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
     details: "Fill in your details to pay in the app.",
     chooseCard: "Choose the card.",
     cardDetails: "Fill in the card details.",
+    repricing: "Updating the amount…",
   },
   actions: {
     choose: "Choose how to pay",
@@ -46,6 +47,7 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
   payer: (name) => `Paying as ${name} · CPF ✓`,
   payerChange: "Change",
   charging: (total, card) => `Paying ${total} with ${card ?? "the card entered"}…`,
+  chargingCovered: "Confirming the order, paid with your balance…",
   cancel: "Cancel",
   pixFace: {
     title: (total) => `Pay ${total} with Pix`,

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

@@ -66,11 +66,19 @@ function saveAsked(props: ListFaceProps): void {
   saveBuyerContact?.({ name: c.buyer.name, phone: c.buyer.phone, taxId: c.buyer.taxId });
 }
 
+/**
+ * What an online payment asks for: the host's amount due when a balance it
+ * holds pays part of the cart, else the cart's total (P3).
+ */
+function onlineTotal(props: ListFaceProps): string {
+  return props.list.amountDueLabel ?? props.total;
+}
+
 /** An online choice's press: the card goes through the bar, Pix and the hand-off raise at once. */
 function actOnline(props: ListFaceProps, method: CheckoutOnlineChoice): void {
   const { c, charge, cap } = props;
   saveAsked(props);
-  if (method === "CARD") return charge.start("CARD", props.total);
+  if (method === "CARD") return charge.start("CARD", onlineTotal(props));
   const raised = method === "PIX" ? "PIX" : handOffMethod(cap.offered);
   if (method === "HAND_OFF") props.onHandOff();
   c.setMethod(raised);
@@ -94,7 +102,7 @@ function useAct(props: ListFaceProps, clearFailure: () => void): () => void {
 
 /**
  * Google Pay's press, from Google's own button: the sheet opens HERE, inside
- * the tap, priced with the host's total — then the order is raised behind it.
+ * the tap, priced with the host's amount due — then the order is raised behind it.
  */
 function useGooglePayPress(props: ListFaceProps, clearFailure: () => void, sheet: { current: OpenSheet | null }): () => void {
   return () => {
@@ -113,7 +121,7 @@ function useGooglePayPress(props: ListFaceProps, clearFailure: () => void, sheet
         },
       );
     sheet.current = { answer, cents };
-    charge.start("GOOGLE_PAY", props.total);
+    charge.start("GOOGLE_PAY", onlineTotal(props));
   };
 }
 
@@ -151,26 +159,35 @@ function cardCharging(charge: ListCharge): boolean {
   return charge.phase === "counting" || (charge.phase === "sending" && charge.kind === "CARD");
 }
 
-/** The bar's sentence: the amount frozen at the press, and the card it goes on. */
+/**
+ * The bar's sentence: the amount frozen at the press, and the card it goes on
+ * — or, when the host's balance pays everything, no card at all.
+ */
 function chargingText(props: ListFaceProps): string {
-  const { charge, list, state, total } = props;
+  const { charge, list, state } = props;
+  if (coveredByHost(list) && list.copy.chargingCovered) return list.copy.chargingCovered;
   const selected = state.card.saved.find((card) => card.id === state.card.selection);
-  return list.copy.charging(charge.pressedTotal ?? total, selected ? cardName(list.copy, selected) : null);
+  return list.copy.charging(charge.pressedTotal ?? onlineTotal(props), selected ? cardName(list.copy, selected) : null);
 }
 
 /** The verb, the amount and the busy state of the button, for what is chosen. */
 function buttonFacts(props: ListFaceProps): { label: string; total: string; busy: boolean } {
   const { list, state } = props;
   const door = chosenDoor(props);
+  const online = state.choice?.kind === "online";
   return {
     label: list.hold ? list.hold.action : actionLabel(list.copy, state.choice, door, props.provider),
-    total: door?.totalLabel ?? props.total,
+    total: door ? (door.totalLabel ?? props.total) : online ? onlineTotal(props) : props.total,
     busy: inFlight(props),
   };
 }
 
-/** Google Pay chosen while the host re-prices: the row stays, its button waits for the price. */
-function googlePayRepricing(props: ListFaceProps): boolean {
+/**
+ * Google Pay chosen while the host re-prices (or for the one render before the
+ * list drops a choice nobody prices any more): a plain disabled button, never
+ * a spinner, with `copy.reasons.repricing` under it.
+ */
+function googlePayUnpriced(props: ListFaceProps): boolean {
   const { choice } = props.state;
   return choice?.kind === "online" && choice.method === "GOOGLE_PAY" && !props.cap.googlePay;
 }
@@ -199,7 +216,7 @@ function BarAction({ props, failure, act, onGooglePay, onCancel, reason, returnF
   // all under "não pague de novo" (FUT-563), as the card pane does today.
   if (failure?.code === UNRESOLVED_CODE) return null;
   const { label, total, busy } = buttonFacts(props);
-  if (googlePayRepricing(props)) return <ActionButton label={label} total={total} disabled loading onClick={act} />;
+  if (googlePayUnpriced(props)) return <ActionButton label={label} total={total} disabled loading={false} onClick={act} />;
   if (googlePayLive(props, reason, busy) && cap.googlePay) return <GooglePayAction client={cap.googlePay.client} onPress={onGooglePay} />;
   return <ActionButton label={label} total={total} disabled={reason !== null || busy} loading={busy} onClick={act} focusOnMount={returnFocus} />;
 }
@@ -230,13 +247,19 @@ function RaiseError({ c, onRetry }: { c: Controller; onRetry: () => void }): JSX
   return <PaymentErrorPanel message={c.createError} emailFlagged={c.errorField === "email"} code={c.errorCode} onUseEmail={c.payWithEmail} onRetry={onRetry} />;
 }
 
+/** The host's balance pays the whole amount (`totalCents: 0`): no card is asked for or charged. */
+function coveredByHost(list: CheckoutPaymentList): boolean {
+  return list.totalCents === 0;
+}
+
 /** Why the button is held: the host's hold, then the list's own reasons, in the prototype's order. */
 function reasonOf(props: ListFaceProps, door: CheckoutDoorOption | undefined): string | null {
   const { c, list, state } = props;
-  return blockedReason({
+  const reason = blockedReason({
     copy: list.copy, hold: list.hold?.reason ?? null, choice: state.choice, door, asked: state.asked,
-    buyer: c.buyer, selection: state.card.selection, cardIsComplete: state.card.complete,
+    buyer: c.buyer, selection: state.card.selection, cardIsComplete: state.card.complete, covered: coveredByHost(list),
   });
+  return reason ?? (googlePayUnpriced(props) ? (list.copy.reasons.repricing ?? null) : null);
 }
 
 /**
@@ -262,8 +285,8 @@ function barFacts(props: ListFaceProps, door: CheckoutDoorOption | undefined, re
  * appears or a total that moves mid-bar stops it, and `send` checks again.
  */
 function useChargeGuard(props: ListFaceProps, reason: string | null): void {
-  const { charge, total } = props;
-  const allowed = reason === null && (charge.pressedTotal === null || charge.pressedTotal === total);
+  const { charge } = props;
+  const allowed = reason === null && (charge.pressedTotal === null || charge.pressedTotal === onlineTotal(props));
   const { setAllowed } = charge;
   useEffect(() => setAllowed(allowed), [allowed, setAllowed]);
 }
@@ -301,7 +324,7 @@ export function ListFace(props: ListFaceProps): JSX.Element {
   return (
     <Box data-testid="payment-list-step" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       {shown ? (
-        <ChoiceList copy={list.copy} state={state} door={list.door ?? []} buyer={c.buyer} onBuyerChange={c.setBuyer} provider={props.provider} failure={failure} locked={facts.locked} />
+        <ChoiceList copy={list.copy} state={state} door={list.door ?? []} buyer={c.buyer} onBuyerChange={c.setBuyer} provider={props.provider} failure={failure} locked={facts.locked} covered={coveredByHost(list)} />
       ) : null}
       <Runners props={props} sheet={sheet.current} onFailed={onFailed} />
       <RaiseError c={c} onRetry={act} />

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

@@ -180,13 +180,13 @@ export function ListPixFace(props: ListPixFaceProps & { mode: PaymentListMode })
   return (
     <Box data-testid="list-pix" sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
       <Text variant="body" size="md" weight="bold" as="p" style={{ margin: 0 }} data-testid="list-pix-title">
-        {copy.title(order.totalLabel)}
+        {copy.title(mode.list.amountDueLabel ?? order.totalLabel)}
       </Text>
       {afterCopy ? (
         <PixAfterCopy
           pix={pix}
           words={props.words}
-          totalLabel={order.totalLabel}
+          totalLabel={mode.list.amountDueLabel ?? order.totalLabel}
           deadline={props.time}
           justCopied={props.justCopied}
           onCopyAgain={props.onCopyAgain}

package/src/components/checkout/list/online-content.tsx

@@ -72,9 +72,13 @@ function SavedChips({ card, copy }: { card: ListCard; copy: PaymentListCopy }):
   );
 }
 
-/** Whether a chosen online row has anything to open — a row with nothing opens no box (L5). */
-export function opensContent(method: string, asked: readonly CheckoutCustomerField[], failure: ListChargeFailure | null): boolean {
-  return method === "CARD" || asked.length > 0 || failure !== null;
+/**
+ * Whether a chosen online row has anything to open — a row with nothing opens
+ * no box (L5). The card opens nothing of its own when the host's balance pays
+ * the whole amount: no card is charged, so none is asked for.
+ */
+export function opensContent(method: string, asked: readonly CheckoutCustomerField[], failure: ListChargeFailure | null, covered = false): boolean {
+  return (method === "CARD" && !covered) || asked.length > 0 || failure !== null;
 }
 
 /** Move the focus to the card number — the next thing to type once the CPF is complete. */
@@ -97,6 +101,7 @@ export function OnlineContent({
   copy,
   provider,
   failure,
+  covered = false,
 }: {
   method: "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
   asked: readonly CheckoutCustomerField[];
@@ -106,9 +111,11 @@ export function OnlineContent({
   copy: PaymentListCopy;
   provider: string | null;
   failure: ListChargeFailure | null;
+  /** The host's balance pays the whole amount — no chips, no card fields. */
+  covered?: boolean;
 }): JSX.Element {
   const scope = useRef<HTMLDivElement | null>(null);
-  const isCard = method === "CARD";
+  const isCard = method === "CARD" && !covered;
   return (
     <Box ref={scope} sx={{ display: "flex", flexDirection: "column", gap: 1.25 }}>
       <BuyerInline

package/src/components/checkout/list/option-row.tsx

@@ -70,8 +70,10 @@ export function OptionRow({
         borderRadius: 2.5,
         px: 1.5,
         opacity: disabled ? 0.6 : 1,
-        // The keyboard's place in the group, drawn on the whole row (5.1 item 6).
-        "&:has(input:focus-visible)": { outline: (t) => `${t.spacing(0.25)} solid ${t.palette.primary.main}`, outlineOffset: (t) => t.spacing(0.25) },
+        // The keyboard's place in the group, drawn on the whole row (5.1 item 6)
+        // — for the row's own radio only: a field opened inside draws its own
+        // ring, and a second one around the row doubled it.
+        "&:has(> label input[type='radio']:focus-visible)": { outline: (t) => `${t.spacing(0.25)} solid ${t.palette.primary.main}`, outlineOffset: (t) => t.spacing(0.25) },
       }}
     >
       <Box

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

@@ -132,7 +132,7 @@ export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
     taxIdOnFile: props.taxIdOnFile,
     onChoiceChange: list.onChoiceChange,
   });
-  const charge = useListCharge({ ...c, cartTotal: displayTotals(props.totalOverride, props.cart).label });
+  const charge = useListCharge({ ...c, cartTotal: displayTotals(props.totalOverride, props.cart).label, dueCents: list.totalCents });
   const [handingOff, startHandOff] = useHandingOff(c.createError);
   const pixStage = usePaymentPixStage(cap, usePreferMethod(c, state.choose));
   const pix = c.order?.method === "PIX" ? c.order : null;

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,35 @@ 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 list's words — a pack per locale ships at `@12-apps/payments-frontend/locales`. */
@@ -155,6 +178,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 +194,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: "" };
@@ -72,12 +72,12 @@ function usePreselect(
 }
 
 /**
- * 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;
 }

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;
   /**