@12-apps/payments-frontend 3.21.4 → 3.23.0

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;
@@ -173,6 +185,17 @@ export interface CreateOrderRequest {
   buyer: BuyerInfo;
   /** Opt-in: save buyer name/phone (not CPF — never persisted here) for next-checkout pre-fill. */
   saveProfile: boolean;
+  /**
+   * WHICH settlement the buyer chose, when it is not one of the two above
+   * (FUT-1240).
+   *
+   * `method` is what the CHAIN can be asked to charge, so a pipeline host's own
+   * registered settlement — "pay the courier", "pay the waiter" — cannot be
+   * said there, and without this every one of them arrives as the same request.
+   * ABSENT for `PIX` and `CARD`, which is what keeps it additive; otherwise the
+   * registered `SettlementMethodDescriptor.id` verbatim (`flows/pipeline`).
+   */
+  settlementMethod?: string;
 }
 
 /** What the flow hands the host's `saveBuyerContact` port on "Continuar". */
@@ -358,8 +381,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;
 }

package/src/components/checkout/use-card-checkout.ts

@@ -22,12 +22,12 @@ import {
   type CardInstruments,
   type RefreshBrowserKey,
 } from "./card-instruments";
+import { handOverToChallenge, reportResolved, type ChallengeScope } from "./card-outcome";
 import { useCheckoutClientApi } from "./client-context";
-import { rememberHostedOrder } from "./hosted-return";
-import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
+import { useCheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
 import { useOneClickArmed, useOneClickPay } from "./one-click";
-import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
+import type { BuyerInfo, CheckoutOrder, OnCheckoutResolved, OrderStatus } from "./types";
 import { usePaymentPolling } from "./use-payment-polling";
 import type { CardCopy } from "../../card/copy";
 import { useCheckoutCopy } from "./copy-context";
@@ -40,7 +40,17 @@ const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
  * actually charge are offered. The slug arrives as an argument (the host's
  * routing owns it); absent, the list is unscoped, exactly as before FUT-697.
  */
-function useSavedCards(tenantSlug: string | undefined): {
+function useSavedCards(
+  tenantSlug: string | undefined,
+  /**
+   * The buyer is here because a card was REFUSED (FUT-1145), so the saved card
+   * this would otherwise preselect is the one that just failed. The list is
+   * still offered — another saved card may well work — but nothing is chosen
+   * for them, which puts the form in front of a buyer whose only untried
+   * instrument is a new one.
+   */
+  freshInstrument: boolean,
+): {
   savedCards: SavedCard[];
   selection: string;
   setSelection: (id: string) => void;
@@ -55,12 +65,12 @@ function useSavedCards(tenantSlug: string | undefined): {
       if (!active) return;
       setSavedCards(cards);
       const first = cards[0];
-      if (first) setSelection(first.id);
+      if (first && !freshInstrument) setSelection(first.id);
     });
     return () => {
       active = false;
     };
-  }, [tenantSlug, client]);
+  }, [tenantSlug, client, freshInstrument]);
 
   return { savedCards, selection, setSelection };
 }
@@ -159,29 +169,12 @@ type CardSubmit = Pick<
  * It was 36 healthy polls, which is the same 90 s at the default 2500 ms
  * interval and an unbounded wait at any other — including the one that
  * mattered, where every poll is FAILING and the healthy count never moves.
- * PIX passes no bound at all and keeps today's behavior: its charge expires
- * server-side and comes back as a terminal EXPIRED.
+ * PIX is bounded too since FUT-1170, but by the CHARGE's own expiry rather
+ * than by a constant: a code the buyer can still scan is still worth watching,
+ * and one that has died is not.
  */
 const CARD_AWAITING_WAIT_MS = 90_000;
 
-/**
- * Hand the buyer to the provider's authentication page (FUT-698) — Stripe's
- * redirect-based 3-D Secure. Park the order and navigate, the same trip a
- * redirect provider's link takes (FUT-556): the return lands back on this
- * checkout route, where the hosted-resume machinery polls the parked order.
- */
-function handOverToChallenge(
-  order: CheckoutOrder,
-  url: string,
-  navigate: CheckoutNavigate,
-): void {
-  // PARK FIRST. The navigation may not come back to a live SPA at all, and a
-  // return trip that finds nothing parked lands the buyer on a blank
-  // confirmation after they have paid.
-  rememberHostedOrder(order);
-  navigate(url);
-}
-
 /** The buyer's card is invalid — block the submit and show which field. */
 function blockedByForm(form: CardFormState): boolean {
   if (!form.usingNewCard) return false;
@@ -257,10 +250,13 @@ function useCardSubmit(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   providerConfig: CardTokenizationConfig,
-  onResolved: (status: OrderStatus) => void,
+  onResolved: OnCheckoutResolved,
   pollIntervalMs: number,
   form: CardFormState,
   providerChain: readonly CardChainLink[],
+  /** WHOSE store and WHICH basket this charge is for — parked with a 3DS
+   *  hand-off, which is otherwise resumable over any basket anywhere. */
+  scope: ChallengeScope,
 ): CardSubmit {
   const [submitting, setSubmitting] = useState(false);
   const [submitted, setSubmitted] = useState(false);
@@ -319,11 +315,11 @@ function useCardSubmit(
     // 3-D Secure (FUT-698): the buyer must finish on the provider's page.
     // `submitting` stays true on purpose — the tab is navigating away.
     if (charged.data.hostedCheckoutUrl) {
-      return handOverToChallenge(order, charged.data.hostedCheckoutUrl, navigate);
+      return handOverToChallenge(order, charged.data.hostedCheckoutUrl, navigate, scope);
     }
-    // A business outcome (e.g. declined → FAILED) shows the status screen;
-    // an accepted charge begins polling for the async confirmation.
-    if (charged.data.status !== "AWAITING_PAYMENT") onResolved(charged.data.status);
+    // A business outcome shows the status screen, carrying the refusal the
+    // server classified (FUT-1145); an accepted charge begins polling.
+    if (charged.data.status !== "AWAITING_PAYMENT") reportResolved(charged.data, onResolved);
     else setSubmitted(true);
   };
 
@@ -338,7 +334,7 @@ export function useCardCheckout(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   providerConfig: CardTokenizationConfig,
-  onResolved: (status: OrderStatus) => void,
+  onResolved: OnCheckoutResolved,
   pollIntervalMs: number,
   /** The store whose saved cards may be offered (host routing owns the slug). */
   tenantSlug?: string,
@@ -347,8 +343,12 @@ export function useCardCheckout(
    * per entry so a card charge can fail over. Omitted ⇒ the head alone.
    */
   providerChain: readonly CardChainLink[] = [],
+  /** Do not preselect a saved card — the last one was refused (FUT-1145). */
+  freshInstrument = false,
+  /** WHOSE store and WHICH basket, for the 3-D Secure hand-off's parked order. */
+  scope: ChallengeScope = {},
 ): CardCheckout {
-  const { savedCards, selection, setSelection } = useSavedCards(tenantSlug);
+  const { savedCards, selection, setSelection } = useSavedCards(tenantSlug, freshInstrument);
   const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
   const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
   const [saveCard, setSaveCard] = useState(false);
@@ -373,6 +373,7 @@ export function useCardCheckout(
     pollIntervalMs,
     { card, usingNewCard, selection, saveCard, validate, setFieldErrors },
     providerChain,
+    scope,
   );
   // The tap a one-click buyer already made (`./one-click.tsx`). Nothing about
   // the charge differs — this only presses the button, and only while a SAVED