@12-apps/payments-frontend 3.19.0 → 3.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.19.0",
+  "version": "3.20.1",
   "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.26.0",
+    "@12-apps/payments-backend": "^4.26.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

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

@@ -10,45 +10,47 @@ import {
 
 import { useCheckoutCopy } from "./copy-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
+import { StalledWait } from "./stalled-wait";
 import type { CardChainLink } from "./method-capability";
 import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
-import { useCardCheckout } from "./use-card-checkout";
+import { useCardCheckout, type CardCheckout } from "./use-card-checkout";
 
 /**
- * Post-submit confirmation state, error > timeout > spinner (FUT-191): a poll
- * failure is a danger Alert, the healthy-poll cap elapsing is a warning (the
- * order stays AWAITING server-side and is recoverable by webhook/reconcile/
- * backfill), and otherwise the — now bounded — confirmation spinner shows.
+ * Post-submit confirmation state: timeout > error > spinner.
+ *
+ * The elapsed wall-clock wait leads (the order stays AWAITING server-side and is
+ * recoverable by webhook/reconcile/backfill, which is what its copy says), then
+ * a poll that cannot reach us — a warning saying we are STILL TRYING, where
+ * FUT-1144 found a danger Alert over a wait that had actually given up — then
+ * the ordinary bounded spinner.
+ *
+ * That order inverted with the meaning of the two flags. An error used to BE the
+ * ending; now the clock is, and a wait that failed its way to the clock carries
+ * both. "We keep trying" over a wait nothing is scheduled for is the lie.
  */
-function SubmittedState({
-  pollError,
-  pollTimedOut,
-}: {
-  pollError: string | null;
-  pollTimedOut: boolean;
-}): JSX.Element {
-  const { Alert, LoadingState } = useCheckoutComponents();
+function SubmittedState({ card }: { card: CardCheckout }): JSX.Element {
+  const { LoadingState } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.settling;
-  if (pollError) {
+  if (card.pollTimedOut) {
     return (
-      <Alert
-        variant="danger"
-        title={copy.cannotConfirm}
-        description={pollError}
-        showIcon
-        data-testid="card-poll-error"
+      <StalledWait
+        title={copy.takingLonger}
+        description={copy.takingLongerHelp}
+        onCheckAgain={card.pollCheckAgain}
+        testId="card-poll-timeout"
+        actionTestId="card-check-again"
       />
     );
   }
-  if (pollTimedOut) {
+  if (card.pollError) {
     return (
-      <Alert
-        variant="warning"
-        title={copy.takingLonger}
-        description={copy.takingLongerHelp}
-        showIcon
-        data-testid="card-poll-timeout"
+      <StalledWait
+        title={copy.connectionLost}
+        description={card.pollError}
+        onCheckAgain={card.pollCheckAgain}
+        testId="card-poll-error"
+        actionTestId="card-check-again"
       />
     );
   }
@@ -139,7 +141,7 @@ export function CardView({
   const unresolved = cc.errorCode === UNRESOLVED_CODE;
 
   if (cc.submitted) {
-    return <SubmittedState pollError={cc.pollError} pollTimedOut={cc.pollTimedOut} />;
+    return <SubmittedState card={cc} />;
   }
 
   return (

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

@@ -7,6 +7,7 @@ import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
 import { CheckoutCopyProvider } from "./copy-context";
+import { OneClickProvider, useOneClick } from "./one-click";
 import { CheckoutComponentsProvider, useCheckoutComponents, type CheckoutComponents } from "./ui";
 import type { CheckoutViewCopy } from "./view-copy";
 import { useCheckoutController, type CheckoutHostPorts } from "./use-checkout-controller";
@@ -59,6 +60,17 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   providerConfig?: CheckoutProviderConfig | null;
   /** Scopes the saved-card list to the store being paid. */
   tenantSlug?: string;
+  /**
+   * The buyer pressed a BUY button rather than opening a checkout — pay with
+   * their saved card and land them on Confirmação, with no tap in between.
+   *
+   * A REQUEST, never an instruction: it is honoured only where it can be, and
+   * degrades to the ordinary flow everywhere else — a store that finishes on
+   * the provider's page, a buyer with no CPF on file, a buyer with no saved
+   * card. See `./one-click.tsx` for the whole decision and why every clause
+   * narrows toward standing down.
+   */
+  oneClick?: boolean;
   /**
    * The host's Apple Pay merchant-validation port (FUT-472): exchange the
    * session's `validationURL` for an Apple merchant session, SERVER-SIDE.
@@ -162,18 +174,24 @@ function StatusStep({
       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}
     />
   );
 }
 
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, ...ports } = props;
+  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, oneClick = false, ...ports } = props;
   // Resolved for NO method on purpose (FUT-595): the Dados step opens before
   // the picker, and the form is filled once — so it asks for the union of what
   // any chain member may need rather than re-opening after the choice. A chain
   // that declares nothing degrades to CPF-required, never to "ask nothing".
   const buyerFields = useMemo(() => buyerFieldsFor(providerConfig?.chain, null), [providerConfig]);
   const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields, tenantSlug);
+  const armed = useOneClick({ requested: oneClick, config: providerConfig, taxIdOnFile, step: c.step, method: c.method, setMethod: c.setMethod });
 
   // A settlement settlement pays already-sent kitchen items — the cart is
   // legitimately empty here, so the empty-cart guard only applies to cart mode.
@@ -210,25 +228,27 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       ) : null}
 
       {c.step === "payment" ? (
-        <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)}
-          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}
-          validateApplePayMerchant={validateApplePayMerchant}
-          onResolved={c.handleResolved}
-        />
+        <OneClickProvider armed={armed}>
+          <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)}
+            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}
+            validateApplePayMerchant={validateApplePayMerchant}
+            onResolved={c.handleResolved}
+          />
+        </OneClickProvider>
       ) : null}
 
       {c.step === "status" ? (

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

@@ -40,8 +40,17 @@ export const EN_US_PAYMENT_STATUS_COPY: PaymentStatusCopy = {
       "If you have already paid, the order is confirmed as soon as the provider tells us — " +
       "do not pay again. You can close this screen.",
   },
+  awaitingUnreachable: {
+    heading: "We cannot reach the payment right now",
+    // "do not pay again" leads the second sentence for the same reason it
+    // leads `awaitingTimedOut`: a second payment is the expensive mistake.
+    support:
+      "We are still trying. If you have already paid, do not pay again — " +
+      "the order is confirmed as soon as the provider tells us.",
+  },
   retryAction: "Try again",
   regenerateAction: "Generate a new code",
+  checkAgainAction: "Check again",
   backAction: "Back to the menu",
   amountLabel: "Amount paid",
   referenceLabel: "Order",

package/src/components/checkout/one-click.tsx

@@ -0,0 +1,179 @@
+/**
+ * ONE-CLICK checkout — the buyer who already decided (FUT-1070).
+ *
+ * A storefront can offer a BUY button beside a product or a past order: press
+ * it and the shopper expects to have bought, not to be handed a form. The
+ * whole flow that follows already exists — Pagamento raises the order, the
+ * card path charges a saved instrument, Confirmação reports the outcome — and
+ * every step of it is a tap the buyer has already made by pressing that
+ * button. So one-click makes those taps, in order, and reaches the same
+ * terminal screen through the same code the ordinary flow uses.
+ *
+ * That reuse is the design, not an economy. A second charge path would be a
+ * second answer to "what does paying with a saved card do", and the two would
+ * eventually disagree about failover instruments, the unresolved-charge rule,
+ * or the poll cap — each of which is money.
+ *
+ * ## It arms, or it stands down. It never guesses.
+ *
+ * `armedFor` is the whole decision, and every clause narrows toward
+ * NOT arming, because the failure directions are not symmetric: standing down
+ * costs a buyer the taps they would have made anyway, and arming wrongly
+ * charges a card nobody chose.
+ *
+ * - **No request** — the host did not ask. This is every ordinary checkout.
+ * - **No CPF on file** — the buyer still has a Dados step to fill (FUT-465),
+ *   so there is no tap to skip and the flow opens where it always did. In
+ *   practice a buyer with a saved card has one; a buyer without one is a buyer
+ *   we have never charged.
+ * - **No protocol yet** (`config === null`, still loading or a fetch blip) —
+ *   the ordinary flow fails OPEN here and renders a picker the server may
+ *   refuse, which costs a tap. Arming on the same guess would raise a charge.
+ * - **The choice is not ours to ask** — a store that finishes on the
+ *   provider's own page has no card path in this browser at all, and the one
+ *   thing one-click must never do is redirect a checkout the moment it
+ *   renders. This is the InfinitePay shape, and it is why a store on a hosted
+ *   provider degrades to the ordinary hand-off screen with nothing else
+ *   changed.
+ * - **No card path** — the chain declares no CARD entry this browser can mint
+ *   or charge for.
+ *
+ * The last condition cannot be answered here at all: **whether the buyer has a
+ * saved card**. That list is fetched by the card path itself, scoped to the
+ * store, and asking for it twice would be two answers to one question. So an
+ * armed flow selects the card tile and the card view does the rest —
+ * {@link useOneClickPay} pays only once a SAVED card is the selection, which
+ * is a state the picker can only reach after the list came back non-empty. A
+ * buyer with no saved card therefore lands on Pagamento with the picker and
+ * the card form, which is exactly the ordinary step 2.
+ */
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  type JSX,
+  type ReactNode,
+} from "react";
+
+import { cardPathAvailable } from "./method-capability";
+import { methodChosenAtProvider } from "./providers/registry";
+import type { CheckoutProviderConfig, PaymentMethod } from "./types";
+
+/**
+ * Whether the flow above this subtree is running as one-click.
+ *
+ * CONTEXT rather than a prop, because the consumer is the card path — four
+ * layers down, behind the published `ProviderCheckoutScreen` contract that
+ * every provider screen implements. Threading a flag through it would widen a
+ * contract that three screens share for the benefit of one, and would oblige
+ * an out-of-tree screen to forward a prop it has no use for.
+ */
+const OneClickContext = createContext(false);
+
+/** Arm (or explicitly disarm) one-click for everything below. */
+export function OneClickProvider({
+  armed,
+  children,
+}: {
+  armed: boolean;
+  children: ReactNode;
+}): JSX.Element {
+  return <OneClickContext.Provider value={armed}>{children}</OneClickContext.Provider>;
+}
+
+/** Whether this subtree is a one-click checkout. `false` outside a provider. */
+export function useOneClickArmed(): boolean {
+  return useContext(OneClickContext);
+}
+
+/**
+ * Can this store honour a one-click request right now? See the module comment
+ * for why every clause narrows toward `false`.
+ *
+ * `step` is what keeps the answer honest over TIME rather than only at mount:
+ * a resumed hosted return opens on Confirmação, and a buyer who walked back to
+ * Dados is a buyer who took over. Neither is a checkout that should still be
+ * charging on its own.
+ */
+function armedFor(input: OneClickFlow): boolean {
+  const { requested, config, taxIdOnFile, step } = input;
+  if (!requested || !taxIdOnFile || step !== "payment" || !config) return false;
+  if (methodChosenAtProvider(config.chain?.[0]?.checkoutScreen, config)) return false;
+  return cardPathAvailable(config);
+}
+
+/** What the flow knows that decides whether one-click may run, and how it starts. */
+interface OneClickFlow {
+  /** The host asked for one-click on this checkout. */
+  requested: boolean;
+  /** The store's published protocol; `null` while it is still unknown. */
+  config: CheckoutProviderConfig | null | undefined;
+  /** The buyer's CPF is already saved, so there is no Dados step to fill. */
+  taxIdOnFile: boolean;
+  /** Which step the flow is showing — one-click only ever runs on Pagamento. */
+  step: string;
+  /** The method currently selected, or `null` before any choice. */
+  method: PaymentMethod | null;
+  /** Selecting a method — the same event a picker tile press is. */
+  setMethod: (method: PaymentMethod) => void;
+}
+
+/**
+ * Arm one-click for this render, and take the card tile for the buyer ONCE
+ * when it is armed.
+ *
+ * Selecting a method is what raises the order (`useAutoRaiseOrder`), so that
+ * one call starts everything downstream — and it is the same event a tile
+ * press is, which is why nothing else in the flow has to change.
+ *
+ * Once only, by ref. `setMethod` clears any order raised for a previous
+ * method, so a re-fire would discard a live charge and raise a second; and a
+ * buyer who switches to PIX after this ran must be allowed to stay there.
+ */
+export function useOneClick(flow: OneClickFlow): boolean {
+  const armed = armedFor(flow);
+  const { method, setMethod } = flow;
+  const taken = useRef(false);
+  useEffect(() => {
+    if (!armed || taken.current || method !== null) return;
+    taken.current = true;
+    setMethod("CARD");
+  }, [armed, method, setMethod]);
+  return armed;
+}
+
+/**
+ * Press "Pagar" for the buyer, ONCE, when a saved card is what is selected.
+ *
+ * `ready` is the caller's whole precondition and is deliberately narrow: a
+ * SAVED card is the current selection and no charge is in flight, has landed,
+ * or has already failed. It can only become true after the instrument list
+ * came back with something, which is what makes "the buyer has no saved card"
+ * a silent stand-down rather than a branch.
+ *
+ * The submit is held in a ref because `handlePay` is rebuilt every render;
+ * depending on it directly would re-run this effect constantly and leave the
+ * once-only guard as the only thing between a shopper and a second charge.
+ * One guard for one job: the ref fires it, `fired` decides whether it may.
+ *
+ * A DECLINE is terminal for one-click, and that is the point of listing
+ * `error` in `ready`: the buyer's own "Pagar R$ …" comes back under the
+ * refusal, and retrying a declined card automatically is how a shopper gets
+ * three identical declines they never asked for.
+ */
+export function useOneClickPay(input: {
+  armed: boolean;
+  ready: boolean;
+  pay: () => Promise<void>;
+}): void {
+  const { armed, ready } = input;
+  const submit = useRef(input.pay);
+  submit.current = input.pay;
+  const fired = useRef(false);
+  useEffect(() => {
+    if (!armed || !ready || fired.current) return;
+    fired.current = true;
+    void submit.current();
+  }, [armed, ready]);
+}

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

@@ -4,7 +4,7 @@ import type { JSX, ReactNode } from "react";
 import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
 import type { OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
-import type { PaymentStatusCopy } from "./view-copy";
+import type { PaymentStatusCopy, StatusOutcomeCopy } from "./view-copy";
 
 /**
  * The last screen of checkout.
@@ -79,37 +79,65 @@ function orderReference(orderId: string): string {
   return orderId.replace(/-/g, "").slice(0, 8).toUpperCase();
 }
 
+/** How the wait itself is going, when it has not resolved into an outcome. */
+interface WaitState {
+  /** The bounded wall-clock wait elapsed — nothing further is scheduled. */
+  timedOut: boolean;
+  /** The last poll failed, and the wait is still running (FUT-1144). */
+  unreachable: boolean;
+}
+
+/**
+ * Which of AWAITING's three faces this is.
+ *
+ * STOPPED beats STILL TRYING, and the order is the whole honesty of the screen.
+ * A wait that ran its clock out while failing carries BOTH flags — the last
+ * poll's error is still the last thing that happened — and saying "we keep
+ * trying" over a wait nothing is scheduled for is precisely the lie this ticket
+ * exists to remove. The elapsed state is also the one carrying "não pague de
+ * novo", which is the sentence that matters most when we have stopped looking.
+ *
+ * Both keep AWAITING's neutral clock icon and take WARNING's tone: the order is
+ * not resolved, and calm-but-alert is the visual for that.
+ */
+function awaitingFace(
+  copy: PaymentStatusCopy,
+  wait: WaitState,
+): { outcome: StatusOutcomeCopy; tone: OutcomeVisual["tone"]; testId: string } | null {
+  if (wait.timedOut) {
+    return { outcome: copy.awaitingTimedOut, tone: "warning", testId: "payment-awaiting-timeout" };
+  }
+  if (wait.unreachable) {
+    return { outcome: copy.awaitingUnreachable, tone: "warning", testId: "payment-awaiting-unreachable" };
+  }
+  return null;
+}
+
 /** The headline block: icon, outcome, and one supporting line. */
 function OutcomeHero({
   copy,
   status,
-  timedOut = false,
+  wait,
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
-  timedOut?: boolean;
+  wait: WaitState;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
-  const timedOutWait = timedOut && status === "AWAITING_PAYMENT";
-  // The timed-out wait keeps AWAITING's neutral clock icon but WARNING's tone:
-  // the order is not resolved, and calm-but-alert is the visual for that.
-  const visual = timedOutWait
-    ? { icon: OUTCOME_VISUAL.AWAITING_PAYMENT.icon, tone: "warning" as const }
+  const face = status === "AWAITING_PAYMENT" ? awaitingFace(copy, wait) : null;
+  const visual = face
+    ? { icon: OUTCOME_VISUAL.AWAITING_PAYMENT.icon, tone: face.tone }
     : OUTCOME_VISUAL[status];
-  const outcome = timedOutWait ? copy.awaitingTimedOut : copy[OUTCOME_COPY_KEY[status]];
+  const outcome = face ? face.outcome : copy[OUTCOME_COPY_KEY[status]];
   return (
     <Box
       // `payment-paid` is load-bearing for the storefront journeys — it is how
-      // they assert the buyer actually got there. The timed-out wait gets its
+      // they assert the buyer actually got there. Each unsettled wait gets its
       // OWN id rather than reusing `payment-awaiting_payment`: a test that
-      // cannot tell "still asking" from "stopped asking" is a test that would
-      // pass against the unbounded spinner this replaced.
+      // cannot tell "still asking" from "stopped asking" from "cannot reach the
+      // payment" is a test that would pass against the spinner this replaced.
       data-testid={
-        timedOut && status === "AWAITING_PAYMENT"
-          ? "payment-awaiting-timeout"
-          : status === "PAID"
-            ? "payment-paid"
-            : `payment-${status.toLowerCase()}`
+        face ? face.testId : status === "PAID" ? "payment-paid" : `payment-${status.toLowerCase()}`
       }
       sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
     >
@@ -176,23 +204,41 @@ function PaidFacts({
   );
 }
 
-/** The next-action row: retry / regenerate for failures, always back-to-menu. */
+/** The next-action row: retry / regenerate / check-again, always back-to-menu. */
 function StatusActions({
   copy,
   status,
   onRetry,
   onRegenerate,
+  onCheckAgain,
   onBackToMenu,
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
   onRetry?: () => void;
   onRegenerate?: () => void;
+  /**
+   * Offered only while the wait is unsettled AND not visibly working — the
+   * caller decides that; here it is simply present or absent. A button under a
+   * healthy spinner would invite a tap that changes nothing.
+   */
+  onCheckAgain?: () => void;
   onBackToMenu: () => void;
 }): JSX.Element {
   const { Button } = useCheckoutComponents();
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      {onCheckAgain ? (
+        <Button
+          variant="solid"
+          color="primary"
+          size="lg"
+          onClick={onCheckAgain}
+          dataTestId="payment-check-again"
+        >
+          {copy.checkAgainAction}
+        </Button>
+      ) : null}
       {status === "FAILED" && onRetry ? (
         <Button variant="solid" color="primary" size="lg" onClick={onRetry} dataTestId="payment-retry">
           {copy.retryAction}
@@ -218,18 +264,8 @@ function StatusActions({
   );
 }
 
-export function PaymentStatus({
-  copy,
-  status,
-  totalLabel,
-  orderId,
-  buyerEmail,
-  onRetry,
-  onRegenerate,
-  onBackToMenu,
-  paidExtra,
-  awaitingTimedOut = false,
-}: {
+/** What the last screen of checkout is handed. */
+interface PaymentStatusProps {
   /** Every sentence and label this screen renders — the HOST's words. */
   copy: PaymentStatusCopy;
   status: OrderStatus | null;
@@ -249,14 +285,69 @@ export function PaymentStatus({
    */
   paidExtra?: ReactNode;
   /**
-   * The wait has been given up on — see {@link AWAITING_TIMED_OUT}. Only
-   * meaningful while AWAITING_PAYMENT; every other status has already resolved,
-   * so a stale flag cannot change what a settled screen says.
+   * The wait has been given up on. Only meaningful while AWAITING_PAYMENT;
+   * every other status has already resolved, so a stale flag cannot change what
+   * a settled screen says.
    */
   awaitingTimedOut?: boolean;
-}): JSX.Element {
+  /**
+   * The wait's last poll failed (FUT-1144). Same scope rule as
+   * {@link awaitingTimedOut}, and it YIELDS to it: a wait that failed its way to
+   * the wall clock has both, and the honest thing to say then is that we have
+   * stopped asking.
+   */
+  awaitingError?: string | null;
+  /**
+   * Ask now. Rendered ONLY while the automatic wait is not visibly working —
+   * unreachable, or elapsed — so the buyer always has something to press when
+   * the spinner cannot honestly stand for progress, and nothing extra to think
+   * about when it can.
+   */
+  onCheckAgain?: () => void;
+}
+
+/**
+ * The wait has stopped LOOKING like progress: it cannot reach us, or it has run
+ * its clock out. Either way the spinner would be a lie and the buyer is owed
+ * something to press. Scoped to AWAITING because every other status has already
+ * resolved, so a stale flag cannot change what a settled screen says.
+ */
+function isStalled(status: OrderStatus, wait: WaitState): boolean {
+  if (status !== "AWAITING_PAYMENT") return false;
+  return wait.timedOut || wait.unreachable;
+}
+
+/**
+ * The check-again action, but only where it can honestly be offered — a button
+ * under a healthy spinner invites a tap that changes nothing.
+ */
+function offeredCheckAgain(
+  stalled: boolean,
+  onCheckAgain: (() => void) | undefined,
+): (() => void) | undefined {
+  return stalled ? onCheckAgain : undefined;
+}
+
+export function PaymentStatus({
+  copy,
+  status,
+  totalLabel,
+  orderId,
+  buyerEmail,
+  onRetry,
+  onRegenerate,
+  onBackToMenu,
+  paidExtra,
+  awaitingTimedOut = false,
+  awaitingError = null,
+  onCheckAgain,
+}: PaymentStatusProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
   const effective: OrderStatus = status ?? "AWAITING_PAYMENT";
+  const wait: WaitState = { timedOut: awaitingTimedOut, unreachable: awaitingError !== null };
+  const stalled = isStalled(effective, wait);
+  const paid = effective === "PAID";
+  const spinning = effective === "AWAITING_PAYMENT" && !stalled;
 
   return (
     <Box
@@ -265,15 +356,15 @@ export function PaymentStatus({
       data-timed-out={awaitingTimedOut ? "true" : undefined}
       sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
     >
-      <OutcomeHero copy={copy} status={effective} timedOut={awaitingTimedOut} />
+      <OutcomeHero copy={copy} status={effective} wait={wait} />
 
-      {effective === "PAID" ? (
+      {paid ? (
         <PaidFacts copy={copy} totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />
       ) : null}
 
-      {effective === "PAID" ? paidExtra : null}
+      {paid ? paidExtra : null}
 
-      {effective === "AWAITING_PAYMENT" && !awaitingTimedOut ? (
+      {spinning ? (
         <LoadingState variant="spinner" size="md" message="" dataTestId="payment-pending" />
       ) : null}
 
@@ -282,6 +373,7 @@ export function PaymentStatus({
         status={effective}
         onRetry={onRetry}
         onRegenerate={onRegenerate}
+        onCheckAgain={offeredCheckAgain(stalled, onCheckAgain)}
         onBackToMenu={onBackToMenu}
       />
     </Box>