@12-apps/payments-frontend 3.22.0 → 3.23.0

package/src/flows/pipeline/steps/pay-steps.tsx

@@ -0,0 +1,182 @@
+/**
+ * THE PAY PHASE (FUT-1240): the Pix code, the card form, the hand-off, and the
+ * return from one.
+ *
+ * Every step here is `phase: "pay"` except the resume, and that matters: the
+ * engine drops the whole phase for a settlement method whose `raisesCharge` is
+ * `false`. So a shopper paying the courier never reaches any of these, and no
+ * lane has to remember not to render them.
+ *
+ * The resume is `before-pay` rather than `pay` deliberately. A shopper coming
+ * back from a provider's own page has to be resolved BEFORE they are offered a
+ * way to pay again — and the same screen has to work for an in-person method,
+ * which has no pay phase at all.
+ */
+import { Box } from "@mui/material";
+import { useEffect, type JSX } from "react";
+
+import { useCheckoutComponents } from "../../../components/checkout/ui";
+import { useHostedResume, type HostedResume } from "../../../components/checkout/use-hosted-resume";
+import type { FlowsRuntime } from "../../runtime";
+import { usePipelineActions } from "../actions";
+import { CARD_PANE_STEP, PIX_PANE_STEP } from "../methods";
+import type { CheckoutStep, CheckoutStepRender } from "../types";
+
+export const HANDOFF_STEP_ID = "handoff";
+export const RESUME_STEP_ID = "resume";
+
+/** A raised order whose provider takes the money on its own page. */
+function handedOver(url: string | undefined): url is string {
+  return typeof url === "string" && url.length > 0;
+}
+
+function PixView({ ctx }: CheckoutStepRender<void>): JSX.Element | null {
+  const actions = usePipelineActions();
+  const PixPayment = actions.screens.PixPayment;
+  if (!ctx.order) return null;
+  return <PixPayment payable={ctx.order} onResolved={actions.resolve} />;
+}
+
+function CardView({ ctx }: CheckoutStepRender<void>): JSX.Element | null {
+  const actions = usePipelineActions();
+  const CardEntry = actions.screens.CardEntry;
+  if (!ctx.order) return null;
+  return <CardEntry payable={ctx.order} onResolved={actions.resolve} />;
+}
+
+/**
+ * The Pix code, once one exists.
+ *
+ * WHICH method this pane belongs to is not asked here: the engine reads it off
+ * the descriptor that named this step as its `pane`, so a method the package
+ * has never heard of can reuse the pane by naming it, and no pane states its
+ * own method twice.
+ */
+export const pixStep: CheckoutStep = {
+  id: PIX_PANE_STEP,
+  phase: "pay",
+  order: 0,
+  applies(ctx) {
+    return ctx.order !== null && !handedOver(ctx.order.hostedCheckoutUrl);
+  },
+  complete(ctx) {
+    return ctx.outcome !== null;
+  },
+  render(props) {
+    return <PixView {...props} />;
+  },
+};
+
+/** The card form, once an order exists to charge. Its method is its `pane` owner. */
+export const cardStep: CheckoutStep = {
+  id: CARD_PANE_STEP,
+  phase: "pay",
+  order: 1,
+  applies(ctx) {
+    return ctx.order !== null && !handedOver(ctx.order.hostedCheckoutUrl);
+  },
+  complete(ctx) {
+    return ctx.outcome !== null;
+  },
+  render(props) {
+    return <CardView {...props} />;
+  },
+};
+
+/**
+ * The hand-off interstitial: the order is parked and the tab is leaving.
+ *
+ * `complete` is `false` forever on purpose — there is no next step on THIS
+ * page. What comes back is a fresh mount that meets the resume step.
+ */
+function HandoffView({ ctx, back }: CheckoutStepRender<void>): JSX.Element | null {
+  const { Text } = useCheckoutComponents();
+  const actions = usePipelineActions();
+  const HostedHandoff = actions.screens.HostedHandoff;
+  const url = ctx.order?.hostedCheckoutUrl;
+  if (!ctx.order || !handedOver(url)) return null;
+  const pipeline = actions.copy.pipeline;
+  const waiting =
+    (ctx.method === null ? undefined : pipeline.awaitingHandover[ctx.method]) ?? pipeline.loading;
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      <Text variant="body" size="sm" color="secondary" as="p" data-testid="checkout-awaiting-handover">
+        {waiting}
+      </Text>
+      <HostedHandoff url={url} payable={ctx.order} onCancel={back} />
+    </Box>
+  );
+}
+
+export const handoffStep: CheckoutStep = {
+  id: HANDOFF_STEP_ID,
+  phase: "pay",
+  order: 2,
+  applies(ctx) {
+    return ctx.order !== null && handedOver(ctx.order.hostedCheckoutUrl);
+  },
+  complete() {
+    return false;
+  },
+  render(props) {
+    return <HandoffView {...props} />;
+  },
+};
+
+/**
+ * A shopper coming back from a provider's own page.
+ *
+ * It runs the package's OWN resume machinery — `useHostedResume`, with this
+ * checkout's slug and basket — rather than a second reading of the parked
+ * entry. That matters more than the extra hook: `useHostedResume` carries the
+ * whole FUT-1213 rule, including the deferral until the cart has answered, the
+ * bounded wait when it never does, and the one server ASK for a basket that
+ * has changed. A step that re-implemented "is something parked?" would be a
+ * second answer to a question with one correct one, on the money path.
+ *
+ * WHERE a resume lands is `hosted-return.ts`'s decision, honoured here:
+ *
+ *  - a HAND-OFF has nothing left on our page, so it waits on the confirmation
+ *    until the poll reaches a terminal state;
+ *  - anything else — a Pix code, a card charge raised on our own page — is
+ *    ADOPTED as this visit's order, and the walk puts the shopper back in
+ *    front of the pane that still has what they need.
+ */
+export function buildResumeStep(runtime: FlowsRuntime): CheckoutStep<void, HostedResume> {
+  return {
+    id: RESUME_STEP_ID,
+    phase: "before-pay",
+    order: -10,
+    useFacts() {
+      const tenantSlug = runtime.useTenantSlug();
+      const cart = runtime.config.useCart();
+      return useHostedResume(tenantSlug, cart.identity);
+    },
+    applies(ctx, resume) {
+      return ctx.outcome === null && ctx.order === null && resume.order !== null;
+    },
+    complete(ctx) {
+      return ctx.outcome !== null || ctx.order !== null;
+    },
+    render({ facts }) {
+      return <ResumeView resume={facts} />;
+    },
+  };
+}
+
+/** The resumed order, taken up by whichever half of the walk owns it. */
+function ResumeView({ resume }: { resume: HostedResume }): JSX.Element | null {
+  const actions = usePipelineActions();
+  const { adoptOrder, resolve } = actions;
+  const { order, step, status } = resume;
+  useEffect(() => {
+    if (!order) return;
+    // An on-page charge belongs to the WALK, not to this screen: adopting it
+    // makes the pane apply on the very next render.
+    if (step === "payment") adoptOrder(order);
+    else if (status !== null && status !== "AWAITING_PAYMENT") resolve(status);
+  }, [order, step, status, adoptOrder, resolve]);
+  if (!order || step === "payment") return null;
+  const PaymentStatus = actions.screens.PaymentStatus;
+  return <PaymentStatus status={status} payable={order} />;
+}

