@12-apps/payments-frontend 3.19.0 → 3.20.1

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

@@ -4,6 +4,7 @@ import QRCode from "react-qr-code";
 
 import { useCheckoutCopy } from "./copy-context";
 import { ContentCopyIcon } from "./icons";
+import { StalledWait } from "./stalled-wait";
 import type { CheckoutOrder, OrderStatus, PixCharge } from "./types";
 import { useCheckoutComponents } from "./ui";
 import { usePaymentPolling } from "./use-payment-polling";
@@ -71,19 +72,38 @@ function PixCodeBox({ pix }: { pix: PixCharge }): JSX.Element {
   );
 }
 
-/** The live footer: poll error, or the pulsing "awaiting payment" indicator. */
-function PixPollFooter({ error }: { error: string | null }): JSX.Element {
-  const { Alert, Text } = useCheckoutComponents();
+/**
+ * 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.
+ *
+ * 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.
+ */
+function PixPollFooter({
+  error,
+  onCheckAgain,
+}: {
+  error: string | null;
+  onCheckAgain: () => void;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
   const { pix, settling } = useCheckoutCopy().screens;
   if (error) {
+    // 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 (
-      <Alert
-        variant="danger"
-        title={settling.cannotConfirm}
-        description={error}
-        showIcon
-        data-testid="pix-poll-error"
-      />
+      <Box sx={{ width: "100%", maxWidth: 420 }}>
+        <StalledWait
+          title={settling.connectionLost}
+          description={error}
+          onCheckAgain={onCheckAgain}
+          testId="pix-poll-error"
+          actionTestId="pix-check-again"
+        />
+      </Box>
     );
   }
   return (
@@ -107,7 +127,9 @@ export function PixView({
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
-  const { status, error } = usePaymentPolling(order.orderId, { intervalMs: pollIntervalMs });
+  const { status, error, checkAgain } = usePaymentPolling(order.orderId, {
+    intervalMs: pollIntervalMs,
+  });
 
   // Bubble a terminal status up once, so the parent can advance to the status step.
   useEffect(() => {
@@ -160,7 +182,7 @@ export function PixView({
         {copy.validUntil(validUntil)}
       </Text>
 
-      <PixPollFooter error={error} />
+      <PixPollFooter error={error} onCheckAgain={checkAgain} />
     </Box>
   );
 }

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

@@ -34,8 +34,15 @@ export const PT_BR_PAYMENT_STATUS_COPY: PaymentStatusCopy = {
       "Se você já pagou, o pedido é confirmado assim que a operadora avisar — " +
       "não pague de novo. Você pode fechar esta tela.",
   },
+  awaitingUnreachable: {
+    heading: "Não conseguimos falar com o pagamento agora",
+    support:
+      "Continuamos tentando por aqui. Se você já pagou, não pague de novo — " +
+      "o pedido é confirmado assim que a operadora avisar.",
+  },
   retryAction: "Tentar novamente",
   regenerateAction: "Gerar novo código",
+  checkAgainAction: "Verificar de novo",
   backAction: "Voltar ao cardápio",
   amountLabel: "Valor pago",
   referenceLabel: "Pedido",

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

@@ -61,6 +61,25 @@ export interface SettlingCopy {
   confirming: string;
   /** It came back refused. */
   cannotPay: string;
+  /**
+   * We cannot reach the payment right now — a dropped connection, a handset
+   * moving between Wi-Fi and 4G, a browser that aborted our requests while the
+   * shopper was in their bank app (FUT-1144).
+   *
+   * TRANSIENT, and the sentence must say so: the screen is still asking, on a
+   * backoff, and it re-asks the moment the tab comes back or the signal
+   * returns. This was `cannotConfirm` — "não foi possível confirmar o
+   * pagamento" — under which the wait had actually STOPPED, so a shopper who
+   * had paid read a final-sounding refusal and was never told otherwise.
+   */
+  connectionLost: string;
+  /**
+   * Ask again, now. Offered beside {@link connectionLost} and beside the
+   * elapsed wait, because a shopper watching a screen that cannot reach us
+   * needs something to press — and because pressing it is what restarts a wait
+   * that has run out.
+   */
+  checkAgainAction: string;
 }
 
 /** The PIX pane: the QR, the copyable code, and the wait. */

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

@@ -35,6 +35,10 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     processing: 'Processing payment…',
     confirming: 'We are confirming your payment',
     cannotPay: 'Could not pay',
+    // "we keep trying" is the load-bearing half: the wait has not ended, and a
+    // shopper who reads a final-sounding refusal pays a second time.
+    connectionLost: 'No connection right now — we keep trying',
+    checkAgainAction: 'Check again',
   },
   pix: {
     heading: 'Pay with PIX',

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

@@ -26,6 +26,8 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     processing: 'Processando pagamento…',
     confirming: 'Estamos confirmando seu pagamento',
     cannotPay: 'Não foi possível pagar',
+    connectionLost: 'Sem conexão no momento — continuamos tentando',
+    checkAgainAction: 'Verificar de novo',
   },
   pix: {
     heading: 'Pague com PIX',

package/src/components/checkout/stalled-wait.tsx

@@ -0,0 +1,58 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { useCheckoutCopy } from "./copy-context";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * A wait that has stopped LOOKING like progress, said as a warning with the
+ * buyer's own "ask now" underneath (FUT-1144).
+ *
+ * Two situations reach it and they are deliberately the same shape: the poll
+ * cannot reach us, or the wall-clock wait has run out. In both, the confirmation
+ * spinner would be telling the buyer something is happening when nothing is —
+ * and by this point in the card and wallet panes every pay control is already
+ * gone, so without this button the screen has no control at all while it reports
+ * a problem. Pressing it restarts the wait, which is what makes it worth
+ * offering after a timeout and not only during a blip.
+ *
+ * A WARNING rather than a danger, in both. Neither says the payment failed:
+ * the charge is recoverable by webhook, reconciliation or backfill, and a red
+ * panel over a recoverable charge is what pushes a buyer into paying twice.
+ *
+ * One component for the card and the wallet because it is one decision. The
+ * panes' own confirmation states were near-identical before this and drifted
+ * apart in exactly the way that ends with a product telling a buyer two
+ * different things about one situation depending on which button they pressed.
+ */
+export function StalledWait({
+  title,
+  description,
+  onCheckAgain,
+  testId,
+  actionTestId,
+}: {
+  title: string;
+  description: string;
+  onCheckAgain: () => void;
+  /** The alert's id — each pane names its own situation for its own suites. */
+  testId: string;
+  actionTestId: string;
+}): JSX.Element {
+  const { Alert, Button } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.settling;
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      <Alert variant="warning" title={title} description={description} showIcon data-testid={testId} />
+      <Button
+        variant="outline"
+        color="neutral"
+        size="md"
+        onClick={onCheckAgain}
+        dataTestId={actionTestId}
+      >
+        {copy.checkAgainAction}
+      </Button>
+    </Box>
+  );
+}

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

@@ -26,6 +26,7 @@ import { useCheckoutClientApi } from "./client-context";
 import { rememberHostedOrder } from "./hosted-return";
 import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
+import { useOneClickArmed, useOneClickPay } from "./one-click";
 import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
 import { usePaymentPolling } from "./use-payment-polling";
 import type { CardCopy } from "../../card/copy";
@@ -99,7 +100,7 @@ function useCardPublicKey(
 }
 
 /** Everything the card view renders — all checkout state + the submit handler. */
-interface CardCheckout {
+export interface CardCheckout {
   savedCards: SavedCard[];
   selection: string;
   setSelection: (id: string) => void;
@@ -116,9 +117,16 @@ interface CardCheckout {
   errorCode: string | null;
   submitting: boolean;
   submitted: boolean;
+  /**
+   * The last status poll failed. TRANSIENT (FUT-1144): the wait carries on at a
+   * backed-off cadence and this clears on the next success, so the view shows
+   * it as "still trying" beside {@link pollCheckAgain} rather than as an end.
+   */
   pollError: string | null;
-  /** The healthy-poll cap elapsed while still AWAITING (FUT-191 bounded wait). */
+  /** The bounded AWAITING wait elapsed (FUT-191, now wall-clock — FUT-1144). */
   pollTimedOut: boolean;
+  /** Ask now and restart the wait — the buyer's "verificar de novo". */
+  pollCheckAgain: () => void;
   handlePay: () => Promise<void>;
 }
 
@@ -141,14 +149,20 @@ type CardSubmit = Pick<
   | "errorCode"
   | "pollError"
   | "pollTimedOut"
+  | "pollCheckAgain"
   | "handlePay"
 >;
 
 /**
- * Healthy-poll cap for the card AWAITING wait: 36 polls ≈ 90 s at the 2500 ms
- * default interval (FUT-191). PIX passes no cap and keeps today's behavior.
+ * The card AWAITING wait, bounded in WALL TIME: 90 s (FUT-191, FUT-1144).
+ *
+ * It was 36 healthy polls, which is the same 90 s at the default 2500 ms
+ * interval and an unbounded wait at any other — including the one that
+ * mattered, where every poll is FAILING and the healthy count never moves.
+ * PIX passes no bound at all and keeps today's behavior: its charge expires
+ * server-side and comes back as a terminal EXPIRED.
  */
-const CARD_AWAITING_POLL_CAP = 36;
+const CARD_AWAITING_WAIT_MS = 90_000;
 
 /**
  * Hand the buyer to the provider's authentication page (FUT-698) — Stripe's
@@ -209,6 +223,31 @@ async function resolveInstruments(input: {
   );
 }
 
+/**
+ * The card's status wait, named the way the view reads it.
+ *
+ * Its own function so `useCardSubmit` stays inside the size gate, and so the
+ * one decision here — this wait is bounded in WALL TIME — sits beside the
+ * constant that states it rather than inside a submit machine.
+ */
+function useCardWait(
+  orderId: string,
+  submitted: boolean,
+  intervalMs: number,
+): {
+  status: OrderStatus | null;
+  pollError: string | null;
+  pollTimedOut: boolean;
+  pollCheckAgain: () => void;
+} {
+  const { status, error, timedOut, checkAgain } = usePaymentPolling(orderId, {
+    enabled: submitted,
+    intervalMs,
+    maxWaitMs: CARD_AWAITING_WAIT_MS,
+  });
+  return { status, pollError: error, pollTimedOut: timedOut, pollCheckAgain: checkAgain };
+}
+
 /**
  * The submit state machine (FUT-58): validate → tokenize (self-heal) → charge →
  * poll for the async confirmation, bubbling the terminal status up via
@@ -234,11 +273,7 @@ function useCardSubmit(
   const navigate = useCheckoutNavigate();
   const cardCopy = useCheckoutCopy().card;
 
-  const { status, error: pollError, timedOut: pollTimedOut } = usePaymentPolling(order.orderId, {
-    enabled: submitted,
-    intervalMs: pollIntervalMs,
-    maxHealthyPolls: CARD_AWAITING_POLL_CAP,
-  });
+  const { status, ...wait } = useCardWait(order.orderId, submitted, pollIntervalMs);
 
   useEffect(() => {
     if (status && status !== "AWAITING_PAYMENT") onResolved(status);
@@ -292,7 +327,7 @@ function useCardSubmit(
     else setSubmitted(true);
   };
 
-  return { submitting, submitted, error, errorCode, pollError, pollTimedOut, handlePay };
+  return { submitting, submitted, error, errorCode, ...wait, handlePay };
 }
 
 /**
@@ -339,6 +374,13 @@ export function useCardCheckout(
     { card, usingNewCard, selection, saveCard, validate, setFieldErrors },
     providerChain,
   );
+  // The tap a one-click buyer already made (`./one-click.tsx`). Nothing about
+  // the charge differs — this only presses the button, and only while a SAVED
+  // card is the selection, which is a state the picker reaches exactly when the
+  // instrument list came back with something. A buyer with no saved card is
+  // left on the form, which is the ordinary step 2.
+  const ready = !usingNewCard && !submit.submitting && !submit.submitted && submit.error === null;
+  useOneClickPay({ armed: useOneClickArmed(), ready, pay: submit.handlePay });
 
   return {
     savedCards,

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

@@ -147,15 +147,19 @@ function handOverToProvider(
  * confirmation is at most 2.5 s late, and an abandoned checkout costs ~126
  * polls instead of the 360 a flat 2.5 s would have.
  *
- * The three constants are ONE decision — 48 × 2.5 s + 78 × 10 s ≈ 15 min — so
- * the cap is derived rather than typed, and cannot drift from the comment.
- *
  * Fifteen minutes because by then a webhook that was ever coming has come. Past
  * that the answer will not change while the buyer watches: the scheduled
  * reconciliation is what rescues a genuinely late one, and it does that whether
  * the tab is open or not.
  *
- * The card wait is bounded at 90 s (`CARD_AWAITING_POLL_CAP`) because a card
+ * The BOUND is that wall-clock window, not a poll count (FUT-1144). The two are
+ * the same number for a healthy wait — 48 × 2.5 s + 78 × 10 s = 15 min — and
+ * they part company for the wait that needed bounding: a poll that FAILS
+ * incremented nothing, so a connection that never came back left this screen
+ * asking, and spinning, with no end at all. A clock cannot be stopped by the
+ * failure it is measuring.
+ *
+ * The card wait is bounded at 90 s (`CARD_AWAITING_WAIT_MS`) because a card
  * authorises inline and a buyer is holding their phone. This leg is the other
  * shape: the buyer has already been off to another site and back, and may
  * legitimately still be finishing there.
@@ -165,8 +169,7 @@ const HOSTED_RESUME_SLOW_MS = 10_000;
 /** Two minutes at the fast rate, before the wait is worth economising on. */
 const HOSTED_RESUME_FAST_POLLS = (2 * 60_000) / HOSTED_RESUME_FAST_MS;
 /** Thirteen more at the slow one — 15 minutes all told. */
-const HOSTED_RESUME_POLL_CAP =
-  HOSTED_RESUME_FAST_POLLS + (13 * 60_000) / HOSTED_RESUME_SLOW_MS;
+const HOSTED_RESUME_WINDOW_MS = 15 * 60_000;
 
 /**
  * The leg of checkout that resumes after a hosted provider sent the buyer back
@@ -184,21 +187,56 @@ const HOSTED_RESUME_POLL_CAP =
  * had no way to reach a terminal state, because the ORDER has none: expiry is
  * PIX-only, and a redirect charge carries no QR window to lapse. `timedOut` is
  * what the screen says instead of spinning.
+ *
+ * `error` is the half that was dropped on the floor (FUT-1144), and dropping it
+ * is what made this leg the SILENT one. The poll below has always been able to
+ * fail; this hook returned `status` and `timedOut` and nothing else, so a leg
+ * whose every request was failing looked identical to one still waiting — the
+ * spinner, forever, with the reason a `console`-less browser away. It is
+ * surfaced now, together with the wait's own `checkAgain`, because a screen that
+ * says "we cannot reach the payment" and offers nothing to press is only half
+ * of an answer.
  */
 function useHostedResume(tenantSlug?: string): {
   order: CheckoutOrder | null;
   status: OrderStatus | null;
   timedOut: boolean;
+  error: string | null;
+  checkAgain: () => void;
 } {
   const [order] = useState(() => takeHostedOrder(tenantSlug));
-  const { status, timedOut } = usePaymentPolling(order?.orderId ?? null, {
+  const { status, timedOut, error, checkAgain } = usePaymentPolling(order?.orderId ?? null, {
     enabled: Boolean(order),
     intervalMs: HOSTED_RESUME_FAST_MS,
     slowAfterPolls: HOSTED_RESUME_FAST_POLLS,
     slowIntervalMs: HOSTED_RESUME_SLOW_MS,
-    maxHealthyPolls: HOSTED_RESUME_POLL_CAP,
+    maxWaitMs: HOSTED_RESUME_WINDOW_MS,
   });
-  return { order, status, timedOut };
+  return { order, status, timedOut, error, checkAgain };
+}
+
+/**
+ * What the resumed leg contributes to the controller's surface.
+ *
+ * `resumeTimedOut` is only ever true on that leg — `useHostedResume` is the
+ * sole caller that bounds its wait, and a buyer who never left has a card or
+ * PIX view reporting its own. `resumeError` and `resumeCheckAgain` are the
+ * transient failure and the buyer's way out of it (FUT-1144).
+ *
+ * All three are inert for a checkout that never left this tab: with nothing
+ * parked the poll is disabled, so the error stays null, the bound never
+ * elapses, and the action has no wait to restart.
+ */
+function resumeSurface(resume: ReturnType<typeof useHostedResume>): {
+  resumeTimedOut: boolean;
+  resumeError: string | null;
+  resumeCheckAgain: () => void;
+} {
+  return {
+    resumeTimedOut: resume.timedOut,
+    resumeError: resume.error,
+    resumeCheckAgain: resume.checkAgain,
+  };
 }
 
 /**
@@ -338,10 +376,7 @@ export function useCheckoutController(
   return {
     step, setStep, method, setMethod, buyer, setBuyer, saveProfile, setSaveProfile,
     order, finalStatus: finalStatus ?? resume.status, creating,
-    // Only ever true on the resumed leg: `useHostedResume` is the sole caller
-    // that caps its polls, and a buyer who never left has a card or PIX view
-    // reporting its own wait.
-    resumeTimedOut: resume.timedOut,
+    ...resumeSurface(resume),
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
     goToPayment, startPayment, payWithEmail, handleResolved, retry, completed,