@12-apps/payments-frontend 3.21.4 → 3.23.0

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

@@ -1,10 +1,11 @@
 import { Box } from "@mui/material";
 import type { JSX, ReactNode } from "react";
 
-import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
+import type { CheckoutDecline } from "./decline";
+import { OutcomeHero, PaidFacts, StatusActions, type WaitState } from "./payment-status-parts";
 import type { OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
-import type { PaymentStatusCopy, StatusOutcomeCopy } from "./view-copy";
+import type { PaymentStatusCopy } from "./view-copy";
 
 /**
  * The last screen of checkout.
@@ -29,241 +30,6 @@ import type { PaymentStatusCopy, StatusOutcomeCopy } from "./view-copy";
  * screen says and how it is arranged has changed.
  */
 
-/**
- * The per-outcome VISUAL grammar — icon and semantic tone. The heading and
- * supporting line beside them come from {@link PaymentStatusCopy}: an icon is
- * the component's own vocabulary, a sentence never is. (The FAILED support
- * line's job — say "nothing was charged" plainly and first — and the
- * timed-out wait's "do not pay again" now live with the host's words, where
- * FUT-556's reasoning is documented on the copy port.)
- */
-interface OutcomeVisual {
-  icon: JSX.Element;
-  /** Semantic theme token — never a raw colour. */
-  tone: "success" | "danger" | "warning" | "neutral";
-}
-
-const OUTCOME_VISUAL: Record<OrderStatus, OutcomeVisual> = {
-  PAID: { icon: <CheckCircleOutlineIcon fontSize="large" />, tone: "success" },
-  AWAITING_PAYMENT: { icon: <ScheduleIcon fontSize="large" />, tone: "neutral" },
-  FAILED: { icon: <ErrorOutlineIcon fontSize="large" />, tone: "danger" },
-  EXPIRED: { icon: <ScheduleIcon fontSize="large" />, tone: "warning" },
-};
-
-const OUTCOME_COPY_KEY: Record<OrderStatus, keyof Pick<
-  PaymentStatusCopy,
-  "paid" | "awaiting" | "failed" | "expired"
->> = {
-  PAID: "paid",
-  AWAITING_PAYMENT: "awaiting",
-  FAILED: "failed",
-  EXPIRED: "expired",
-};
-
-const TONE_COLOR: Record<OutcomeVisual["tone"], string> = {
-  success: "success.main",
-  danger: "error.main",
-  warning: "warning.main",
-  neutral: "text.secondary",
-};
-
-/**
- * The buyer's quotable reference.
- *
- * The order id is a uuid — unreadable over a phone call and impossible to copy
- * by eye — so the screen shows its first block, uppercased. It is the real id's
- * own prefix rather than a second number, so support can still find the order
- * from what the buyer reads out.
- */
-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,
-  wait,
-}: {
-  copy: PaymentStatusCopy;
-  status: OrderStatus;
-  wait: WaitState;
-}): JSX.Element {
-  const { Text } = useCheckoutComponents();
-  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 = 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. Each unsettled wait gets its
-      // OWN id rather than reusing `payment-awaiting_payment`: a test that
-      // 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={
-        face ? face.testId : status === "PAID" ? "payment-paid" : `payment-${status.toLowerCase()}`
-      }
-      sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
-    >
-      <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
-      <Text variant="heading" size="md" weight="bold" as="h2">
-        {outcome.heading}
-      </Text>
-      <Text variant="body" size="sm" as="p" style={{ opacity: 0.75 }}>
-        {outcome.support}
-      </Text>
-    </Box>
-  );
-}
-
-/** One label/value row of the paid receipt block. */
-function Fact({ label, value, testId }: { label: string; value: string; testId?: string }): JSX.Element {
-  const { Text } = useCheckoutComponents();
-  return (
-    <Box sx={{ display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 2 }}>
-      <Text variant="body" size="sm" as="span" style={{ opacity: 0.75 }}>
-        {label}
-      </Text>
-      <Text variant="body" size="sm" weight="bold" as="span" data-testid={testId}>
-        {value}
-      </Text>
-    </Box>
-  );
-}
-
-/**
- * What a paid buyer will want later: how much left their account, which order
- * it was, and where the receipt went. Rendered only for PAID — on any other
- * outcome these facts are either untrue or not yet knowable.
- */
-function PaidFacts({
-  copy,
-  totalLabel,
-  orderId,
-  buyerEmail,
-}: {
-  copy: PaymentStatusCopy;
-  totalLabel: string;
-  orderId?: string;
-  buyerEmail?: string;
-}): JSX.Element {
-  return (
-    <Box
-      data-testid="payment-receipt"
-      sx={{
-        display: "flex",
-        flexDirection: "column",
-        gap: 1,
-        p: 2,
-        borderRadius: 2,
-        bgcolor: "action.hover",
-      }}
-    >
-      <Fact label={copy.amountLabel} value={totalLabel} testId="payment-amount" />
-      {orderId ? (
-        <Fact label={copy.referenceLabel} value={`#${orderReference(orderId)}`} testId="payment-reference" />
-      ) : null}
-      {buyerEmail ? <Fact label={copy.receiptEmailLabel} value={buyerEmail} /> : null}
-    </Box>
-  );
-}
-
-/** 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}
-        </Button>
-      ) : null}
-      {status === "EXPIRED" && onRegenerate ? (
-        <Button variant="solid" color="primary" size="lg" onClick={onRegenerate} dataTestId="payment-regenerate">
-          {copy.regenerateAction}
-        </Button>
-      ) : null}
-      <Button
-        // Full width and last, so the thumb lands on the same place in every
-        // outcome instead of hunting a button that moves with the state.
-        variant={status === "PAID" ? "solid" : "outline"}
-        color={status === "PAID" ? "primary" : "neutral"}
-        size="lg"
-        onClick={onBackToMenu}
-        dataTestId="payment-back-to-menu"
-      >
-        {copy.backAction}
-      </Button>
-    </Box>
-  );
-}
-
 /** What the last screen of checkout is handed. */
 interface PaymentStatusProps {
   /** Every sentence and label this screen renders — the HOST's words. */
@@ -304,6 +70,20 @@ interface PaymentStatusProps {
    * about when it can.
    */
   onCheckAgain?: () => void;
+  /**
+   * The buyer says they did not pay (FUT-1146). Present only while the wait is
+   * genuinely unsettled and the caller has something to release; rendered on
+   * AWAITING and nowhere else, because every other status has an answer already
+   * and this action is the one that manufactures one.
+   */
+  onNotPaid?: () => void;
+  /** A release is in flight — the action stands down rather than repeating. */
+  releasing?: boolean;
+  /**
+   * WHY the charge was refused (FUT-1145). Read only on FAILED: it chooses the
+   * sentence, and it decides whether a retry is offered at all.
+   */
+  decline?: CheckoutDecline | null;
 }
 
 /**
@@ -328,52 +108,77 @@ function offeredCheckAgain(
   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 };
+/** What the props ADD UP TO — every branch this screen makes, made once. */
+interface StatusView {
+  effective: OrderStatus;
+  wait: WaitState;
+  paid: boolean;
+  spinning: boolean;
+  decline: CheckoutDecline | null;
+  checkAgain: (() => void) | undefined;
+  notPaid: (() => void) | undefined;
+}
+
+/**
+ * Resolve the props into that view.
+ *
+ * A pure function rather than a block inside the component, because the
+ * decisions and the markup are two different things to read — and because the
+ * component was over the complexity gate with all of them inlined.
+ */
+function statusView(props: PaymentStatusProps): StatusView {
+  const effective: OrderStatus = props.status ?? "AWAITING_PAYMENT";
+  const wait: WaitState = {
+    timedOut: props.awaitingTimedOut === true,
+    unreachable: (props.awaitingError ?? null) !== null,
+  };
   const stalled = isStalled(effective, wait);
-  const paid = effective === "PAID";
-  const spinning = effective === "AWAITING_PAYMENT" && !stalled;
+  const awaiting = effective === "AWAITING_PAYMENT";
+  return {
+    effective,
+    wait,
+    paid: effective === "PAID",
+    spinning: awaiting && !stalled,
+    decline: props.decline ?? null,
+    checkAgain: offeredCheckAgain(stalled, props.onCheckAgain),
+    // Scoped to the unsettled wait, and stood down while its own request is
+    // out. A settled screen has its answer; a second tap would only ask again.
+    notPaid: awaiting && props.releasing !== true ? props.onNotPaid : undefined,
+  };
+}
+
+export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
+  const { copy, totalLabel, orderId, buyerEmail, onRetry, onRegenerate, onBackToMenu } = props;
+  const { LoadingState } = useCheckoutComponents();
+  const view = statusView(props);
 
   return (
     <Box
       data-testid="payment-status"
-      data-status={effective}
-      data-timed-out={awaitingTimedOut ? "true" : undefined}
+      data-status={view.effective}
+      data-timed-out={view.wait.timedOut ? "true" : undefined}
       sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
     >
-      <OutcomeHero copy={copy} status={effective} wait={wait} />
+      <OutcomeHero copy={copy} status={view.effective} wait={view.wait} decline={view.decline} />
 
-      {paid ? (
+      {view.paid ? (
         <PaidFacts copy={copy} totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />
       ) : null}
 
-      {paid ? paidExtra : null}
+      {view.paid ? props.paidExtra : null}
 
-      {spinning ? (
+      {view.spinning ? (
         <LoadingState variant="spinner" size="md" message="" dataTestId="payment-pending" />
       ) : null}
 
       <StatusActions
         copy={copy}
-        status={effective}
+        status={view.effective}
+        decline={view.decline}
         onRetry={onRetry}
         onRegenerate={onRegenerate}
-        onCheckAgain={offeredCheckAgain(stalled, onCheckAgain)}
+        onCheckAgain={view.checkAgain}
+        onNotPaid={view.notPaid}
         onBackToMenu={onBackToMenu}
       />
     </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/providers/types.ts

@@ -15,11 +15,12 @@
  */
 import type { JSX } from "react";
 
+import type { CheckoutBasketIdentity } from "../basket";
 import type {
   BuyerInfo,
   CheckoutOrder,
   CheckoutProviderConfig,
-  OrderStatus,
+  OnCheckoutResolved,
   PaymentMethod,
 } from "../types";
 
@@ -70,6 +71,19 @@ export interface ProviderCheckoutScreenProps {
   tenantSlug?: string;
   /** The shell's polling cadence, passed through so tests can shorten it. */
   pollIntervalMs?: number;
+  /**
+   * The buyer is retrying a REFUSED card (FUT-1145), so no saved instrument is
+   * preselected: the one this would otherwise choose is the one that failed,
+   * and a retry that re-charges it is a second identical decline.
+   */
+  freshInstrument?: boolean;
+  /**
+   * WHICH basket this checkout is for (FUT-1213). A card screen needs it
+   * because it can PARK an order of its own: a redirect-based 3-D Secure
+   * challenge is a hand-off like any other, and an entry parked without a
+   * basket (or without a store) resumes over any basket at any store.
+   */
+  basket?: CheckoutBasketIdentity;
   /**
    * The host's Apple Pay merchant-validation port (FUT-472): exchange the
    * session's `validationURL` for an Apple merchant session, SERVER-SIDE —
@@ -78,8 +92,11 @@ export interface ProviderCheckoutScreenProps {
    * card form stays the way to pay.
    */
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
-  /** A terminal status — the shell moves to Confirmação. */
-  onResolved: (status: OrderStatus) => void;
+  /**
+   * A terminal status — the shell moves to Confirmação, carrying the refusal
+   * when the charge produced one (FUT-1145).
+   */
+  onResolved: OnCheckoutResolved;
 }
 
 /**

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

@@ -40,9 +40,42 @@ export const PT_BR_PAYMENT_STATUS_COPY: PaymentStatusCopy = {
       "Continuamos tentando por aqui. Se você já pagou, não pague de novo — " +
       "o pedido é confirmado assim que a operadora avisar.",
   },
+  /**
+   * One refusal at a time, in the cardholder's own terms (FUT-1145).
+   *
+   * `UNKNOWN` is deliberately absent: with no recognised reason there is
+   * nothing specific to say, and `failed` above is already that sentence.
+   */
+  declined: {
+    INSUFFICIENT_FUNDS: {
+      heading: "Não havia saldo ou limite",
+      support: "Nenhum valor foi cobrado. Tente outro cartão.",
+    },
+    CARD_DECLINED: {
+      heading: "Seu banco não autorizou o pagamento",
+      support: "Nenhum valor foi cobrado. Tente outro cartão ou fale com o seu banco.",
+    },
+    INVALID_CARD: {
+      heading: "Os dados do cartão não foram aceitos",
+      support: "Nenhum valor foi cobrado. Confira o número, a validade e o CVV, ou use outro cartão.",
+    },
+    EXPIRED_CARD: {
+      heading: "O cartão está vencido",
+      support: "Nenhum valor foi cobrado. Use um cartão com a validade em dia.",
+    },
+    FRAUD_SUSPECTED: {
+      heading: "O banco bloqueou esta compra por segurança",
+      support: "Nenhum valor foi cobrado. Fale com o seu banco ou use outro cartão.",
+    },
+    PROVIDER_ERROR: {
+      heading: "Não foi possível processar o pagamento agora",
+      support: "Nenhum valor foi cobrado. Tente de novo em alguns instantes.",
+    },
+  },
   retryAction: "Tentar novamente",
   regenerateAction: "Gerar novo código",
   checkAgainAction: "Verificar de novo",
+  notPaidAction: "Não consegui pagar",
   backAction: "Voltar ao cardápio",
   amountLabel: "Valor pago",
   referenceLabel: "Pedido",
@@ -92,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…",
+    },
+  },
 };