@12-apps/payments-frontend 3.31.1 → 3.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.31.1",
+  "version": "3.32.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/checkout-steps.tsx

@@ -289,6 +289,7 @@ export function PaymentStep({
           onChange={onMethodChange}
           cardUnavailable={choice.cardUnavailable}
           offered={choice.offered}
+          pixByStore={config?.chain?.find((link) => link.methods.includes("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/method-picker.tsx

@@ -22,9 +22,11 @@ interface MethodOption {
  * host's Portuguese. The order and the icons are still ours — that is layout,
  * not language.
  */
-function methodOptions(copy: MethodPickerCopy): MethodOption[] {
+function methodOptions(copy: MethodPickerCopy, pixByStore: boolean): MethodOption[] {
+  // A Pix the store confirms by hand is not "aprovação imediata" (FUT-3232).
+  const pixDescription = (pixByStore ? copy.pixManualDescription : undefined) ?? copy.pixDescription;
   return [
-    { value: "PIX", label: copy.pixLabel, description: copy.pixDescription, icon: <PixIcon /> },
+    { value: "PIX", label: copy.pixLabel, description: pixDescription, icon: <PixIcon /> },
     {
       value: "CARD",
       label: copy.cardLabel,
@@ -125,8 +127,9 @@ function MethodTile({
 function visibleOptions(
   copy: MethodPickerCopy,
   offered: PaymentMethod[] | null,
+  pixByStore: boolean,
 ): MethodOption[] {
-  return methodOptions(copy).filter(
+  return methodOptions(copy, pixByStore).filter(
     (option) => offered === null || offered.includes(option.value),
   );
 }
@@ -136,6 +139,7 @@ export function MethodPicker({
   onChange,
   cardUnavailable = false,
   offered = null,
+  pixByStore = false,
 }: {
   /** The chosen method, or `null` before the buyer has picked one. */
   value: PaymentMethod | null;
@@ -144,10 +148,12 @@ export function MethodPicker({
   cardUnavailable?: boolean;
   /** Methods the store's chain can charge, or `null` while unknown (fail open). */
   offered?: PaymentMethod[] | null;
+  /** True ⇒ the chain's first PIX provider is one the STORE confirms by hand. */
+  pixByStore?: boolean;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.method;
-  const options = visibleOptions(copy, offered);
+  const options = visibleOptions(copy, offered, pixByStore);
   return (
     <Box>
       <Text variant="body" size="sm" weight="bold" as="p" style={{ marginBottom: 8 }}>

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/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

@@ -32,6 +32,12 @@ export interface MethodPickerCopy {
   cardLabel: string;
   /** What each method is like to use — shown under its name. */
   pixDescription: string;
+  /**
+   * PIX's line when the store confirms it by hand (the chain's first PIX
+   * provider declares `confirmation: 'MANUAL'`). Optional; absent falls back
+   * to `pixDescription`, so a host enabling such a provider should set it.
+   */
+  pixManualDescription?: string;
   cardDescription: string;
   /** This store's providers cannot take that method. */
   unavailableHere: string;

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

@@ -22,6 +22,7 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     pixLabel: 'PIX',
     cardLabel: 'Card',
     pixDescription: 'Approved instantly',
+    pixManualDescription: 'Confirmed by the store',
     cardDescription: 'Credit, paid in full',
     unavailableHere: 'Unavailable in this store',
   },

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

@@ -15,6 +15,7 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     pixLabel: 'PIX',
     cardLabel: 'Cartão',
     pixDescription: 'Aprovação imediata',
+    pixManualDescription: 'Confirmado pela loja',
     cardDescription: 'Crédito à vista',
     unavailableHere: 'Indisponível nesta loja',
   },

package/src/components/checkout/types.ts

@@ -275,15 +275,15 @@ export interface CheckoutChainLink {
   provider: string;
   /**
    * The provider's own name as a BUYER should read it ("InfinitePay"), which
-   * `GET /api/checkout/config` publishes per entry.
-   *
-   * Optional, and the DEGRADE DIRECTION IS "SAY NOTHING": an older host serves
-   * no name, and a hand-off screen then describes where the buyer is going
-   * without naming it, rather than printing the internal `provider` id — a
-   * buyer shown "infinitepay" learns less than one shown nothing, and learns
-   * it in a vocabulary that is ours rather than theirs.
+   * `GET /api/checkout/config` publishes per entry. Optional, and the DEGRADE
+   * DIRECTION IS "SAY NOTHING": an older host serves no name, and a hand-off
+   * screen then describes where the buyer is going without naming it, rather
+   * than printing the internal `provider` id — a buyer shown "infinitepay"
+   * learns less than one shown nothing, in a vocabulary ours rather than theirs.
    */
   displayName?: string | null;
+  /** `MANUAL`: only the store confirms this entry's charges (`pixmanual`); absent is automatic. */
+  confirmation?: "AUTOMATIC" | "MANUAL";
   tokenization: "NONE" | "PUBLIC_KEY" | "SDK" | "REDIRECT";
   publicKey: string | null;
   mockTokenization: boolean;

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