@12-apps/payments-frontend 3.31.2 → 3.33.0

package/package.json

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

package/src/components/checkout/checkout-flow.tsx

@@ -233,6 +233,9 @@ function StatusStep({
       // FAILED only, where it picks the sentence and decides whether a retry
       // could work at all.
       decline={c.decline}
+      // A Pix the store confirms by hand ends without proof either way
+      // (FUT-3232), so its refusal and lapse get their own sentences.
+      manual={c.order?.pix?.confirmation === "MANUAL"}
     />
   );
 }

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

@@ -34,6 +34,16 @@ export const EN_US_PAYMENT_STATUS_COPY: PaymentStatusCopy = {
     heading: "The code expired",
     support: "Nothing was charged. Generate a new code to carry on.",
   },
+  manual: {
+    failed: {
+      heading: "The store did not find your Pix",
+      support: "If you have already paid, talk to the store before paying again.",
+    },
+    expired: {
+      heading: "The store did not confirm the payment in time",
+      support: "If you have already paid, talk to the store before paying again.",
+    },
+  },
   awaitingTimedOut: {
     heading: "We have not had the confirmation yet",
     support:

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

@@ -0,0 +1,81 @@
+import type { JSX } from "react";
+
+import type { CheckoutDecline } from "./decline";
+import type { OrderStatus } from "./types";
+import { useCheckoutComponents } from "./ui";
+import type { PaymentStatusCopy } from "./view-copy";
+
+/**
+ * The confirmation screen's "pay again" action — retry or regenerate — split
+ * out of `./payment-status-parts.tsx` when the Pix the store confirms
+ * (FUT-3232) gave it a second look and took that file past its size gate.
+ */
+
+/**
+ * Whether "Tentar novamente" may be offered for a refusal (FUT-1145).
+ *
+ * `retriable === false` is the provider's OWN verdict that another attempt with
+ * this instrument cannot succeed — attempts exhausted (10001), a cancelled
+ * recurring mandate (20118), a malformed request. Offering a retry there is
+ * offering a button that mints another failed order and shows the same screen
+ * again; on a card the issuer is already counting, it is worse than useless.
+ *
+ * SILENCE MEANS YES. An undefined verdict is a provider that offered no
+ * guidance, not a refusal to retry, and withholding the button on silence
+ * would strand a buyer whose card is fine.
+ */
+function retryable(decline: CheckoutDecline | null): boolean {
+  return decline?.retriable !== false;
+}
+
+/**
+ * How "Tentar novamente" / "Gerar novo código" look. Under a Pix the store
+ * confirms they step back to outline: the sentence above them asks a buyer who
+ * may already have paid to talk to the store first, and a filled button would
+ * say the opposite.
+ */
+function againLook(byStore: boolean): { variant: "solid" | "outline"; color: "primary" | "neutral" } {
+  return byStore ? { variant: "outline", color: "neutral" } : { variant: "solid", color: "primary" };
+}
+
+/** "Tentar novamente" on a retryable FAILED, "Gerar novo código" on EXPIRED, else nothing. */
+export function PayAgain({
+  copy,
+  status,
+  decline,
+  onRetry,
+  onRegenerate,
+  byStore,
+}: {
+  copy: PaymentStatusCopy;
+  status: OrderStatus;
+  decline: CheckoutDecline | null;
+  onRetry?: () => void;
+  onRegenerate?: () => void;
+  byStore: boolean;
+}): JSX.Element | null {
+  const { Button } = useCheckoutComponents();
+  const again = againLook(byStore);
+  if (status === "FAILED" && onRetry && retryable(decline)) {
+    return (
+      <Button variant={again.variant} color={again.color} size="lg" onClick={onRetry} dataTestId="payment-retry">
+        {copy.retryAction}
+      </Button>
+    );
+  }
+  if (status === "EXPIRED" && onRegenerate) {
+    return (
+      <Button
+        variant={again.variant}
+        color={again.color}
+        size="lg"
+        onClick={onRegenerate}
+        dataTestId="payment-regenerate"
+      >
+        {copy.regenerateAction}
+      </Button>
+    );
+  }
+  return null;
+}
+

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

@@ -4,6 +4,7 @@ import type { JSX, ReactNode } from "react";
 import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
 import type { CheckoutDecline } from "./decline";
 import type { OrderStatus } from "./types";
+import { PayAgain } from "./payment-status-again";
 import { useCheckoutComponents } from "./ui";
 import type { PaymentStatusCopy, StatusOutcomeCopy } from "./view-copy";
 
@@ -120,6 +121,23 @@ function failedOutcome(copy: PaymentStatusCopy, decline: CheckoutDecline | null)
   return (reason ? copy.declined?.[reason] : undefined) ?? copy.failed;
 }
 
