@12-apps/payments-frontend 3.21.4 → 3.23.0

package/src/components/checkout/use-hosted-resume.ts

@@ -0,0 +1,326 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+
+import type { CheckoutBasketIdentity } from "./basket";
+import { useCheckoutClientApi } from "./client-context";
+import {
+  forgetHostedOrder,
+  takeHostedOrder,
+  type HostedResumeStep,
+} from "./hosted-return";
+import type { CheckoutOrder, OrderStatus } from "./types";
+import { usePaymentPolling } from "./use-payment-polling";
+
+/**
+ * A LAYOUT effect where there is a DOM, an ordinary one where there is not.
+ *
+ * The resume decision cannot be made during render — it waits for the host's
+ * cart to load — so it lands from an effect, and an ordinary effect runs AFTER
+ * paint: a buyer coming back from a payment would see one frame of the Dados
+ * or Pagamento step before their confirmation replaced it. A layout effect
+ * commits before the browser paints, so the flow simply opens where it belongs.
+ *
+ * The branch is by ENVIRONMENT rather than by render pass, which is what makes
+ * it a constant and not a conditional hook. It costs nothing on a server render
+ * either: everything this hook decides from is `sessionStorage`, which does not
+ * exist there — and `useLayoutEffect` on the server is a warning React prints
+ * for exactly the case where the effect would matter and cannot run.
+ */
+export const useResumeEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * The leg of checkout that RESUMES a payment this tab already raised (FUT-556,
+ * FUT-1140, FUT-1213, FUT-1146).
+ *
+ * Three tickets share this hook because they are three halves of one mechanism,
+ * and stacking them would have produced three: FUT-1213 decides WHETHER a
+ * parked checkout may be resumed, FUT-1140 makes the parked entry cover every
+ * raised order rather than only a hand-off, and FUT-1146 gives the buyer the
+ * one way out that a hosted charge's own protocol cannot offer.
+ *
+ * ## How long it keeps asking, and how often
+ *
+ * TWO RATES, because one rate cannot serve this wait. The interval decides two
+ * things that pull opposite ways: how fast a buyer WHO PAID is told so, and
+ * what an abandoned checkout costs for the rest of the window. Every poll is a
+ * provider round trip, so a slow rate is cheap and leaves a paying buyer
+ * watching a spinner seconds longer than they need to — and the person on this
+ * screen has almost always paid. A single number picks one of them to lose;
+ * this shipped at a flat 5 s and picked the wrong one.
+ *
+ * So: 2.5 s for the first two minutes, which is where essentially every real
+ * webhook lands, then 10 s for the remaining thirteen.
+ *
+ * Fifteen minutes because by then a webhook that was ever coming has come. The
+ * BOUND is that wall-clock window, not a poll count (FUT-1144): a poll that
+ * FAILS increments nothing, so a connection that never came back left this
+ * screen asking with no end at all. A clock cannot be stopped by the failure it
+ * is measuring.
+ */
+const HOSTED_RESUME_FAST_MS = 2_500;
+const HOSTED_RESUME_SLOW_MS = 10_000;
+/** Two minutes at the fast rate, before the wait is worth economising on. */
+const HOSTED_RESUME_FAST_POLLS = (2 * 60_000) / HOSTED_RESUME_FAST_MS;
+/** Thirteen more at the slow one — 15 minutes all told. */
+const HOSTED_RESUME_WINDOW_MS = 15 * 60_000;
+
+/**
+ * How long the buyer waits before being offered a way out (FUT-1146).
+ *
+ * A cancelled or refused hosted payment has NO terminal state to arrive at.
+ * The provider's `payment_check` publishes `success` and `paid` and nothing
+ * else — no status, no cancel, no decline — the webhook verifier refuses an
+ * unpaid delivery outright, and every server-side writer of FAILED is
+ * unreachable from a hosted cancel. So the screen waits fifteen minutes and
+ * then tells someone who never paid not to pay again. The only signal that
+ * exists is the BUYER's, and this is how long we wait before asking for it.
+ *
+ * Thirty seconds: a webhook that was ever coming lands within seconds of the
+ * payment (the fast rate above is sized on exactly that), so a wait still going
+ * at thirty is already unusual — while a button offered instantly would sit
+ * under a spinner during the two seconds in which most confirmations arrive,
+ * inviting a shopper to abandon a payment that is landing. The release itself
+ * is guarded server-side regardless: a payable the provider reports PAID is
+ * answered PAID and released by nothing.
+ */
+const RELEASE_OFFER_AFTER_MS = 30_000;
+
+/** What the resumed leg contributes to the controller's surface. */
+export interface HostedResume {
+  /** The rehydrated order, once the decision has been made. */
+  order: CheckoutOrder | null;
+  /** Where the flow should open for it — see `hosted-return.ts`. */
+  step: HostedResumeStep | null;
+  status: OrderStatus | null;
+  timedOut: boolean;
+  error: string | null;
+  checkAgain: () => void;
+  /**
+   * The buyer's own "I did not pay" (FUT-1146), or `undefined` while it must
+   * not be offered — nothing is being resumed, the wait has settled, or the
+   * grace period above has not elapsed.
+   */
+  release: (() => void) | undefined;
+  /** A release is in flight; the action must not be pressable twice. */
+  releasing: boolean;
+  /** The order was released — the caller opens a fresh checkout. */
+  released: boolean;
+}
+
+/**
+ * How long the decision waits for the host's cart before deciding without it.
+ *
+ * The deferral (FUT-1213) assumes the cart eventually answers. A cart FETCH can
+ * fail — on exactly the flaky connection a buyer has coming back from their
+ * bank app — and an unbounded wait there is the same shape of bug this ticket
+ * is about, pointed the other way: the flow renders Dados forever and a paid
+ * buyer's confirmation never lands.
+ *
+ * So the wait is bounded, and past the bound the decision is made WITHOUT a
+ * basket, which is the pre-1213 answer: resume. That is the permissive
+ * direction, deliberately, and it is the same one `hostedCheckoutReturnPending`
+ * takes for an unloaded cart — a shopper whose cart never loaded cannot check
+ * out with it either way, so the only outcome still worth protecting is the
+ * confirmation of a payment that already happened.
+ *
+ * Eight seconds: long enough that no ordinary cart fetch reaches it, short
+ * enough that a buyer coming back from a payment is not left looking at a form.
+ */
+const BASKET_WAIT_MS = 8_000;
+
+/** The decision, made ONCE, as soon as the basket is loaded enough to make it. */
+function useResumeDecision(
+  tenantSlug: string | undefined,
+  basket: CheckoutBasketIdentity | undefined,
+): {
+  resumed: { order: CheckoutOrder; step: HostedResumeStep } | null;
+  setResumed: (next: { order: CheckoutOrder; step: HostedResumeStep } | null) => void;
+  asking: CheckoutOrder | null;
+  setAsking: (next: CheckoutOrder | null) => void;
+} {
+  const [resumed, setResumed] = useState<{ order: CheckoutOrder; step: HostedResumeStep } | null>(
+    null,
+  );
+  const [asking, setAsking] = useState<CheckoutOrder | null>(null);
+  // Once, whatever React does with this effect. The decision CONSUMES the
+  // parked entry, so a second run would find nothing and un-resume a buyer
+  // mid-confirmation — which is what StrictMode's double-invoke does for free.
+  const decided = useRef(false);
+  const waitedLongEnough = useBasketDeadline();
+
+  useResumeEffect(() => {
+    if (decided.current) return;
+    // Past the deadline the basket is treated as unnamed rather than as
+    // pending — see BASKET_WAIT_MS. A cart that never answered cannot be
+    // compared with, and waiting forever is the worse of the two failures.
+    const decision = takeHostedOrder(tenantSlug, waitedLongEnough ? undefined : basket);
+    // WAIT is the host's cart still loading. Nothing was read and nothing was
+    // consumed; the next render with a loaded basket decides for real.
+    if (decision.verdict === "WAIT") return;
+    decided.current = true;
+    if (decision.verdict === "RESUME") setResumed({ order: decision.order, step: decision.step });
+    if (decision.verdict === "ASK") setAsking(decision.order);
+  }, [tenantSlug, basket, waitedLongEnough]);
+
+  return { resumed, setResumed, asking, setAsking };
+}
+
+/**
+ * Rule 3: a DIFFERENT basket stands, so ask the server once what the parked
+ * order is worth.
+ *
+ * PAID resumes on the confirmation — that order is settled in the host's own
+ * row by the webhook, and it is the one thing a shopper must never lose.
+ * Anything else drops the entry and leaves the checkout to the basket in front
+ * of them.
+ *
+ * A FAILED ASK leaves the entry parked, deliberately. "We could not reach the
+ * server" is not "the order is not paid", and the shopper still gets their
+ * normal checkout either way — so the cheap outcome is that a later mount asks
+ * again and can still find the confirmation, rather than a dropped entry that
+ * can never be recovered.
+ */
+function useAskBeforeResuming(
+  asking: CheckoutOrder | null,
+  onResume: (next: { order: CheckoutOrder; step: HostedResumeStep }) => void,
+  onDrop: () => void,
+): void {
+  const client = useCheckoutClientApi();
+  useEffect(() => {
+    if (!asking) return undefined;
+    let live = true;
+    void client.getStatus(asking.orderId).then((answer) => {
+      if (!live) return;
+      if (!answer.ok) {
+        onDrop();
+        return;
+      }
+      forgetHostedOrder();
+      if (answer.data === "PAID") onResume({ order: asking, step: "status" });
+      else onDrop();
+    });
+    return () => {
+      live = false;
+    };
+  }, [asking, client, onDrop, onResume]);
+}
+
+/** Whether the wait for the host's cart has run out — see {@link BASKET_WAIT_MS}. */
+function useBasketDeadline(): boolean {
+  const [elapsed, setElapsed] = useState(false);
+  useEffect(() => {
+    const timer = setTimeout(() => setElapsed(true), BASKET_WAIT_MS);
+    return () => clearTimeout(timer);
+  }, []);
+  return elapsed;
+}
+
+/** Whether the "I did not pay" way out may be offered yet — see the constant. */
+function useReleaseOffered(waiting: boolean): boolean {
+  const [elapsed, setElapsed] = useState(false);
+  useEffect(() => {
+    if (!waiting) return undefined;
+    const timer = setTimeout(() => setElapsed(true), RELEASE_OFFER_AFTER_MS);
+    return () => clearTimeout(timer);
+  }, [waiting]);
+  return waiting && elapsed;
+}
+
+/** The release itself: ask the server to let the order go, unless it is paid. */
+function useRelease(
+  order: CheckoutOrder | null,
+  onSettled: (status: OrderStatus) => void,
+  onReleased: () => void,
+): { run: () => void; releasing: boolean } {
+  const client = useCheckoutClientApi();
+  const [releasing, setReleasing] = useState(false);
+  const run = useCallback(() => {
+    if (!order || releasing) return;
+    setReleasing(true);
+    void client.releaseCheckout({ orderId: order.orderId }).then((answer) => {
+      setReleasing(false);
+      // The one answer that overrules the buyer: they say they did not pay and
+      // the provider says they did. They keep their confirmation.
+      if (answer.ok && answer.data === "PAID") {
+        onSettled("PAID");
+        return;
+      }
+      // Everything else — released, or a request that never got out — returns
+      // them to a usable checkout. A server that could not be reached has not
+      // taken their money either, and leaving them on a dead wait to be sure
+      // is the failure this ticket exists to remove.
+      forgetHostedOrder();
+      onReleased();
+    });
+  }, [client, order, releasing, onSettled, onReleased]);
+  return { run, releasing };
+}
+
+/** Still waiting on an answer for the order we resumed — nothing more. */
+function stillWaiting(polling: boolean, released: boolean, settled: OrderStatus | null): boolean {
+  if (!polling || released) return false;
+  return settled === null || settled === "AWAITING_PAYMENT";
+}
+
+/** The wait's own poll, run for the CONFIRMATION leg and nothing else. */
+function useResumePoll(
+  order: CheckoutOrder | null,
+  polling: boolean,
+): { status: OrderStatus | null; timedOut: boolean; error: string | null; checkAgain: () => void } {
+  // A resume that lands back on the payment step is handed to the PIX or card
+  // pane, which runs its own wait — two polls for one order would race each
+  // other to the same answer.
+  return usePaymentPolling(order === null ? null : order.orderId, {
+    enabled: polling,
+    intervalMs: HOSTED_RESUME_FAST_MS,
+    slowAfterPolls: HOSTED_RESUME_FAST_POLLS,
+    slowIntervalMs: HOSTED_RESUME_SLOW_MS,
+    maxWaitMs: HOSTED_RESUME_WINDOW_MS,
+  });
+}
+
+export function useHostedResume(
+  tenantSlug?: string,
+  basket?: CheckoutBasketIdentity,
+): HostedResume {
+  const { resumed, setResumed, asking, setAsking } = useResumeDecision(tenantSlug, basket);
+  const [override, setOverride] = useState<OrderStatus | null>(null);
+  const [released, setReleased] = useState(false);
+
+  const drop = useCallback(() => setAsking(null), [setAsking]);
+  const resume = useCallback(
+    (next: { order: CheckoutOrder; step: HostedResumeStep }) => {
+      setAsking(null);
+      setResumed(next);
+    },
+    [setAsking, setResumed],
+  );
+  useAskBeforeResuming(asking, resume, drop);
+
+  const order = resumed === null ? null : resumed.order;
+  const step = resumed === null ? null : resumed.step;
+  const polling = step === "status";
+  const wait = useResumePoll(order, polling);
+
+  const settled = override === null ? wait.status : override;
+  const offered = useReleaseOffered(stillWaiting(polling, released, settled));
+  const onReleased = useCallback(() => {
+    setResumed(null);
+    setReleased(true);
+  }, [setResumed]);
+  const { run, releasing } = useRelease(order, setOverride, onReleased);
+
+  return {
+    order,
+    step,
+    // A RELEASED order reports nothing. The poll's last answer is still sitting
+    // in its own state, and a controller that read it would carry "we are
+    // confirming your payment" into the fresh checkout the buyer just asked for.
+    status: released ? null : settled,
+    timedOut: wait.timedOut,
+    error: wait.error,
+    checkAgain: wait.checkAgain,
+    release: offered ? run : undefined,
+    releasing,
+    released,
+  };
+}