package/src/flows/pipeline/steps/status-step.tsx

@@ -0,0 +1,41 @@
+/**
+ * THE CONFIRMATION (FUT-1240) — the one step every settlement reaches.
+ *
+ * `complete` is `false` forever: a walk whose last step is finished has
+ * nowhere to put the shopper, and this is where a checkout ends. The
+ * registered method may replace the screen entirely (`Confirmation` on its
+ * descriptor), which is how a settlement that raises no charge says
+ * "recebemos seu pedido" instead of "pagamento aprovado" without the engine
+ * knowing either sentence.
+ */
+import type { JSX } from "react";
+
+import { descriptorFor, usePipelineActions } from "../actions";
+import type { CheckoutStep, CheckoutStepRender } from "../types";
+
+export const STATUS_STEP_ID = "status";
+
+function StatusView({ ctx }: CheckoutStepRender<void>): JSX.Element {
+  const actions = usePipelineActions();
+  const descriptor = descriptorFor(actions.methods, ctx);
+  const Confirmation = descriptor?.Confirmation;
+  if (Confirmation && ctx.order) return <Confirmation ctx={ctx} order={ctx.order} />;
+  const PaymentStatus = actions.screens.PaymentStatus;
+  return <PaymentStatus status={ctx.outcome} payable={ctx.order} />;
+}
+
+export const statusStep: CheckoutStep = {
+  id: STATUS_STEP_ID,
+  phase: "after-pay",
+  order: 0,
+  label: "status",
+  applies(ctx) {
+    return ctx.outcome !== null;
+  },
+  complete() {
+    return false;
+  },
+  render(props) {
+    return <StatusView {...props} />;
+  },
+};

