@12-apps/payments-frontend 3.20.0 → 3.21.0

package/src/components/checkout/use-wallet-charge.ts

@@ -36,9 +36,16 @@ export interface WalletCharge {
   errorCode: string | null;
   /** The charge is unresolved: no pay control may render (FUT-563). */
   unresolved: 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 pane 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). */
+  /** 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;
   /**
    * Charge the wallet's key. The button calls this once the sheet resolves.
    * Resolves `true` when the charge was ACCEPTED — paid, confirming, or
@@ -49,10 +56,11 @@ export interface WalletCharge {
 }
 
 /**
- * Healthy-poll cap for the wallet AWAITING wait — the card path's own cap
- * (FUT-191): 36 polls ≈ 90 s at the 2500 ms default interval.
+ * The wallet AWAITING wait — the card path's own bound (FUT-191): 90 s, in WALL
+ * TIME rather than healthy polls (FUT-1144, and see `CARD_AWAITING_WAIT_MS` for
+ * why a count of the polls that SUCCEEDED cannot bound a wait that is failing).
  */
-const WALLET_AWAITING_POLL_CAP = 36;
+const WALLET_AWAITING_WAIT_MS = 90_000;
 
 /** The wallet charge state machine. See the module comment. */
 export function useWalletCharge(
@@ -67,10 +75,15 @@ export function useWalletCharge(
   const client = useCheckoutClientApi();
   const navigate = useCheckoutNavigate();
 
-  const { status, error: pollError, timedOut: pollTimedOut } = usePaymentPolling(order.orderId, {
+  const {
+    status,
+    error: pollError,
+    timedOut: pollTimedOut,
+    checkAgain: pollCheckAgain,
+  } = usePaymentPolling(order.orderId, {
     enabled: phase === "polling",
     intervalMs: pollIntervalMs,
-    maxHealthyPolls: WALLET_AWAITING_POLL_CAP,
+    maxWaitMs: WALLET_AWAITING_WAIT_MS,
   });
 
   useEffect(() => {
@@ -124,6 +137,7 @@ export function useWalletCharge(
     unresolved: errorCode === UNRESOLVED_CODE,
     pollError,
     pollTimedOut,
+    pollCheckAgain,
     payWithKey,
   };
 }

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

@@ -74,8 +74,23 @@ export interface PaymentStatusCopy {
   failed: StatusOutcomeCopy;
   expired: StatusOutcomeCopy;
   awaitingTimedOut: StatusOutcomeCopy;
+  /**
+   * The wait cannot reach the payment right now (FUT-1144) — and is STILL
+   * ASKING, which is the whole difference between this outcome and the one
+   * above it, and why the one above it wins when a screen somehow has both. The
+   * resumed hosted return used to render neither: its poll could fail forever
+   * and the screen went on saying "isso costuma levar alguns segundos" under a
+   * spinner, so the one leg with no PIX or card view of its own was also the
+   * one that never mentioned a problem.
+   */
+  awaitingUnreachable: StatusOutcomeCopy;
   retryAction: string;
   regenerateAction: string;
+  /**
+   * Ask now, rather than waiting for the next automatic poll — and, once the
+   * wait has run out, the only thing that starts it again.
+   */
+  checkAgainAction: string;
   backAction: string;
   /** The paid receipt's three row labels. */
   amountLabel: string;

package/src/components/checkout/wallet-pane.tsx

@@ -12,6 +12,7 @@ import {
   googlePayConfig,
 } from "./method-capability";
 import type { ProviderCheckoutScreenProps } from "./providers/types";
+import { StalledWait } from "./stalled-wait";
 import { useCheckoutComponents } from "./ui";
 import { useWalletCharge, type WalletCharge } from "./use-wallet-charge";
 
@@ -35,29 +36,29 @@ type WalletPaneProps = ProviderCheckoutScreenProps & {
   order: NonNullable<ProviderCheckoutScreenProps["order"]>;
 };
 
-/** Post-submit confirmation, error > timeout > spinner — the card view's order. */
+/** Post-submit confirmation, timeout > error > spinner — the card view's order. */
 function WalletProcessing({ wallet }: { wallet: WalletCharge }): JSX.Element {
-  const { Alert, LoadingState } = useCheckoutComponents();
+  const { LoadingState } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.settling;
-  if (wallet.pollError) {
+  if (wallet.pollTimedOut) {
     return (
-      <Alert
-        variant="danger"
-        title={copy.cannotConfirm}
-        description={wallet.pollError}
-        showIcon
-        data-testid="wallet-poll-error"
+      <StalledWait
+        title={copy.takingLonger}
+        description={copy.takingLongerHelp}
+        onCheckAgain={wallet.pollCheckAgain}
+        testId="wallet-poll-timeout"
+        actionTestId="wallet-check-again"
       />
     );
   }
-  if (wallet.pollTimedOut) {
+  if (wallet.pollError) {
     return (
-      <Alert
-        variant="warning"
-        title={copy.takingLonger}
-        description={copy.takingLongerHelp}
-        showIcon
-        data-testid="wallet-poll-timeout"
+      <StalledWait
+        title={copy.connectionLost}
+        description={wallet.pollError}
+        onCheckAgain={wallet.pollCheckAgain}
+        testId="wallet-poll-error"
+        actionTestId="wallet-check-again"
       />
     );
   }

package/src/flows/copy.ts

@@ -59,6 +59,25 @@ export interface CheckoutCopyFE {
    * part only a host can own.
    */
   returnTimedOut?: string;
+  /**
+   * The return leg while the poll cannot REACH us (FUT-1144) — a dropped
+   * connection, or a browser that aborted our requests while the buyer was on
+   * the provider's page. The wait is still running and re-arms the moment the
+   * tab or the signal comes back, so the sentence must say "still trying", not
+   * "failed".
+   *
+   * OPTIONAL, on the {@link returnTimedOut} precedent: without it the screen
+   * shows the transport's own sentence — which the host already owns, through
+   * `views.screens.transport` — under `returnPending` as a warning.
+   */
+  returnUnreachable?: string;
+  /**
+   * The label on the buyer's "ask now" (FUT-1144), offered whenever the wait is
+   * unreachable or has elapsed. OPTIONAL for the same reason, and its ABSENCE
+   * costs the button: a control with no host-written label could only carry
+   * this package's Portuguese.
+   */
+  returnCheckAgain?: string;
   /** The Dados step's primary action. */
   continueAction: string;
   /**

package/src/flows/screens-hosted.tsx

@@ -108,13 +108,60 @@ function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHando
  * Stated here rather than imported because the two waits are the same DECISION
  * arrived at twice, not one shared implementation: this screen takes its FAST
  * interval from the host's `polling` config when there is one, and a host that
- * tunes that must not have this package's cap silently mean a different
- * wall-clock window than the constant's comment claims.
+ * tunes that must not have this package's bound silently mean a different
+ * wall-clock window than the constant's comment claims — which is exactly what
+ * a bound counted in POLLS did, and why it is counted in milliseconds now
+ * (FUT-1144).
  */
 const RETURN_FAST_MS = 2_500;
 const RETURN_SLOW_MS = 10_000;
 const RETURN_FAST_POLLS = (2 * 60_000) / RETURN_FAST_MS;
-const RETURN_POLL_CAP = RETURN_FAST_POLLS + (13 * 60_000) / RETURN_SLOW_MS;
+const RETURN_WINDOW_MS = 15 * 60_000;
+
+/**
+ * The two ways this wait stops looking like progress, said as a warning with
+ * the buyer's own "ask now" under it (FUT-1144).
+ *
+ * The button is drawn only when the host wrote a label for it. That is the
+ * `returnTimedOut` precedent one step further: a bound with no copy still
+ * stops the spinner, and an action with no copy could only be labelled in this
+ * package's Portuguese, so it is the one half that stands down.
+ */
+function ReturnStalled({
+  runtime,
+  description,
+  onCheckAgain,
+  testId,
+}: {
+  runtime: FlowsRuntime;
+  description: string | undefined;
+  onCheckAgain: () => void;
+  testId: string;
+}): JSX.Element {
+  const { Alert, Button } = useCheckoutComponents();
+  return (
+    <Box data-testid="checkout-hosted-return" sx={{ py: 4, display: "flex", flexDirection: "column", gap: 2 }}>
+      <Alert
+        variant="warning"
+        title={runtime.copy.returnPending}
+        {...(description === undefined ? {} : { description })}
+        showIcon
+        data-testid={testId}
+      />
+      {runtime.copy.returnCheckAgain === undefined ? null : (
+        <Button
+          variant="outline"
+          color="neutral"
+          size="md"
+          onClick={onCheckAgain}
+          dataTestId="checkout-hosted-return-check-again"
+        >
+          {runtime.copy.returnCheckAgain}
+        </Button>
+      )}
+    </Box>
+  );
+}
 
 function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn"] {
   function HostedReturnBody({
@@ -126,15 +173,15 @@ function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn
     // Read-and-clear, once, on first render: the resumed view belongs to
     // exactly one return trip.
     const [parked] = useState(takeHostedOrder);
-    // Bounded, for the reason on RETURN_POLL_CAP: nothing here can ever reach a
+    // Bounded, for the reason on RETURN_WINDOW_MS: nothing here can ever reach a
     // terminal state on its own, so an unbounded poll is a spinner the buyer
     // watches until they close the tab.
-    const { status, timedOut } = usePaymentPolling(parked?.orderId ?? null, {
+    const { status, timedOut, error, checkAgain } = usePaymentPolling(parked?.orderId ?? null, {
       enabled: Boolean(parked),
       intervalMs: runtime.config.polling?.intervalMs ?? RETURN_FAST_MS,
       slowAfterPolls: RETURN_FAST_POLLS,
       slowIntervalMs: RETURN_SLOW_MS,
-      maxHealthyPolls: RETURN_POLL_CAP,
+      maxWaitMs: RETURN_WINDOW_MS,
     });
 
     useEffect(() => {
@@ -152,19 +199,27 @@ function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn
         />
       );
     }
+    // STOPPED beats STILL TRYING. A wait that failed its way to the wall clock
+    // carries both, and the elapsed state is the one that stops asking — and the
+    // one whose sentence says not to pay again.
     if (timedOut) {
       return (
-        <Box data-testid="checkout-hosted-return" sx={{ py: 4 }}>
-          <Alert
-            variant="warning"
-            title={runtime.copy.returnPending}
-            {...(runtime.copy.returnTimedOut === undefined
-              ? {}
-              : { description: runtime.copy.returnTimedOut })}
-            showIcon
-            data-testid="checkout-hosted-return-timeout"
-          />
-        </Box>
+        <ReturnStalled
+          runtime={runtime}
+          description={runtime.copy.returnTimedOut}
+          onCheckAgain={checkAgain}
+          testId="checkout-hosted-return-timeout"
+        />
+      );
+    }
+    if (error !== null) {
+      return (
+        <ReturnStalled
+          runtime={runtime}
+          description={runtime.copy.returnUnreachable ?? error}
+          onCheckAgain={checkAgain}
+          testId="checkout-hosted-return-unreachable"
+        />
       );
     }
     return (