@12-apps/payments-frontend 3.20.0 → 3.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.20.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

@@ -174,6 +174,11 @@ 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}
     />
   );
 }

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

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