@12-apps/payments-frontend 3.21.4 → 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/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'}`,
 };

package/src/components/checkout/transport.ts

@@ -96,10 +96,20 @@ export interface CheckoutTransport {
 export type CheckoutTransportBinding = Omit<CheckoutTransport, "copy"> &
   Partial<Pick<CheckoutTransport, "copy">>;
 
-/** The eight calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
+/** The nine calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
 export interface CheckoutClient {
   getConfig(tenantSlug: string): Promise<Result<CheckoutProviderConfig>>;
   getStatus(ref: string): Promise<Result<OrderStatus>>;
+  /**
+   * `POST /release` (FUT-1146): the buyer says they did not pay, and the
+   * charge they were sent away for has no terminal state of its own.
+   *
+   * Answers the payable's status AFTER the server has re-asked the provider,
+   * so a payment that actually succeeded comes back `PAID` and nothing is
+   * released — the race against a late webhook resolves in the shopper's
+   * favour rather than against it.
+   */
+  releaseCheckout(input: { orderId: string }): Promise<Result<OrderStatus>>;
   charge(input: ChargeCardInput): Promise<Result<ChargeOutcome>>;
   /** A wallet instrument against the same `/charge` route (FUT-471/472). */
   chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>>;
@@ -266,6 +276,16 @@ export function createCheckoutClient(transport: CheckoutTransport): CheckoutClie
         { method: "GET" },
       ),
 
+    releaseCheckout: (input) =>
+      // The settlement hints ride in the QUERY, exactly as the poll's do: they
+      // are the only way a hosted provider can be asked anything at all, so a
+      // release must carry them or the server decides "not paid" from a
+      // question it was never able to put.
+      call<OrderStatus>(`/release?${new URLSearchParams(returnedSettlement()).toString()}`, {
+        method: "POST",
+        body: JSON.stringify({ orderId: input.orderId }),
+      }),
+
     charge: (input) =>
       call<ChargeOutcome>("/charge", { method: "POST", body: flatChargeBody(input) }),
 

package/src/components/checkout/types.ts

@@ -9,6 +9,8 @@
  * the ports declared on `CheckoutFlowProps`.
  */
 
+import type { CheckoutDecline, CheckoutDeclineReason } from "./decline";
+
 /** Payment methods offered at checkout. Mirrors `Payment.method` (FUT-42). */
 export type PaymentMethod = "PIX" | "CARD";
 
@@ -34,6 +36,16 @@ export type OrderStatus = "AWAITING_PAYMENT" | "PAID" | "FAILED" | "EXPIRED";
 /** Terminal states — polling stops once the order reaches one of these. */
 export const TERMINAL_STATUSES: readonly OrderStatus[] = ["PAID", "FAILED", "EXPIRED"];
 
+/**
+ * What a payment pane calls once the charge has an answer.
+ *
+ * The refusal rides along OPTIONALLY (FUT-1145): a pane that has one hands it
+ * over so the confirmation screen can say which refusal this was and whether
+ * another instrument could work, and every caller that has nothing to add keeps
+ * calling this with one argument exactly as before.
+ */
+export type OnCheckoutResolved = (status: OrderStatus, decline?: CheckoutDecline | null) => void;
+
 /** Buyer contact captured at checkout. */
 export interface BuyerInfo {
   name?: string;
@@ -358,8 +370,20 @@ export interface CheckoutProviderConfig {
  * present when the provider demands the buyer finish the charge on ITS page —
  * Stripe's redirect-based 3-D Secure — and the client then hands the buyer
  * over exactly as it does for a redirect provider's link (FUT-556).
+ *
+ * `declineReason` / `retriable` ride along on a refusal (FUT-1145). The server
+ * has classified every acquirer decline since FUT-340 — 33 PagBank codes with
+ * issuer sub-reasons, each carrying the vendor's own retry verdict — and then
+ * answered `{ status }` and threw the classification away, so an expired card,
+ * a stolen card and "attempts exhausted, do not retry" all reached the buyer as
+ * "Pagamento não concluído. Você pode tentar novamente."
+ *
+ * BOTH OPTIONAL, and the degrade direction is today's behaviour: a server that
+ * sends neither renders exactly the generic refusal it always did.
  */
 export interface ChargeOutcome {
   status: OrderStatus;
   hostedCheckoutUrl?: string;
+  declineReason?: CheckoutDeclineReason;
+  retriable?: boolean;
 }