@12-apps/payments-frontend 3.22.0 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.22.0",
+  "version": "3.23.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.",
@@ -22,7 +22,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.27.0",
+    "@12-apps/payments-backend": "^4.27.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/checkout/checkout-actions.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useState, type Dispatch, type SetStateAction } from "react";
 
 import { buyerGateError } from "./buyer-gate";
+import type { ConfirmationWait } from "./confirmation-wait";
 import type { CheckoutDecline } from "./decline";
 import { forgetHostedOrder, rememberHostedOrder } from "./hosted-return";
 import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
@@ -65,23 +66,55 @@ export function useCheckoutNav(
 }
 
 /**
- * What the resumed leg contributes to the controller's surface.
+ * WHAT THE CONFIRMATION SCREEN KNOWS ABOUT ITS WAIT, from whichever wait is
+ * live.
  *
- * All of it is inert for a checkout that never left this tab and never raised
- * anything: with nothing parked the poll is disabled, so the error stays null,
- * the bound never elapses, and neither action has a wait to act on.
+ * Two can reach that screen and they are mutually exclusive by construction: a
+ * checkout RESUMED from a parked entry polls through `useHostedResume`, and one
+ * that never left this tab polls through the confirmation wait (FUT-1170) — and
+ * that one stands down whenever a resumed order is what put the flow here. So
+ * the merge below is a choice between one live wait and one inert one, never a
+ * blend of two opinions.
+ *
+ * All of it is inert for a checkout with an answer already: with nothing to
+ * wait on both polls are disabled, so the error stays null, no bound elapses,
+ * and none of the actions has a wait to act on.
+ *
+ * `release` stays the resumed leg's alone. "Não consegui pagar" exists because
+ * a provider's own page produces no signal when a buyer abandons it (FUT-1146);
+ * a charge raised and still held on THIS page has no such gap to close.
  */