package/src/components/checkout/use-payment-polling.ts

@@ -1,8 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from "react";
 
 import { useCheckoutClientApi } from "./client-context";
 import { useCheckoutCopy } from "./copy-context";
-import { createPollLoop, type PollLoop, type PollingOptions } from "./poll-loop";
+import { createPollLoop, type PollLoop, type PollingOptions, type PollSink } from "./poll-loop";
 import type { OrderStatus } from "./types";
 
 /** What a consumer reads off the wait, and the one action it can take. */
@@ -24,6 +24,50 @@ interface PaymentPollingState {
   checkAgain: () => void;
 }
 
+/**
+ * What one wait has learned, and WHICH order it learned it about (FUT-1170).
+ *
+ * The three facts used to be three `useState`s with no order id attached, so a
+ * consumer re-pointed at a new charge read the PREVIOUS charge's answer until
+ * the new loop's first poll returned. That is not a cosmetic flash: a terminal
+ * status is acted on, and `PixView` acts on it by handing the flow to the
+ * confirmation screen — so a fresh, unpaid PIX code was reported settled by the
+ * code it had just replaced. Regenerating an expired charge is the path that
+ * does exactly this, and it is the one FUT-1170 was reported from.
+ *
+ * Stamping the answer and comparing at READ time (rather than clearing the
+ * state in an effect) is what makes the guard hold in the render that changes
+ * the id, with no intermediate frame in which the stale answer is still live.
+ */
+interface PollAnswer {
+  orderId: string | null;
+  status: OrderStatus | null;
+  error: string | null;
+  timedOut: boolean;
+}
+
+const NO_ANSWER: PollAnswer = { orderId: null, status: null, error: null, timedOut: false };
+
+/**
+ * Where a wait for ONE order writes what it learns.
+ *
+ * Every write is stamped with the order the loop was started for, and a write
+ * arriving against a DIFFERENT stamp starts from `NO_ANSWER` rather than
+ * merging into the previous order's facts.
+ */
+function sinkFor(
+  orderId: string,
+  setAnswer: Dispatch<SetStateAction<PollAnswer>>,
+): PollSink {
+  const write = (patch: Partial<PollAnswer>): void =>
+    setAnswer((prev) => ({ ...(prev.orderId === orderId ? prev : NO_ANSWER), ...patch, orderId }));
+  return {
+    setStatus: (status) => write({ status }),
+    setError: (error) => write({ error }),
+    setTimedOut: (timedOut) => write({ timedOut }),
+  };
+}
+
 
 /**
  * Ask again the moment the shopper could plausibly have an answer for us.
@@ -77,9 +121,7 @@ export function usePaymentPolling(
     askTimeoutMs,
   }: PollingOptions = {},
 ): PaymentPollingState {
-  const [status, setStatus] = useState<OrderStatus | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [timedOut, setTimedOut] = useState(false);
+  const [answer, setAnswer] = useState<PollAnswer>(NO_ANSWER);
   // Whichever mount this tree is bound to (FUT-741). Stable per provider, so it
   // belongs in the deps below rather than being read out of a ref: a checkout
   // re-pointed at another mount must re-poll against THAT one.
@@ -106,7 +148,7 @@ export function usePaymentPolling(
         askTimeoutMs,
         askTimeoutError: transportCopy.offline,
       },
-      { setStatus, setError, setTimedOut },
+      sinkFor(orderId, setAnswer),
     );
     loop.current = running;
     running.restart();
@@ -133,6 +175,15 @@ export function usePaymentPolling(
     loop.current?.restart();
   }, []);
 
-  return { status, error, timedOut, checkAgain };
+  // The answer is this order's, or there is no answer yet. Read here rather
+  // than reset in an effect: an effect runs after paint, so the render that
+  // re-points the hook would still hand a consumer the old charge's status.
+  const current = answer.orderId === orderId ? answer : NO_ANSWER;
+  return {
+    status: current.status,
+    error: current.error,
+    timedOut: current.timedOut,
+    checkAgain,
+  };
 }
 

package/src/components/checkout/use-wallet-charge.ts

@@ -1,5 +1,7 @@
 import { useEffect, useState } from "react";
 
+import { parkedBasket } from "./basket";
+import type { ChallengeScope } from "./card-outcome";
 import { useCheckoutClientApi } from "./client-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
 import { rememberHostedOrder } from "./hosted-return";
@@ -62,12 +64,33 @@ export interface WalletCharge {
  */
 const WALLET_AWAITING_WAIT_MS = 90_000;
 