+/**
+ * A SETTLED outcome's sentences. A Pix only the store confirms swaps FAILED and
+ * EXPIRED for its own pair when the host wrote one (`copy.manual`): neither the
+ * store's "não recebi" nor its lapsed window proves no money moved.
+ */
+function settledOutcome(
+  copy: PaymentStatusCopy,
+  status: OrderStatus,
+  decline: CheckoutDecline | null,
+  manual: boolean,
+): StatusOutcomeCopy {
+  const byStore = manual ? copy.manual : undefined;
+  if (status === "FAILED") return byStore?.failed ?? failedOutcome(copy, decline);
+  if (status === "EXPIRED") return byStore?.expired ?? copy.expired;
+  return copy[OUTCOME_COPY_KEY[status]];
+}
+
 /**
  * The headline block: icon, outcome, and one supporting line.
  *
@@ -135,23 +153,22 @@ export function OutcomeHero({
   wait,
   decline,
   hero,
+  manual = false,
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
   wait: WaitState;
   decline: CheckoutDecline | null;
   hero?: ReactNode;
+  /** The payment was a Pix only the store confirms — see {@link settledOutcome}. */
+  manual?: boolean;
 }): 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
-    : status === "FAILED"
-      ? failedOutcome(copy, decline)
-      : copy[OUTCOME_COPY_KEY[status]];
+  const outcome = face ? face.outcome : settledOutcome(copy, status, decline, manual);
   return (
     <Box
       // `payment-paid` is load-bearing for the storefront journeys — it is how
@@ -233,23 +250,6 @@ export function PaidFacts({
   );
 }
 
-/**
- * Whether "Tentar novamente" may be offered for a refusal (FUT-1145).
- *
- * `retriable === false` is the provider's OWN verdict that another attempt with
- * this instrument cannot succeed — attempts exhausted (10001), a cancelled
- * recurring mandate (20118), a malformed request. Offering a retry there is
- * offering a button that mints another failed order and shows the same screen
- * again; on a card the issuer is already counting, it is worse than useless.
- *
- * SILENCE MEANS YES. An undefined verdict is a provider that offered no
- * guidance, not a refusal to retry, and withholding the button on silence
- * would strand a buyer whose card is fine.
- */
-function retryable(decline: CheckoutDecline | null): boolean {
-  return decline?.retriable !== false;
-}
-
 /**
  * How much of the eye the way out asks for on a PAID confirmation.
  *
@@ -293,6 +293,7 @@ export function StatusActions({
   onNotPaid,
   onBackToMenu,
   backActionEmphasis = "primary",
+  manual,
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
@@ -310,6 +311,8 @@ export function StatusActions({
   onBackToMenu: () => void;
   /** Whether back-to-menu leads a PAID screen. See {@link BackActionEmphasis}. */
   backActionEmphasis?: BackActionEmphasis;
+  /** The payment was a Pix only the store confirms — see `PayAgain`. */
+  manual?: boolean;
 }): JSX.Element {
   const { Button } = useCheckoutComponents();
   const back = backLook(status, backActionEmphasis);
@@ -337,16 +340,14 @@ export function StatusActions({
           {copy.notPaidAction}
         </Button>
       ) : null}
-      {status === "FAILED" && onRetry && retryable(decline) ? (
-        <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}
+      <PayAgain
+        copy={copy}
+        status={status}
+        decline={decline}
+        onRetry={onRetry}
+        onRegenerate={onRegenerate}
+        byStore={manual === true}
+      />
       <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.

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

@@ -117,6 +117,12 @@ interface PaymentStatusProps {
    * sentence, and it decides whether a retry is offered at all.
    */
   decline?: CheckoutDecline | null;
+  /**
+   * The payment was a Pix only the STORE confirms (FUT-3232): a FAILED or
+   * EXPIRED screen then says the store did not find it, never that nothing
+   * was charged.
+   */
+  manual?: boolean;
 }
 
 /**
@@ -198,6 +204,7 @@ export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
         wait={view.wait}
         decline={view.decline}
         hero={props.paidHero}
+        manual={props.manual === true}
       />
 
       {view.paid ? (
@@ -220,6 +227,7 @@ export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
         onNotPaid={view.notPaid}
         onBackToMenu={onBackToMenu}
         backActionEmphasis={props.backActionEmphasis}
+        manual={props.manual === true}
       />
 
       {view.paid ? props.paidFooter : null}

package/src/components/checkout/pix-view.tsx

@@ -66,7 +66,7 @@ function pixWaitMs(expiresAt: string | undefined): number {
 }
 
 /** The copyable "copia e cola" strip with its copy button. */
-function PixCodeBox({ pix }: { pix: PixCharge }): JSX.Element {
+function PixCodeBox({ pix, onCopied }: { pix: PixCharge; onCopied: () => void }): JSX.Element {
   const { Button, Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.pix;
   const [copied, setCopied] = useState(false);
@@ -75,6 +75,7 @@ function PixCodeBox({ pix }: { pix: PixCharge }): JSX.Element {
     try {
       await navigator.clipboard?.writeText(pix.copyPaste);
       setCopied(true);
+      onCopied();
       setTimeout(() => setCopied(false), 2000);
     } catch {
       /* clipboard unavailable — the code is still visible to copy manually */
@@ -200,6 +201,43 @@ function PixPollFooter({
   );
 }
 
+/**
+ * What a store-confirmed Pix says once its code is copied (FUT-3232).
+ *
+ * The footer's caption already names the store's wait, but in a grey line
+ * under the QR that a buyer on their way to the bank app does not read. Copying
+ * is that moment, so it answers with a notice that stays: the wait can run for
+ * minutes, and "volte para esta tela" is the instruction that keeps the buyer
+ * where the confirmation will land.
+ */
+function ManualCopiedNotice({ manual, copied }: { manual: boolean; copied: boolean }): JSX.Element | null {
+  const { Alert } = useCheckoutComponents();
+  const notice = useCheckoutCopy().screens.pix.manual?.copied;
+  if (!manual || !copied || !notice) return null;
+  return (
+    <Box sx={{ width: "100%", maxWidth: 420, textAlign: "left" }}>
+      <Alert
+        variant="info"
+        title={notice.title}
+        description={notice.description}
+        showIcon
+        data-testid="pix-manual-copied"
+      />
+    </Box>
+  );
+}
+
+/** The code strip and, once it has been copied, what that copy means. */
+function PixCopyRow({ pix, manual }: { pix: PixCharge; manual: boolean }): JSX.Element {
+  const [copied, setCopied] = useState(false);
+  return (
+    <>
+      <PixCodeBox pix={pix} onCopied={() => setCopied(true)} />
+      <ManualCopiedNotice manual={manual} copied={copied} />
+    </>
+  );
+}
+
 /**
  * The pane's two sentences that depend on who confirms. A store-confirmed Pix
  * must not say "a confirmação é automática": nothing confirms it but the store.
@@ -279,7 +317,7 @@ export function PixView({
         <QRCode value={pix.copyPaste} size={200} />
       </Box>
 
-      <PixCodeBox pix={pix} />
+      <PixCopyRow pix={pix} manual={manual} />
 
       <Text variant="caption" size="xs" color="secondary" as="p" data-testid="pix-expiry">
         {sentences.validUntil(validUntil)}

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

@@ -28,6 +28,16 @@ export const PT_BR_PAYMENT_STATUS_COPY: PaymentStatusCopy = {
     heading: "O código expirou",
     support: "Nenhum valor foi cobrado. Gere um novo código para continuar.",
   },
+  manual: {
+    failed: {
+      heading: "A loja não identificou o seu Pix",
+      support: "Se você já pagou, fale com a loja antes de pagar de novo.",
+    },
+    expired: {
+      heading: "A loja não confirmou o pagamento a tempo",
+      support: "Se você já pagou, fale com a loja antes de pagar de novo.",
+    },
+  },
   awaitingTimedOut: {
     heading: "Ainda não recebemos a confirmação",
     support:

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

@@ -123,6 +123,13 @@ export interface PixPaneCopy {
     instructions(totalLabel: string): string;
     validUntil(time: string): string;
     awaiting: string;
+    /**
+     * Shown once the buyer copies the code, and kept: copying is the moment
+     * they leave for their bank app, so it is when they must learn the wait
+     * that follows is the STORE's, and that the answer arrives on this screen.
+     * Optional so a host's own copy without it simply shows no notice.
+     */
+    copied?: { title: string; description: string };
   };
 }
 

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

@@ -57,6 +57,11 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
         `Pay ${totalLabel} with the QR code or the code below. The store checks it arrived and confirms your order.`,
       validUntil: (time) => `The store confirms the payment by ${time}.`,
       awaiting: 'Waiting for the store to confirm the payment…',
+      copied: {
+        title: 'Code copied. Now pay in your bank app',
+        description:
+          'Once you have paid, come back to this screen and wait: the store checks it arrived and confirms your order right here.',
+      },
     },
   },
   card: {

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

@@ -46,6 +46,11 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
         `Pague ${totalLabel} com o QR code ou o código abaixo. A loja confere o recebimento e confirma o seu pedido.`,
       validUntil: (time) => `A loja confirma o pagamento até ${time}.`,
       awaiting: 'Aguardando confirmação do pagamento pela loja…',
+      copied: {
+        title: 'Código copiado. Agora pague no app do seu banco',
+        description:
+          'Depois de pagar, volte para esta tela e aguarde: a loja confere o recebimento e confirma o seu pedido aqui mesmo.',
+      },
     },
   },
   card: {

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

@@ -93,6 +93,14 @@ export interface PaymentStatusCopy {
    */
   declined: Partial<Record<CheckoutDeclineReason, StatusOutcomeCopy>>;
   awaitingTimedOut: StatusOutcomeCopy;
+  /**
+   * FAILED and EXPIRED for a Pix only the STORE confirms (FUT-3232). The store
+   * answering "não recebi", or letting its window lapse, says nothing about
+   * whether the buyer paid — a static key takes money whatever the store
+   * later says — so "nothing was charged" would be a guess, and "pay again" an
+   * invitation to pay twice. Absent, those two keep their ordinary sentences.
+   */
+  manual?: { failed: StatusOutcomeCopy; expired: 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