package/src/flows/pipeline/types.ts

@@ -0,0 +1,232 @@
+/**
+ * THE CHECKOUT PIPELINE'S VOCABULARY (FUT-1240, step 4 of FUT-1216).
+ *
+ * A checkout is a list of STEPS, a list of GATES and a list of SETTLEMENT
+ * METHODS. Each is a plain object in an array; registration is array
+ * membership and nothing else. The engine derives which step the shopper is
+ * on rather than remembering it, so a reload, a torn-down tab and a hand-off
+ * return all land where the server's own facts say they should.
+ *
+ * ## Two properties this file exists to keep
+ *
+ * 1. **Method syntax, never arrow properties.** Under `strictFunctionTypes` a
+ *    method's parameters are BIVARIANT while a property holding a function is
+ *    contravariant — so `CheckoutStep<S, F>` is assignable to
+ *    {@link AnyCheckoutStep} with no `any` and no cast. Written as
+ *    `applies: (ctx, facts) => boolean` instead, every registration would need
+ *    a cast, and this repo forbids `any`.
+ * 2. **The package names no host.** Nothing here imports a host, a sibling
+ *    workspace package or a domain word. A mode, a mesa, a comanda and a
+ *    delivery address are all host concepts and reach the engine as a
+ *    registered step or a registered method, never as a field.
+ */
+import type { ComponentType, ReactNode } from "react";
+
+import type { CheckoutCartView } from "../../components/checkout/checkout-flow";
+import type {
+  BuyerInfo,
+  CheckoutError,
+  CheckoutOrder,
+  CheckoutProviderConfig,
+  CreateOrderRequest,
+  OrderStatus,
+  SettlementCheckout,
+} from "../../components/checkout/types";
+import type {
+  CheckoutStepperCopy,
+  CheckoutViewCopy,
+} from "../../components/checkout/view-copy";
+
+/**
+ * Where a step sits in the walk. The engine sorts by this first and by
+ * {@link CheckoutStep.order} second, so a host appends a step without knowing
+ * what else is registered.
+ *
+ * `pay` is the phase the no-charge rule is stated over: a settlement method
+ * that raises no charge mounts NO `pay` step, ever — see
+ * {@link SettlementMethodDescriptor.raisesCharge}.
+ */
+export type CheckoutStepPhase = "details" | "before-pay" | "pay" | "after-pay";
+
+/** Everything a step, a gate or a method may read. All of it server-owned or parked. */
+export interface CheckoutContext {
+  tenantSlug?: string;
+  /** `GET /config`: chain, methods, tokenization. */
+  config: CheckoutProviderConfig | null;
+  configPending: boolean;
+  cart: CheckoutCartView;
+  /** Host-resolved balance, opaque scope. */
+  settlement: SettlementCheckout | null;
+  buyer: BuyerInfo;
+  taxIdOnFile: boolean;
+  /** A {@link SettlementMethodDescriptor.id}, or `null` before a choice. */
+  method: string | null;
+  /** Raised now, resumed from the server, or parked by a hand-off. */
+  order: CheckoutOrder | null;
+  outcome: OrderStatus | null;
+  intent: { oneClick: boolean; resuming: boolean; presetMethod: string | null };
+  /** Every step's declared slice, by step id. */
+  slices: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A step's own scrap of state, DECLARED rather than held.
+ *
+ * The engine owns the storage, which is what makes a reload survivable: a
+ * `session` slice is parked under `payments.checkout.<slug>.<stepId>` and
+ * rehydrated on mount. Nothing money-shaped belongs here — that is the order.
+ */
+export interface StepSlice<S> {
+  initial(ctx: CheckoutContext): S;
+  /** `"session"` ⇒ `payments.checkout.<slug>.<stepId>`, rehydrated on mount. */
+  persist: "none" | "session";
+  /**
+   * Trust nothing that came back out of storage — the `hosted-return.ts` rule.
+   * A `session` slice with NO parser is never rehydrated: the engine cannot
+   * check a shape it has not been told, and a half-written value reaching a
+   * step as its state is exactly what that rule exists to stop.
+   */
+  parse?(raw: unknown): S | null;
+}
+
+/** What a step's `render` is handed. Its own type so the method syntax stays readable. */
+export interface CheckoutStepRender<S> {
+  ctx: CheckoutContext;
+  slice: S;
+  setSlice(s: S): void;
+  /** Done here — clear any back-navigation and let the walk move on. */
+  advance(): void;
+  /** The previous applying step, or the host's catalog when there is none. */
+  back(): void;
+  /** A server refusal THIS step claimed through {@link CheckoutStep.answersCodes}. */
+  error: CheckoutError | null;
+}
+
+/** One step of the walk. */
+export interface CheckoutStep<S = void, F = void> {
+  id: string;
+  phase: CheckoutStepPhase;
+  order?: number;
+  /** Host hook; runs EVERY render, in array order. */
+  useFacts?(): F;
+  /** Pure. */
+  applies(ctx: CheckoutContext, facts: F): boolean;
+  /** Pure — the current step is the first applying step whose answer is `false`. */
+  complete(ctx: CheckoutContext, facts: F, slice: S): boolean;
+  slice?: StepSlice<S>;
+  render(p: CheckoutStepRender<S> & { facts: F }): ReactNode;
+  /** Server refusal codes re-rendered HERE, never as a generic retry. */
+  answersCodes?: readonly string[];
+  contribute?(ctx: CheckoutContext, facts: F, slice: S): Partial<CreateOrderRequest>;
+  /** Absent ⇒ an interstitial, not a stepper node. */
+  label?: keyof CheckoutStepperCopy | null;
+}
+
+/** Any registered step. Reachable with no cast because every member above is a method. */
+export type AnyCheckoutStep = CheckoutStep<unknown, unknown>;
+
+/** What a gate decided about this shopper. */
+export type GateVerdict =
+  | { kind: "pass" }
+  | { kind: "pending" }
+  | {
+      kind: "refuse";
+      Screen: ComponentType<{
+        ctx: CheckoutContext;
+        error: CheckoutError | null;
+        retry(): void;
+      }>;
+    };
+
+/** Something that must be true before ANY step renders. */
+export interface CheckoutGate<F = void> {
+  id: string;
+  useFacts?(): F;
+  /** Pure. */
+  decide(ctx: CheckoutContext, facts: F): GateVerdict;
+  answersCodes?: readonly string[];
+  /** Bypassed when a hand-off from this tab is still waiting to be resolved. */
+  standsAsideForResume?: boolean;
+}
+
+/** Any registered gate. */
+export type AnyCheckoutGate = CheckoutGate<unknown>;
+
+/**
+ * A way of settling — the seam a no-charge settlement never had.
+ *
+ * `raisesCharge: false` is the whole reason this type exists: placing the
+ * order IS the settlement, so there is no `/charge`, no poll, and no payment
+ * surface after the method is chosen. The engine enforces that ONCE, over the
+ * `pay` phase, so no lane can forget it.
+ */
+export interface SettlementMethodDescriptor<F = void> {
+  /** `"PIX"`, `"CARD"`, `"ON_DELIVERY"`, `"WAITER"`, `"BOLETO"`… */
+  id: string;
+  /** `false` ⇒ no `/charge`, no poll; placing the order IS the settlement. */
+  raisesCharge: boolean;
+  /** The `pay`-phase step id shown once the order exists; `null` ⇒ Confirmation. */
+  pane: string | null;
+  useFacts?(): F;
+  offered(ctx: CheckoutContext, facts: F): boolean;
+  Review?: ComponentType<{
+    ctx: CheckoutContext;
+    place(): void;
+    placing: boolean;
+    error: CheckoutError | null;
+  }>;
+  /** Default: the package's own `PaymentStatus`. */
+  Confirmation?: ComponentType<{ ctx: CheckoutContext; order: CheckoutOrder }>;
+  tile(copy: CheckoutViewCopy): { label: string; hint?: string };
+}
+
+/** Any registered settlement method. */
+export type AnySettlementMethod = SettlementMethodDescriptor<unknown>;
+
+/**
+ * Where the shopper leaves for, and how.
+ *
+ * A hook for the label because it is the host's router that knows which
+ * catalog this checkout came from, and a value would freeze the first one.
+ */
+export interface CheckoutExit {
+  useCatalog(): { to: string; label: string };
+  navigate(to: string): void;
+}
+
+/**
+ * The engine's half of `PaymentFlowsConfig` — every key OPTIONAL.
+ *
+ * Setting ANY of them switches `Checkout` onto the pipeline. Setting NONE
+ * leaves it rendering exactly today's `CheckoutFlow`, which is the whole
+ * meaning of this step being additive.
+ */
+export interface CheckoutPipelineConfig {
+  /** Merged with the package's own, by phase then `order`. */
+  steps?: readonly AnyCheckoutStep[];
+  /** Evaluated in order before any step renders. */
+  gates?: readonly AnyCheckoutGate[];
+  /** Merged with the package's PIX + CARD. */
+  settlementMethods?: readonly AnySettlementMethod[];
+  /** The HOST reads its own URL; the package reads nothing. */
+  useIntent?(): CheckoutContext["intent"];
+  /** Resume from the SERVER, not only from a parked hand-off. */
+  useOpenPayable?(): { order: CheckoutOrder | null; pending: boolean };
+  /** Absent ⇒ `ports.exitToCatalog()`, which is what every host wires today. */
+  exit?: CheckoutExit;
+  /** The host invalidates ITS keys. */
+  onSettled?(outcome: OrderStatus, order: CheckoutOrder): void;
+}
+
+/** Whether a config asked for the pipeline at all. */
+export function pipelineRequested(config: CheckoutPipelineConfig): boolean {
+  return (
+    config.steps !== undefined ||
+    config.gates !== undefined ||
+    config.settlementMethods !== undefined ||
+    config.useIntent !== undefined ||
+    config.useOpenPayable !== undefined ||
+    config.exit !== undefined ||
+    config.onSettled !== undefined
+  );
+}

package/src/flows/public.ts

@@ -0,0 +1,78 @@
+/**
+ * THE FACTORY'S PUBLIC SURFACE — `createPaymentFlows` (FUT-741) and the
+ * checkout pipeline it can now run (FUT-1240).
+ *
+ * Listed here rather than inline in `src/index.ts` for the reason
+ * `./activation/public.ts` already gives: the root barrel is at its size gate,
+ * and a surface that grows with every plugin type is one that will keep
+ * growing. Everything below is re-exported verbatim by the root.
+ */
+
+// ---------------------------------------------------------------------------
+// The MOUNTED buyer checkout (FUT-741) — `createPaymentFlows` returns every
+// screen pre-bound to one transport, one scope, one slot table and one set of
+// host ports. Additive: the hand-composing path is unchanged.
+// ---------------------------------------------------------------------------
+export { createPaymentFlows } from './create-payment-flows';
+// A type and nothing else now: `DEFAULT_CHECKOUT_COPY_FE` used to sit beside it
+// and was the only value this module ever published (FUT-760).
+export type { CheckoutCopyFE } from './copy';
+export {
+  type BoundCheckoutClient,
+  type BuyerDetailsProps,
+  type CheckoutAvailability,
+  type CheckoutConfigState,
+  type CheckoutController,
+  type CheckoutPorts,
+  type CheckoutScreens,
+  type PaymentFlows,
+  type PaymentFlowsConfig,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// The checkout PIPELINE (FUT-1240) — steps, gates and settlement methods as
+// registered plugins, with the current step DERIVED from the server's own
+// facts rather than held in a `useState` a reload forgets.
+//
+// ADDITIVE: a host that registers none of these gets exactly the flat
+// three-step `CheckoutFlow`, unchanged, down to its test ids. What the types
+// below buy is the ability to say "this store has a step of its own", "this
+// shopper may not check out yet", and "this settlement raises no charge" — the
+// last of which the package had no seam for at all, so every in-person payment
+// path was written beside the checkout instead of inside it.
+// ---------------------------------------------------------------------------
+export type {
+  AnyCheckoutGate,
+  AnyCheckoutStep,
+  AnySettlementMethod,
+  CheckoutContext,
+  CheckoutExit,
+  CheckoutGate,
+  CheckoutPipelineConfig,
+  CheckoutStep,
+  CheckoutStepPhase,
+  CheckoutStepRender,
+  GateVerdict,
+  SettlementMethodDescriptor,
+  StepSlice,
+} from './pipeline/types';
+/**
+ * The step ids the PACKAGE registers, so a host ordering its own steps around
+ * them names a constant instead of retyping a string that can change.
+ */
+export {
+  DADOS_STEP_ID,
+  HANDOFF_STEP_ID,
+  METHOD_STEP_ID,
+  RESUME_STEP_ID,
+  STATUS_STEP_ID,
+} from './pipeline/steps';
+export { CARD_PANE_STEP, PIX_PANE_STEP } from './pipeline/methods';
+/**
+ * Where a step's parked slice lives — `payments.checkout.<slug>.<stepId>`.
+ * Public for the same reason `HOSTED_ORDER_STORAGE_KEY` is: a host clearing
+ * storage on sign-out, or a spec asserting a resume, otherwise retypes it.
+ */
+export { sliceKey } from './pipeline/slices';
+/** Whose plugin answers a refusal code — the routing, without the renderer. */
+export { refusalOwner, type RefusalOwner } from './pipeline/refusal-routing';

package/src/flows/screens-hosted.tsx

@@ -23,6 +23,7 @@
 import { Box } from "@mui/material";
 import { useEffect, useState, type JSX } from "react";
 
+import { parkedBasket, type CheckoutBasketIdentity } from "../components/checkout/basket";
 import { rememberHostedOrder, takeHostedOrder } from "../components/checkout/hosted-return";
 import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
 import { useCheckoutComponents } from "../components/checkout/ui";
@@ -31,18 +32,45 @@ import { usePaymentPolling } from "../components/checkout/use-payment-polling";
 import { FlowsShell, type FlowsRuntime } from "./runtime";
 import type { CheckoutScreens } from "./types";
 
+/** Whose store and which basket this hand-off belongs to. */
+interface HandoverScope {
+  tenantSlug?: string;
+  basket?: CheckoutBasketIdentity;
+}
+
 /** Park the order, then navigate — exactly once, even under StrictMode. */
-function useHandover(payable: CheckoutOrder, url: string, navigate: (url: string) => void): void {
+function useHandover(
+  payable: CheckoutOrder,
+  url: string,
+  navigate: (url: string) => void,
+  /**
+   * PARKED WITH THE STORE AND THE BASKET (FUT-1240).
+   *
+   * This call site named neither, and 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 entry against ANY basket. So the one
+   * hand-off screen this package ships was exempt from the multi-tenant
+   * scoping (FUT-556) and from the basket binding (FUT-1213) — it resumed over
+   * whatever checkout mounted next. The other three parks were fixed one at a
+   * time; this is the last of them.
+   */
+  scope: HandoverScope,
+): void {
   const [done, setDone] = useState(false);
   useEffect(() => {
     if (done) return;
     setDone(true);
+    const basket = parkedBasket(scope.basket);
     // `handoff: true` is what tells the return leg this order was finished on
     // ANOTHER SITE (FUT-1140): only such an order resumes onto the confirmation
     // screen, because only such an order has nothing left on our page to show.
-    rememberHostedOrder(payable, { handoff: true });
+    rememberHostedOrder(payable, {
+      ...(scope.tenantSlug === undefined ? {} : { tenantSlug: scope.tenantSlug }),
+      ...(basket === undefined ? {} : { basket }),
+      handoff: true,
+    });
     navigate(url);
-  }, [done, payable, url, navigate]);
+  }, [done, payable, url, navigate, scope.tenantSlug, scope.basket]);
 }
 
 function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHandoff"] {
@@ -57,7 +85,12 @@ function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHando
   }): JSX.Element {
     const { Button, LoadingState, Text } = useCheckoutComponents();
     const copy = runtime.copy;
-    useHandover(payable, url, runtime.navigate);
+    const tenantSlug = runtime.useTenantSlug();
+    const cart = runtime.config.useCart();
+    useHandover(payable, url, runtime.navigate, {
+      ...(tenantSlug === undefined ? {} : { tenantSlug }),
+      ...(cart.identity === undefined ? {} : { basket: cart.identity }),
+    });
     return (
       <Box
         data-testid="checkout-hosted-handoff"

package/src/flows/screens-pay.tsx

@@ -15,6 +15,7 @@ import { PixView } from "../components/checkout/pix-view";
 import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
 import { useCheckoutComponents } from "../components/checkout/ui";
 
+import { useCatalogExit } from "./catalog-exit";
 import { FlowsShell, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import type { CheckoutScreens } from "./types";
 
@@ -79,6 +80,10 @@ function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStat
     status: OrderStatus | null;
     payable?: CheckoutOrder | null;
   }) {
+    // The SAME door the chrome's back link takes (FUT-1240). Bound straight to
+    // the port, this control ignored a registered `exit` — so one host got its
+    // router from one way out of the checkout and a page load from the other.
+    const backToMenu = useCatalogExit(runtime);
     return (
       <FlowsShell runtime={runtime}>
         <PaymentStatusView
@@ -86,7 +91,7 @@ function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStat
           status={status}
           totalLabel={payable?.totalLabel ?? ""}
           orderId={payable?.orderId}
-          onBackToMenu={runtime.config.ports.exitToCatalog}
+          onBackToMenu={backToMenu}
           paidExtra={runtime.config.confirmation?.extra}
         />
       </FlowsShell>

package/src/flows/types.ts

@@ -45,6 +45,7 @@ import type { useCheckoutController } from "../components/checkout/use-checkout-
 import type { Result } from "../result";
 
 import type { CheckoutCopyFE } from "./copy";
+import type { CheckoutPipelineConfig, GateVerdict } from "./pipeline/types";
 
 /** The host's remedy on the unavailable screen, and its veto over a live chain. */
 export interface CheckoutAvailability {
@@ -88,8 +89,17 @@ export interface CheckoutPorts {
   useAvailability?(): CheckoutAvailability;
 }
 
-/** What `createPaymentFlows` is configured with. */
-export interface PaymentFlowsConfig {
+/**
+ * What `createPaymentFlows` is configured with.
+ *
+ * It extends {@link CheckoutPipelineConfig}, whose every key is OPTIONAL: set
+ * one and `Checkout` renders through the checkout PIPELINE (FUT-1240); set
+ * none and it renders exactly the `CheckoutFlow` it always did, with the same
+ * pixels and the same test ids. That is the whole meaning of the pipeline
+ * landing additively — a host adopts it when it has a step, a gate or a
+ * settlement method of its own to register, and not a release earlier.
+ */
+export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
   /** Where the `createPaymentFlowsBE` mount lives. Default `/api/checkout`. */
   transport?: CheckoutTransportBinding;
 
@@ -209,6 +219,19 @@ export interface PaymentFlows {
   screens: CheckoutScreens;
   /** The flow controller, pre-bound to the ports — the easy path is not the only path. */
   useCheckout(): CheckoutController;
+  /**
+   * MAY THIS SHOPPER CHECK OUT — the registered gate list, headless (FUT-1240).
+   *
+   * The same list, in the same order, that `Checkout` runs before it renders
+   * anything. Exported so the surfaces that OFFER a checkout — a cart
+   * drawer's CTA, a buy-now button — consume the answer the checkout will
+   * give rather than a second one of their own. Two surfaces deciding this
+   * separately is how a storefront ends up offering a checkout the checkout
+   * itself refuses.
+   *
+   * A host that registered no gates always passes.
+   */
+  useAdmission(): GateVerdict;
   useCheckoutConfig(): CheckoutConfigState;
   client: BoundCheckoutClient;
 }