-export function resumeSurface(resume: HostedResume): {
+export function resumeSurface(
+  resume: HostedResume,
+  confirming: ConfirmationWait,
+): {
+  awaitingTimedOut: boolean;
+  awaitingError: string | null;
+  awaitingCheckAgain: () => void;
+  /** @deprecated Renamed to `awaitingTimedOut`; kept so the rename ships additively. */
   resumeTimedOut: boolean;
+  /** @deprecated Renamed to `awaitingError`; kept so the rename ships additively. */
   resumeError: string | null;
+  /** @deprecated Renamed to `awaitingCheckAgain`; kept so the rename ships additively. */
   resumeCheckAgain: () => void;
   resumeRelease: (() => void) | undefined;
   resumeReleasing: boolean;
 } {
+  const live = resume.order === null ? confirming : resume;
   return {
-    resumeTimedOut: resume.timedOut,
-    resumeError: resume.error,
-    resumeCheckAgain: resume.checkAgain,
+    awaitingTimedOut: live.timedOut,
+    awaitingError: live.error,
+    awaitingCheckAgain: live.checkAgain,
+    // The three old spellings, beside the new ones rather than replaced by them.
+    // This shape is PUBLIC — `CheckoutController` is `ReturnType<typeof
+    // useCheckoutController>` (flows/types.ts:148), re-exported from index.ts,
+    // and `PaymentFlows.useCheckout()` returns it. Dropping three members of it
+    // is a source break for any adopter that hand-composes the flow, and this
+    // release is a patch. The rename was cosmetic; breaking a published type for
+    // it is not a trade worth making, so the old names stay until a major.
+    resumeTimedOut: live.timedOut,
+    resumeError: live.error,
+    resumeCheckAgain: live.checkAgain,
     resumeRelease: resume.release,
     resumeReleasing: resume.releasing,
   };
@@ -316,6 +349,20 @@ export function useStartPayment(input: {
     async (chosen: PaymentMethod, override?: BuyerInfo) => {
       failure.clear();
       setDecline(null);
+      // THE CHARGE BEING REPLACED IS DROPPED FIRST (FUT-1170), before the raise
+      // rather than after it. Raising a payment means whatever was on screen is
+      // no longer the one being paid, and a provider round trip is long enough
+      // for the difference to matter: "Gerar novo código" left the expired
+      // charge mounted, so its own view polled it, got the terminal EXPIRED it
+      // was always going to get, and bounced the flow to the confirmation
+      // screen — where the new charge then landed with nothing polling it.
+      //
+      // A no-op on every other caller (the auto-raise, the alternate e-mail and
+      // the retry all run with no order held), which is the point: the clear
+      // belongs to what raising a payment MEANS, not to the one path that
+      // noticed.
+      setOrder(null);
+      setFinalStatus(null);
       setCreating(true);
       const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
       setCreating(false);
@@ -331,7 +378,6 @@ export function useStartPayment(input: {
       // the payment they just made.
       rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
       setOrder(result.data);
-      setFinalStatus(null);
     },
     [
       buyer, saveProfile, createOrder, failure, navigate, tenantSlug, basket,

package/src/components/checkout/checkout-flow.tsx

@@ -197,12 +197,14 @@ function StatusStep({
       onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
       onBackToMenu={c.goToMenu}
       paidExtra={confirmationExtra}
-      awaitingTimedOut={c.resumeTimedOut}
-      // The resumed leg's own trouble, and the way out of it (FUT-1144). Both
-      // are inert for a checkout that never left this tab — nothing was parked,
-      // so nothing is being polled here.
-      awaitingError={c.resumeError}
-      onCheckAgain={c.resumeCheckAgain}
+      awaitingTimedOut={c.awaitingTimedOut}
+      // How the wait behind this screen is going, and the way out of it
+      // (FUT-1144). It is the resumed leg's wait for a checkout that came back
+      // from a provider's page, and this step's own (FUT-1170) for one that
+      // never left the tab — which used to have no wait at all, and so a
+      // spinner that stood for nothing.
+      awaitingError={c.awaitingError}
+      onCheckAgain={c.awaitingCheckAgain}
       // The buyer's own way out of a hosted wait with no terminal state
       // (FUT-1146). Absent — and so unrendered — until the resumed leg has one
       // to offer, which is every checkout that never left this tab.
@@ -229,6 +231,12 @@ function StatusStep({
  * A cart still being FETCHED is empty in exactly the way a real one is not, so
  * a host that wires `identity` gets this screen when its cart is empty rather
  * than when it is late — which is also the moment the resume decision waits for.
+ *
+ * A RAISE IN FLIGHT is not "nothing to pay for" either (FUT-1170). Raising a
+ * charge now drops the one it replaces before it asks for the new one, so there
+ * is a window with no order held — and a checkout whose cart the host had
+ * already emptied would otherwise swap the buyer onto the empty-cart screen
+ * mid-regenerate, discarding the charge as it arrived.
  */
 function nothingToPayFor(
   settlement: SettlementCheckout | null | undefined,
@@ -236,7 +244,7 @@ function nothingToPayFor(
   c: ReturnType<typeof useCheckoutController>,
 ): boolean {
   if (settlement || !cart.empty || !cartLoaded(cart)) return false;
-  return !c.order && c.step !== "status";
+  return !c.order && !c.creating && c.step !== "status";
 }
 
 /** Step 2, with the controller's facts and the host's money mapped onto it. */

package/src/components/checkout/confirmation-wait.ts

@@ -0,0 +1,97 @@
+import { useEffect } from "react";
+
+import type { OrderStatus } from "./types";
+import { usePaymentPolling } from "./use-payment-polling";
+
+/**
+ * THE CONFIRMATION STEP'S OWN WAIT (FUT-1170).
+ *
+ * Polling used to live entirely in the method's screen — the PIX code's footer,
+ * the card pane's post-submit state — which is right for the payment step and
+ * leaves the LAST step with none. A flow parked on Confirmação holding an
+ * unsettled order therefore rendered "Confirmando seu pagamento" over a spinner
+ * that stood for nothing: no poll was scheduled, no error could appear, no
+ * clock could elapse, and the only control on screen was "Voltar ao cardápio".
+ *
+ * FUT-1170 reaches that state through the regenerate path, and dropping the
+ * replaced charge closes that particular door. This is the other half, and it
+ * is the half that holds for doors nobody has opened yet: any caller that lands
+ * on the confirmation screen with a live order now has something asking about
+ * it, and — when the clock runs out — something to press.
+ *
+ * ## Why here rather than hoisting the screens' polls into the flow
+ *
+ * The three waits are genuinely different. PIX is bounded by the CODE's own
+ * expiry and decays over minutes; the card wait is 90 s from the submit; the
+ * resumed hosted leg has its own release action attached to it. One hoisted
+ * poll would have to serve all three at one cadence and one bound, and the
+ * cadence is the thing each of them tunes. So the payment step keeps the wait
+ * that belongs to the pane the buyer is looking at, and this covers the step
+ * that has no pane of its own.
+ *
+ * The two can never run together: this one is gated on the confirmation step,
+ * and every screen that polls renders on the payment step.
+ */
+
+/** How often the confirmation screen asks. The same cadence the panes open at. */
+const CONFIRMATION_INTERVAL_MS = 2_500;
+
+/**
+ * How long it asks for, in WALL TIME — the card pane's bound, for the same
+ * reason it has one: past this point the spinner is no longer a description of
+ * anything, and the honest screen says so and offers the buyer the ask.
+ *
+ * Nothing is lost when it elapses. The order stays AWAITING server-side and is
+ * still recoverable by webhook, reconciliation or backfill; what changes is
+ * only that the screen stops pretending to watch.
+ */
+const CONFIRMATION_WAIT_MS = 90_000;
+
+/** What the confirmation screen reads off a wait it owns. */
+export interface ConfirmationWait {
+  /** The bound elapsed — nothing further is scheduled. */
+  timedOut: boolean;
+  /** The last ask failed, and the wait is still running (FUT-1144). */
+  error: string | null;
+  /** Ask now, and start the clock over. */
+  checkAgain: () => void;
+}
+
+/**
+ * Watch the order the flow is holding, while the confirmation screen is the one
+ * on display and nothing has settled it yet.
+ *
+ * @param active Whether this wait is the live one. FALSE for every checkout
+ *   that has an answer already, and for every step that polls for itself — the
+ *   caller decides, because only it knows which screen is up.
+ * @param onSettled A terminal status arrived. Called once per status, with the
+ *   status only: whether it carries a refusal is the charge path's knowledge and
+ *   a poll has none of it.
+ */
+export function useConfirmationWait(input: {
+  orderId: string | null;
+  active: boolean;
+  onSettled: (status: OrderStatus) => void;
+}): ConfirmationWait {
+  const { orderId, active, onSettled } = input;
+  const { status, error, timedOut, checkAgain } = usePaymentPolling(orderId, {
+    enabled: active,
+    intervalMs: CONFIRMATION_INTERVAL_MS,
+    maxWaitMs: CONFIRMATION_WAIT_MS,
+  });
+
+  useEffect(() => {
+    if (!active || !status || status === "AWAITING_PAYMENT") return;
+    onSettled(status);
+  }, [active, status, onSettled]);
+
+  // Reported only while this wait is the live one. A bound that elapsed for an
+  // order the flow has since settled must not turn a paid confirmation into a
+  // warning, and `usePaymentPolling` keeps its last answer after `enabled` goes
+  // false — deliberately, so a settled wait can still be read.
+  return {
+    timedOut: active && timedOut,
+    error: active ? error : null,
+    checkAgain,
+  };
+}

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

@@ -134,4 +134,12 @@ export const EN_US_CHECKOUT_VIEW_COPY: CheckoutViewCopy = {
     action: "See the menu",
   },
   status: EN_US_PAYMENT_STATUS_COPY,
+  pipeline: {
+    loading: "Loading…",
+    // The KEYS are the package's own settlement-method ids, never words.
+    awaitingHandover: {
+      PIX: "Opening Pix…",
+      CARD: "Opening the card payment…",
+    },
+  },
 };

package/src/components/checkout/failure-codes.ts

@@ -15,3 +15,85 @@
  * one and must not word it as a failure.
  */
 export const UNRESOLVED_CODE = "PAYMENT_UNRESOLVED";
+
+/**
+ * REFUSALS RE-SENDING THE SAME REQUEST CANNOT CLEAR (FUT-1182).
+ *
+ * A different exception from {@link UNRESOLVED_CODE}, and the difference is
+ * worth keeping: an unresolved charge withholds the retry because pressing it
+ * could take the buyer's money twice. These withhold it because pressing it
+ * cannot do anything at all. The order was refused for a fact about the world —
+ * the shop is shut, the mode is off, the booked slot is gone, the basket has
+ * already been paid for, the merchant has connected no provider — and the
+ * identical POST meets the identical fact. So the button was the screen's most
+ * prominent control and it was guaranteed to fail, phrased as though the buyer
+ * had got something wrong.
+ *
+ * ## Why a package names a host's vocabulary here
+ *
+ * Because the alternative is worse in both directions. A prop the host fills
+ * would leave every host that has not filled it with the defect this exists to
+ * remove; and a rule inferred from the STATUS code cannot separate these from
+ * the 400s and 409s that a retry genuinely clears (`CHARGE_MISMATCH` is a 409
+ * and re-raising is exactly what fixes it).
+ *
+ * What makes it safe is that the list is CLOSED and its members are wire
+ * constants: this file already names `PAYMENT_UNRESOLVED` for the same reason,
+ * and the transport beside it already speaks the routes those codes arrive on.
+ * A host that answers none of these loses nothing — an unknown code keeps the
+ * retry, which is the pre-1182 behaviour for every code.
+ *
+ * ## It never SUPPRESSES the message, only the button
+ *
+ * The host half of this ticket (FUT-1166) acts on the same codes: it refetches
+ * whatever was stale, so the screen behind the refusal corrects itself into the
+ * gate that says what the buyer can actually do. The refusal's own sentence has
+ * to stay on screen while that happens, or a shopper watches a checkout
+ * rearrange itself for no stated reason.
+ *
+ * ## What is deliberately NOT here
+ *
+ * `BASKET_NOT_FOUND` and `MODE_CATALOG_SCOPE`, because this list is the
+ * GUARANTEED half. Both name states a fresh read can legitimately answer
+ * differently, and withholding the retry on a maybe is how a buyer with a
+ * recoverable problem ends up with no control at all — the same asymmetry
+ * `CheckoutDecline.retriable` settles by treating silence as yes.
+ */
+const NO_RETRY_CODES: readonly string[] = [
+  // The shop is shut, or shut by the time the slot came round.
+  "STORE_CLOSED",
+  "SCHEDULE_UNAVAILABLE",
+  // The store does not sell this way — a bookmarked URL, or a mode cookie that
+  // outlived the config allowing it.
+  "MODE_UNAVAILABLE",
+  // No provider connected. TWO spellings on purpose: the package's own routes
+  // answer `PAYMENT_NOT_CONFIGURED`, and a host that guards its order route
+  // before delegating answers its own. A client meets both.
+  "PAYMENT_NOT_CONFIGURED",
+  "PAYMENTS_NOT_CONFIGURED",
+  // Already bought — in another tab, or by whoever was settling alongside them.
+  // Retrying cannot un-pay it; the buyer wants their purchases, not this step.
+  "CART_ALREADY_PAID",
+  "BASKET_ALREADY_BOUGHT",
+  // Nothing left to charge for, and this step cannot put anything back.
+  "EMPTY_CART",
+  "COMANDA_CLOSED",
+  // The order cannot be delivered as asked. Fixed where the address is, which
+  // is not here.
+  "DELIVERY_UNAVAILABLE",
+  "DELIVERY_ADDRESS_REQUIRED",
+];
+
+/**
+ * Whether the surface may offer to send this refused order again.
+ *
+ * SILENCE MEANS YES, and so does anything unrecognised: a refusal with no code,
+ * or one from a server this bundle is a release behind, keeps the retry. The
+ * two packages version independently and a host may answer a vocabulary of its
+ * own, so "never heard of it" has to degrade to the old behaviour rather than
+ * to a screen with nothing on it.
+ */
+export function retryMayHelp(code: string | null | undefined): boolean {
+  if (code === undefined || code === null) return true;
+  return !NO_RETRY_CODES.includes(code);
+}

package/src/components/checkout/hosted-store.ts

@@ -259,7 +259,18 @@ export function isStale(parked: ParkedHostedOrder): boolean {
  * ask, FUT-1146's release, and the settle that ends a checkout normally), so
  * callers other than the read need a way to say "this one is finished".
  */
-export function forgetHostedOrder(): void {
+export function forgetHostedOrder(tenantSlug?: string): void {
+  // SCOPED WHEN THE CALLER KNOWS WHOSE CHECKOUT IT IS (FUT-1240). One tab
+  // holds one slot for every store on a multi-tenant storefront, so an
+  // unscoped clear is a clear of whichever store happens to be parked — the
+  // mirror image of the unscoped RESUME the slug closed, and just as quiet: a
+  // shopper who switched stores mid-hand-off loses the confirmation for a
+  // payment they made, with nothing on screen to say why.
+  //
+  // The no-argument call is unchanged and still clears whatever is there. It
+  // is what a caller with no slug in hand means, and it is the read side's
+  // own rule: an entry nobody can attribute belongs to everybody.
+  if (tenantSlug !== undefined && !parkedBelongsTo(tenantSlug)) return;
   try {
     window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
     window.sessionStorage?.removeItem(LEGACY_KEY);
@@ -267,3 +278,14 @@ export function forgetHostedOrder(): void {
     // Storage disabled — there was nothing to clear.
   }
 }
+
+/**
+ * Whether what is parked (if anything) is this store's.
+ *
+ * `true` with nothing parked, deliberately: there is no other store's entry to
+ * protect, and answering `false` would leave a stale key nobody may delete.
+ */
+function parkedBelongsTo(tenantSlug: string): boolean {
+  const parked = readParked();
+  return parked === null || belongsHere(parked, tenantSlug);
+}

package/src/components/checkout/payment-error-panel.tsx

@@ -2,14 +2,14 @@ import { Box } from "@mui/material";
 import { useState, type JSX } from "react";
 
 import { useCheckoutCopy } from "./copy-context";
-import { UNRESOLVED_CODE } from "./failure-codes";
+import { retryMayHelp, UNRESOLVED_CODE } from "./failure-codes";
 import { useCheckoutComponents } from "./ui";
 
 /**
  * Order-creation failure shown inline on Pagamento — the buyer never leaves the
  * step. Split out of `checkout-steps.tsx` when it grew a second presentation.
  *
- * Three shapes, and which one renders is decided by the failure's CODE, never
+ * Four shapes, and which one renders is decided by the failure's CODE, never
  * by its prose:
  *
  *  - the buyer e-mail was rejected (the owner testing with the store's own
@@ -19,6 +19,10 @@ import { useCheckoutComponents } from "./ui";
  *    a new reference, outside the walk's re-probe of the old one: precisely
  *    the double payment the message forbids, offered as the panel's most
  *    prominent affordance;
+ *  - the refusal is about the WORLD rather than the payment (FUT-1182) — the
+ *    ordinary danger Alert, and no retry either. Re-sending the identical
+ *    request meets the identical shut shop; see `retryMayHelp` for the list and
+ *    for why the sentence stays while the button goes;
  *  - anything else — the ordinary danger Alert with a retry.
  */
 export function PaymentErrorPanel({
@@ -48,7 +52,9 @@ export function PaymentErrorPanel({
         showIcon
         data-testid={unresolved ? "checkout-unresolved" : "checkout-error"}
       />
-      {unresolved ? null : <RetryAffordance {...{ emailFlagged, onUseEmail, onRetry }} />}
+      {!unresolved && retryMayHelp(code) ? (
+        <RetryAffordance {...{ emailFlagged, onUseEmail, onRetry }} />
+      ) : null}
     </Box>
   );
 }

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

@@ -1,9 +1,10 @@
 import { Box } from "@mui/material";
-import { useEffect, useState, type JSX } from "react";
+import { useEffect, useMemo, useState, type JSX } from "react";
 import QRCode from "react-qr-code";
 
 import { useCheckoutCopy } from "./copy-context";
 import { ContentCopyIcon } from "./icons";
+import type { SettlingCopy } from "./screens-copy";
 import { StalledWait } from "./stalled-wait";
 import type { CheckoutOrder, OrderStatus, PixCharge } from "./types";
 import { useCheckoutComponents } from "./ui";
@@ -16,6 +17,54 @@ import { usePaymentPolling } from "./use-payment-polling";
  * the payment-status screen.
  */
 
+/**
+ * How many polls at the opening cadence before the wait decays (FUT-1170).
+ *
+ * Twelve is thirty seconds at the default 2.5 s, which is the window the common
+ * case lives in: a buyer on this screen has the QR in front of them and pays
+ * within a few taps, and the answer lands within seconds of the webhook.
+ * Everything after that window is an abandoned tab, or a shopper who has gone
+ * to fetch a different phone — and paying full cadence for it taxes the case
+ * that matters to subsidise the one that does not.
+ */
+const PIX_FAST_POLLS = 12;
+
+/**
+ * The decayed cadence. Six asks a minute rather than twenty-four, and the two
+ * re-arm events (`visibilitychange`, `online`) still poll IMMEDIATELY when the
+ * buyer comes back from their bank app — which is the moment they are waiting
+ * on, so the slow phase costs them nothing there.
+ */
+const PIX_SLOW_INTERVAL_MS = 15_000;
+
+/**
+ * How long the wait outlives the code itself.
+ *
+ * The bound is the CHARGE's expiry, because that is the fact that ends this
+ * screen: after it, the server flips the order and answers a terminal EXPIRED.
+ * The grace is room for that flip to happen and be observed — stopping exactly
+ * at the expiry would end the wait one poll before the answer it exists for.
+ */
+const PIX_EXPIRY_GRACE_MS = 60_000;
+
+/**
+ * The bound for a charge whose expiry cannot be read — a malformed instant, or
+ * an order that arrived without one.
+ *
+ * Unbounded is not the safe reading. It was the shipped one, and it is what let
+ * a forgotten tab ask a provider every 2.5 s for as long as it stayed open. A
+ * quarter of an hour is longer than any PIX code this checkout raises, and the
+ * buyer gets the ask back with one press.
+ */
+const PIX_FALLBACK_WAIT_MS = 15 * 60_000;
+
+/** How long to keep asking about this charge — see the constants above. */
+function pixWaitMs(expiresAt: string | undefined): number {
+  const deadline = expiresAt === undefined ? Number.NaN : Date.parse(expiresAt);
+  if (Number.isNaN(deadline)) return PIX_FALLBACK_WAIT_MS;
+  return Math.max(0, deadline - Date.now()) + PIX_EXPIRY_GRACE_MS;
+}
+
 /** The copyable "copia e cola" strip with its copy button. */
 function PixCodeBox({ pix }: { pix: PixCharge }): JSX.Element {
   const { Button, Text } = useCheckoutComponents();
@@ -72,35 +121,66 @@ function PixCodeBox({ pix }: { pix: PixCharge }): JSX.Element {
   );
 }
 
+/**
+ * Which of the wait's three faces the footer is showing — STOPPED, then STILL
+ * TRYING, then working.
+ *
+ * The card pane's order, and for its reason (`SubmittedState`): a wait that
+ * failed its way to its own clock carries both flags, and "we keep trying" over
+ * a wait nothing is scheduled for is the lie. The sentences are the shared
+ * {@link SettlingCopy} ones, so the two panes say the same thing about the same
+ * situation rather than drifting into two accounts of it.
+ */
+function pixWaitPanel(
+  copy: SettlingCopy,
+  error: string | null,
+  timedOut: boolean,
+): { title: string; description: string; testId: string } | null {
+  if (timedOut) {
+    return { title: copy.takingLonger, description: copy.takingLongerHelp, testId: "pix-poll-timeout" };
+  }
+  if (error) return { title: copy.connectionLost, description: error, testId: "pix-poll-error" };
+  return null;
+}
+
 /**
  * The live footer: the pulsing "awaiting payment" indicator, or — while the
- * poll cannot reach us — the same wait said out loud, with a way to hurry it.
+ * poll cannot reach us, or once it has stopped — the same wait said out loud,
+ * with a way to restart it.
  *
  * A WARNING rather than a danger (FUT-1144). The old red panel said "não foi
  * possível confirmar o pagamento" and meant it: four consecutive failures ended
  * the wait, so a shopper who paid during a ten-second blip watched a QR under a
  * final-sounding refusal that would never update. The QR is still good, the
  * wait is still running, and the sentence now says both.
+ *
+ * The elapsed face is FUT-1170's half. The PIX wait is bounded now, and a bound
+ * that stops the polling without changing what is on screen is the same silent
+ * failure one screen later: a pulsing dot beside "Aguardando pagamento…" for a
+ * wait that is no longer asking anything.
  */
 function PixPollFooter({
   error,
+  timedOut,
   onCheckAgain,
 }: {
   error: string | null;
+  timedOut: boolean;
   onCheckAgain: () => void;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const { pix, settling } = useCheckoutCopy().screens;
-  if (error) {
+  const panel = pixWaitPanel(settling, error, timedOut);
+  if (panel) {
     // The same panel the card and wallet panes show, held to the width of the
     // copy-and-paste strip above it so the centred PIX column stays a column.
     return (
       <Box sx={{ width: "100%", maxWidth: 420 }}>
         <StalledWait
-          title={settling.connectionLost}
-          description={error}
+          title={panel.title}
+          description={panel.description}
           onCheckAgain={onCheckAgain}
-          testId="pix-poll-error"
+          testId={panel.testId}
           actionTestId="pix-check-again"
         />
       </Box>
@@ -127,8 +207,17 @@ export function PixView({
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
-  const { status, error, checkAgain } = usePaymentPolling(order.orderId, {
+  // Fixed once per charge (FUT-1170): the bound is a span, so recomputing it
+  // every render would keep pushing the deadline out — and it is an effect
+  // dependency, so it would also restart the wait on every render.
+  const expiresAt = order.pix?.expiresAt;
+  const maxWaitMs = useMemo(() => pixWaitMs(expiresAt), [expiresAt]);
+  const { status, error, timedOut, checkAgain } = usePaymentPolling(order.orderId, {
     intervalMs: pollIntervalMs,
+    slowAfterPolls: PIX_FAST_POLLS,
+    // Never FASTER than the opening cadence: a host that opens slowly means it.
+    slowIntervalMs: Math.max(pollIntervalMs, PIX_SLOW_INTERVAL_MS),
+    maxWaitMs,
   });
 
   // Bubble a terminal status up once, so the parent can advance to the status step.
@@ -182,7 +271,7 @@ export function PixView({
         {copy.validUntil(validUntil)}
       </Text>
 
-      <PixPollFooter error={error} onCheckAgain={checkAgain} />
+      <PixPollFooter error={error} timedOut={timedOut} onCheckAgain={checkAgain} />
     </Box>
   );
 }

package/src/components/checkout/poll-loop.ts

@@ -32,8 +32,10 @@ export interface PollingOptions {
   /**
    * WALL-CLOCK bound on the whole wait (FUT-1144): stop scheduling and report
    * `timedOut` once this many milliseconds have passed since the wait began.
-   * Undefined ⇒ unbounded (the PIX consumer passes none — its charge expires
-   * server-side and comes back as a terminal EXPIRED).
+   * Undefined ⇒ unbounded, which no consumer here is any more. PIX passed none
+   * — its charge expires server-side and comes back terminal, true of a tab
+   * somebody is watching and not of one left open in a pocket, which asked a
+   * provider every 2.5 s for as long as it lived (FUT-1170).
    *
    * It used to be a count of HEALTHY polls, which measured the wrong thing in
    * the only case that matters. A wait that is failing makes no healthy polls,
@@ -126,7 +128,7 @@ function pollDelay(healthy: number, errors: number, options: PollingOptions): nu
 }
 
 /** Where a running wait writes what it has learned. */
-interface PollSink {
+export interface PollSink {
   setStatus: (status: OrderStatus) => void;
   setError: (error: string | null) => void;
   setTimedOut: (timedOut: boolean) => void;

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

@@ -125,4 +125,13 @@ export const PT_BR_CHECKOUT_VIEW_COPY: CheckoutViewCopy = {
     action: "Ver cardápio",
   },
   status: PT_BR_PAYMENT_STATUS_COPY,
+  pipeline: {
+    loading: "Carregando…",
+    // Keyed by the settlement method's id. The package registers PIX and CARD;
+    // a host that registers another charged method adds its own line here.
+    awaitingHandover: {
+      PIX: "Abrindo o Pix…",
+      CARD: "Abrindo o pagamento com cartão…",
+    },
+  },
 };

package/src/components/checkout/types.ts

@@ -185,6 +185,17 @@ export interface CreateOrderRequest {
   buyer: BuyerInfo;
   /** Opt-in: save buyer name/phone (not CPF — never persisted here) for next-checkout pre-fill. */
   saveProfile: boolean;
+  /**
+   * WHICH settlement the buyer chose, when it is not one of the two above
+   * (FUT-1240).
+   *
+   * `method` is what the CHAIN can be asked to charge, so a pipeline host's own
+   * registered settlement — "pay the courier", "pay the waiter" — cannot be
+   * said there, and without this every one of them arrives as the same request.
+   * ABSENT for `PIX` and `CARD`, which is what keeps it additive; otherwise the
+   * registered `SettlementMethodDescriptor.id` verbatim (`flows/pipeline`).
+   */
+  settlementMethod?: string;
 }
 
 /** What the flow hands the host's `saveBuyerContact` port on "Continuar". */