+/**
+ * Park the order before the tab leaves, WITH the store and the basket
+ * (FUT-1240).
+ *
+ * Both absences are read as "no opinion" by the resume — `belongsHere` passes
+ * a slug-less entry at any store and the basket rule passes a basket-less one
+ * against any basket — so a wallet's 3-D Secure hand-off that named neither
+ * resumed over whatever checkout mounted next. The card path has carried these
+ * since FUT-1213; this call site is the one that did not.
+ */
+function parkForHandover(order: CheckoutOrder, scope: ChallengeScope): void {
+  const basket = parkedBasket(scope.basket);
+  rememberHostedOrder(order, {
+    ...(scope.tenantSlug === undefined ? {} : { tenantSlug: scope.tenantSlug }),
+    ...(basket === undefined ? {} : { basket }),
+    handoff: true,
+  });
+}
+
 /** The wallet charge state machine. See the module comment. */
 export function useWalletCharge(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   onResolved: (status: OrderStatus) => void,
   pollIntervalMs = 2500,
+  /** WHOSE store and WHICH basket — see {@link parkForHandover} (FUT-1240). */
+  scope: ChallengeScope = {},
 ): WalletCharge {
   const [phase, setPhase] = useState<WalletPhase>("idle");
   const [error, setError] = useState<string | null>(null);
@@ -116,7 +139,7 @@ export function useWalletCharge(
     // FUT-698): park the order and hand the buyer over, exactly as the card
     // path does. `phase` stays as-is — the tab is navigating away.
     if (charged.data.hostedCheckoutUrl) {
-      rememberHostedOrder(order);
+      parkForHandover(order, scope);
       navigate(charged.data.hostedCheckoutUrl);
       return true;
     }

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

@@ -1,4 +1,5 @@
 import type { CheckoutCopy } from "./copy-context";
+import type { CheckoutDeclineReason } from "./decline";
 
 /**
  * Every string the legacy checkout views render — required props, with NO
@@ -71,8 +72,26 @@ export interface StatusOutcomeCopy {
 export interface PaymentStatusCopy {
   paid: StatusOutcomeCopy;
   awaiting: StatusOutcomeCopy;
+  /**
+   * A refusal with nothing more specific to say. Still the whole of what a
+   * buyer reads when the server sent no `declineReason`, or sent one this
+   * bundle has never heard of — see {@link PaymentStatusCopy.declined}.
+   */
   failed: StatusOutcomeCopy;
   expired: StatusOutcomeCopy;
+  /**
+   * What a REFUSED CARD says, per normalized reason (FUT-1145).
+   *
+   * The server has classified declines since FUT-340 and then discarded the
+   * classification on the wire, so an expired card, a card reported stolen, no
+   * funds, and "attempts exhausted — do not retry" all reached the buyer as one
+   * sentence offering a retry that could not work. Each of those asks something
+   * different of the person holding the phone, and only they can act on it.
+   *
+   * A reason with no entry — a newer server, a host mid-migration — falls back
+   * to {@link PaymentStatusCopy.failed}, which is exactly today's screen.
+   */
+  declined: Partial<Record<CheckoutDeclineReason, StatusOutcomeCopy>>;
   awaitingTimedOut: StatusOutcomeCopy;
   /**
    * The wait cannot reach the payment right now (FUT-1144) — and is STILL
@@ -86,6 +105,19 @@ export interface PaymentStatusCopy {
   awaitingUnreachable: StatusOutcomeCopy;
   retryAction: string;
   regenerateAction: string;
+  /**
+   * "I did not pay" — the buyer's own way out of a wait with no terminal state
+   * (FUT-1146).
+   *
+   * A cancelled or refused payment on a provider's own page produces NO signal
+   * anywhere: the provider's check publishes `success` and `paid` and nothing
+   * else, an unpaid webhook delivery fails verification before it is parsed,
+   * and no server-side writer of FAILED is reachable from it. So the screen
+   * waited fifteen minutes and then told someone who had never paid not to pay
+   * again. The only signal that exists is this one, and it is safe to act on
+   * because the server re-asks the provider before letting anything go.
+   */
+  notPaidAction: string;
   /**
    * Ask now, rather than waiting for the next automatic poll — and, once the
    * wait has run out, the only thing that starts it again.
@@ -98,12 +130,50 @@ export interface PaymentStatusCopy {
   receiptEmailLabel: string;
 }
 
+/**
+ * The pipeline engine's own two sentences (FUT-1240).
+ *
+ * REQUIRED, both of them, and stated here rather than defaulted for the reason
+ * every other string in this file is: a default in the origin host's language
+ * reads as finished right up until a shopper sees it. These two are the whole
+ * of what the ENGINE renders on its own account — everything else on screen
+ * belongs to a step, a gate or a settlement method.
+ */
+export interface CheckoutPipelineCopy {
+  /**
+   * What is on screen while the checkout has nothing to show yet: a gate still
+   * deciding, the store's protocol still in flight, or no step applying.
+   *
+   * It replaces a blank frame. A shopper who taps "pagar" and gets an empty
+   * page taps again.
+   */
+  loading: string;
+  /**
+   * PER SETTLEMENT METHOD, what the shopper reads between choosing it and the
+   * surface that takes the money arriving — the hand-off interstitial's own
+   * line. Keyed by `SettlementMethodDescriptor.id`.
+   *
+   * Per method because the sentences are not interchangeable: a Pix hand-off
+   * and a card challenge send the shopper to different places for different
+   * reasons, and one shared "aguarde" describes neither. A method with no
+   * entry falls back to {@link CheckoutPipelineCopy.loading}, which is what a
+   * host registering a new charged method gets until it writes the sentence.
+   */
+  awaitingHandover: Readonly<Record<string, string>>;
+}
+
 /** What the legacy `CheckoutFlow` itself renders and must be handed. */
 export interface CheckoutViewCopy {
   steps: CheckoutStepperCopy;
   dados: DadosStepCopy;
   emptyCart: EmptyCartCopy;
   status: PaymentStatusCopy;
+  /**
+   * The engine's own two sentences (FUT-1240). Carried here, beside the
+   * stepper labels, so a host still answers copy exactly once — the pipeline
+   * is another way of rendering this same checkout, not a second surface.
+   */
+  pipeline: CheckoutPipelineCopy;
   /**
    * The words the screens BELOW these read — the card fields, the wallet
    * panes, the buyer-details inputs (FUT-760).

package/src/components/checkout/wallet-pane.tsx

@@ -149,7 +149,13 @@ export function WalletCardPane(props: WalletPaneProps): JSX.Element {
   const { Alert } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.settling;
   const { order, buyer, config, tenantSlug, onResolved, pollIntervalMs } = props;
-  const wallet = useWalletCharge(order, buyer, onResolved, pollIntervalMs);
+  const { freshInstrument, basket } = props;
+  // The same store and basket the card path already parks with (FUT-1213,
+  // FUT-1240): a wallet's 3-D Secure hand-off is a hand-off like any other.
+  const wallet = useWalletCharge(order, buyer, onResolved, pollIntervalMs, {
+    ...(tenantSlug === undefined ? {} : { tenantSlug }),
+    ...(basket === undefined ? {} : { basket }),
+  });
   // A sheet failure the wallet reported before any charge existed (pay.js
   // refused, merchant validation unavailable, the sheet errored) — shown
   // beside the form, which stays usable.
@@ -187,6 +193,8 @@ export function WalletCardPane(props: WalletPaneProps): JSX.Element {
         tenantSlug={tenantSlug}
         onResolved={onResolved}
         pollIntervalMs={pollIntervalMs}
+        freshInstrument={freshInstrument}
+        basket={basket}
       />
     </Box>
   );

package/src/flows/catalog-exit.ts

@@ -0,0 +1,33 @@
+/**
+ * ONE WAY OUT OF A CHECKOUT (FUT-1240).
+ *
+ * A checkout has two controls that leave it — the chrome's back link on the
+ * first step, and "voltar ao cardápio" on the confirmation — and until this
+ * existed they answered differently: back honoured a registered
+ * {@link CheckoutExit} while the confirmation went straight to
+ * `ports.exitToCatalog`. So a host that registered its router's own catalog
+ * route got it from one control and a full page navigation from the other,
+ * with the difference visible only to the shopper who pressed the second one.
+ *
+ * `exit` is a FACTORY-scope constant, so calling its `useCatalog()` here is a
+ * hook call whose presence never changes between renders.
+ */
+import { useCallback } from "react";
+
+import type { FlowsRuntime } from "./runtime";
+
+/**
+ * Leave for the host's catalog, through whichever door it registered.
+ *
+ * `exit` wins when there is one — it is the host's own router, and a router
+ * navigation keeps the SPA alive. `ports.exitToCatalog` is the fallback every
+ * host already wires, and stays the answer for a host that registered nothing.
+ */
+export function useCatalogExit(runtime: FlowsRuntime): () => void {
+  const exit = runtime.config.exit;
+  const catalog = exit?.useCatalog();
+  return useCallback(() => {
+    if (exit && catalog) exit.navigate(catalog.to);
+    else runtime.config.ports.exitToCatalog();
+  }, [exit, catalog, runtime]);
+}