@12-apps/payments-frontend 3.21.3 → 3.22.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/poll-loop.ts

@@ -1,4 +1,5 @@
 import type { Result } from "../../result";
+import { claimRearm } from "./poll-rearm";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
 /**
@@ -70,16 +71,6 @@ export interface PollingOptions {
  */
 const MAX_ERROR_BACKOFF_MS = 10_000;
 
-/**
- * How long a re-arm must stay quiet after the last ask.
- *
- * Returning to a tab commonly fires `visibilitychange` and `online` together —
- * and a shopper flicking between the bank app and the store fires them again
- * per trip. This collapses a burst into one request without delaying it: the
- * first re-arm of a burst polls immediately, the rest fall inside the gap.
- */
-const REARM_QUIET_MS = 1_000;
-
 /**
  * How long ONE status ask may take before the loop stops waiting on it.
  *
@@ -170,6 +161,8 @@ function newRun() {
     healthy: 0,
     startedAt: 0,
     askedAt: 0,
+    /** Live asks abandoned by a re-arm since the last answer. See `claimRearm`. */
+    supersededAsks: 0,
     timer: undefined as ReturnType<typeof setTimeout> | undefined,
     /**
      * The wall clock, as a timer rather than a check after an ask. `outOfTime`
@@ -215,6 +208,9 @@ function askTimeout(
  * it has to be consulted against the delay it is about to sleep for.
  */
 function absorb(run: PollRun, result: Result<OrderStatus>, sink: PollSink): boolean {
+  // An answer got through, so the re-arm budget is no longer being spent into
+  // a void: refill it whether the answer was an error or a status.
+  run.supersededAsks = 0;
   if (!result.ok) {
     run.errors += 1;
     sink.setError(result.error);
@@ -374,6 +370,7 @@ export function createPollLoop(
       run.stopped = false;
       run.errors = 0;
       run.healthy = 0;
+      run.supersededAsks = 0;
       run.startedAt = Date.now();
       armDeadline(run, options, sink);
       sink.setTimedOut(false);
@@ -382,10 +379,11 @@ export function createPollLoop(
     },
     poke: (): void => {
       if (run.cancelled || run.stopped) return;
-      if (Date.now() - run.askedAt < REARM_QUIET_MS) return;
       // Deliberately NOT gated on `inFlight`: the shopper who just came back
       // from their bank app is exactly the case where the previous ask is a
-      // socket that died while the screen was hidden. Abandon it and ask now.
+      // socket that died while the screen was hidden. Abandon it and ask now —
+      // but `claimRearm` bounds how many live asks that may abandon in a row.
+      if (!claimRearm(run)) return;
       run.attempt += 1;
       run.inFlight = false;
       clearPending(run);

package/src/components/checkout/poll-rearm.ts

@@ -0,0 +1,86 @@
+/**
+ * When a re-arm may abandon an ask that is still in flight (FUT-1259).
+ *
+ * `visibilitychange` and `online` drive the loop's `poke`, and both fire for
+ * the same reason the wait exists: the shopper went to their bank app and came
+ * back, and the request left behind is quite likely a socket that died while
+ * the screen was hidden. Abandoning it is right. Abandoning it EVERY time is
+ * what this module bounds.
+ */
+
+/**
+ * The state a re-arm decision reads. Structural on purpose: the poll loop's own
+ * run object satisfies it, and typing it that way keeps this module free of an
+ * import back into the loop that imports it. Module-private — the loop passes
+ * its run and never names this type, so exporting it is an unused export.
+ */
+interface RearmState {
+  inFlight: boolean;
+  askedAt: number;
+  supersededAsks: number;
+}
+
+/**
+ * How long a re-arm must stay quiet after the last ask.
+ *
+ * Returning to a tab commonly fires `visibilitychange` and `online` together —
+ * and a shopper flicking between the bank app and the store fires them again
+ * per trip. This collapses a burst into one request without delaying it: the
+ * first re-arm of a burst polls immediately, the rest fall inside the gap.
+ */
+const REARM_QUIET_MS = 1_000;
+
+/**
+ * How many live asks a re-arm may abandon before it has to let one finish.
+ *
+ * The quiet window alone looked sufficient and is not, because it is measured
+ * against the CURRENT ask rather than against the previous re-arm. Once a round
+ * trip runs longer than the window — which is the ordinary state of the flaky
+ * link this whole feature exists for — every re-arm supersedes an ask that was
+ * still alive. Nothing is ever absorbed, so `errors` never rises, so the 2.5s →
+ * 5s → 10s backoff never engages, and the wait sits near one request per window
+ * instead of decaying to one per ten.
+ *
+ * So the budget: after this many abandoned asks with no answer in between, a
+ * re-arm stands down and lets the in-flight ask either return or hit its own
+ * `askTimeoutMs`. Either outcome reaches `absorb`, which refills the budget, so
+ * this only bites while genuinely nothing is getting through.
+ *
+ * **What it does NOT bound: the re-arm rate itself.** A re-arm that finds the
+ * loop idle spends nothing, so on a link whose asks RESOLVE inside the window —
+ * a fast 500, or the immediate `TypeError: Load failed` iOS raises for a killed
+ * socket — six `online` events still cost six requests, exactly as before. That
+ * flavour is bounded by {@link REARM_QUIET_MS} alone and always was. This
+ * constant is about the ask that hangs, which is the one the quiet window
+ * could not see.
+ */
+const MAX_SUPERSEDED_ASKS = 3;
+
+/**
+ * Decide whether a re-arm may proceed, and account for it if it may.
+ *
+ * Named `claim` rather than `may…` because it MUTATES on success: a re-arm that
+ * abandons a live ask spends one of the budget above. A re-arm that finds no
+ * ask in flight — the loop is simply between ticks — spends nothing, since
+ * there is no request to amplify.
+ *
+ * That second rule is what makes a denial safe, and it is an invariant worth
+ * stating: `supersededAsks > 0` implies `inFlight`, because every transition to
+ * `inFlight === false` in a live run either passes through `absorb` (which
+ * refills) or is followed synchronously by a `tick`. So a re-arm arriving at an
+ * IDLE loop is never denied, whatever the budget reads.
+ *
+ * The cost of a denial, stated honestly: the fourth consecutive return from the
+ * bank app does NOT poll immediately. It waits for the in-flight ask to resolve
+ * or reach `askTimeoutMs` (15s by default), plus one backoff step — so worst
+ * case the buyer learns they paid roughly 17s later than they would have. That
+ * is the price of not hammering `/status` on a link that is answering nothing,
+ * and the buyer's own "Verificar de novo" (`restart`) resets the budget outright.
+ */
+export function claimRearm(run: RearmState): boolean {
+  if (Date.now() - run.askedAt < REARM_QUIET_MS) return false;
+  if (!run.inFlight) return true;
+  if (run.supersededAsks >= MAX_SUPERSEDED_ASKS) return false;
+  run.supersededAsks += 1;
+  return true;
+}

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",

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

@@ -217,4 +217,18 @@ export interface CheckoutScreensCopy {
   validation: CheckoutValidationCopy;
   /** The step wrapper's own wait, while the charge is being raised. */
   generatingPayment: string;
+  /**
+   * The pay bar's money caption — "Total · 2 itens".
+   *
+   * A FUNCTION because it inflects on the count, which is a property of the
+   * language rather than of the checkout: one item and two items are not the
+   * same word, and they are not the same word in different ways per language.
+   *
+   * It was a hard-coded Portuguese template inside the component until
+   * FUT-1179, which is the ticket about a checkout that never showed the
+   * amount — so the fix put that caption on a SECOND step and made a
+   * single-locale string render twice. Everything else on both bars had been a
+   * host's word since FUT-760; this one had simply been missed.
+   */
+  totalCaption(items: number): string;
 }

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

@@ -114,4 +114,5 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     required: 'This field is required.',
   },
   generatingPayment: 'Generating payment…',
+  totalCaption: (items) => `Total · ${items} ${items === 1 ? 'item' : 'items'}`,
 };

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

@@ -100,4 +100,7 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     required: 'Campo obrigatório.',
   },
   generatingPayment: 'Gerando pagamento…',
+  // Verbatim what the component rendered before the key existed, so nothing
+  // changes for a Brazilian shopper.
+  totalCaption: (items) => `Total · ${items} ${items === 1 ? 'item' : 'itens'}`,
 };