@12-apps/payments-frontend 3.21.3 → 3.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.21.3",
+  "version": "3.22.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.",
@@ -22,7 +22,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.26.1",
+    "@12-apps/payments-backend": "^4.27.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/checkout/basket.ts

@@ -0,0 +1,85 @@
+/**
+ * WHAT IS IN THE BASKET, as one comparable fact (FUT-1213).
+ *
+ * A parked checkout has to be able to ask "is this still the basket the order
+ * was raised from?" when the buyer comes back — and the answer cannot be the
+ * cart's ID. Emptying a cart ("Esvaziar carrinho") keeps the row: the same id
+ * comes back holding nothing, then holding something else entirely, and a
+ * comparison on the id says "same basket" for a shopper who has thrown the old
+ * one away and started again.
+ *
+ * So the identity is the LINES: which ones, and how many of each. Two baskets
+ * with the same lines in a different order are the same basket; one extra unit
+ * of one line is not.
+ *
+ * The HOST computes it, because the host owns the cart — this module only says
+ * what shape the answer takes and how to build one from lines, so that every
+ * adopter's signature is built the same way and a package-side comparison can
+ * mean something.
+ */
+
+/** One line of the host's basket, reduced to what identity depends on. */
+export interface CheckoutBasketLine {
+  /** The line's own stable handle — a cart-line id, never a product id alone. */
+  id: string;
+  quantity: number;
+}
+
+/**
+ * The lines' signature, or `null` for an empty basket.
+ *
+ * `null` rather than `""` because an EMPTY basket is a meaningful state on this
+ * path rather than a missing answer: the server closes a cart when its order is
+ * paid, so an empty basket is exactly what a buyer who paid comes back to.
+ *
+ * Sorted before joining, so the answer does not depend on the order the host
+ * happens to hold its lines in — a re-fetch that returns them differently
+ * sorted must not read as a different basket.
+ *
+ * The id is ENCODED before it is joined. `id + "x" + quantity` on a `|` join is
+ * ambiguous the moment an id can contain either character: `[a×1, b×2]` and the
+ * single line `["ax1|b" × 2]` produce the same string, and two different baskets
+ * that compare equal is a resume over the wrong one. Unreachable with the cuid
+ * and uuid ids every adopter has today — and this is exported for hosts whose
+ * ids nobody here has seen, so it is encoded rather than argued about.
+ */
+export function basketSignature(lines: readonly CheckoutBasketLine[]): string | null {
+  if (lines.length === 0) return null;
+  return lines
+    .map((line) => `${encodeURIComponent(line.id)}x${line.quantity}`)
+    .sort()
+    .join("|");
+}
+
+/**
+ * The basket in front of the checkout right now, as the resume rule reads it.
+ *
+ * `ready` is not a nicety. The host's cart is fetched, so the first render of a
+ * checkout has an EMPTY cart that is merely unloaded — and "empty" is the one
+ * state the rule resumes on unconditionally (it is the paid buyer's normal
+ * state). Deciding against an unseeded cart would resume every abandoned
+ * hand-off on every mount, which is the bug this whole rule exists to remove.
+ * So the decision waits.
+ */
+export interface CheckoutBasketIdentity {
+  /** The lines' signature; `null` ⇒ the basket is empty. */
+  signature: string | null;
+  /** False while the host's cart is still loading — decide nothing yet. */
+  ready: boolean;
+}
+
+/**
+ * The signature to PARK with an order, or nothing.
+ *
+ * `undefined` — meaning "no basket was recorded" — for a host that names none
+ * AND for a cart that has not answered yet. The second is the one worth
+ * stating: a loading cart reports `signature: null`, which is the value that
+ * means EMPTY, and an order parked as "raised from an empty basket" would later
+ * be compared against the real one and read as a different basket. Recording
+ * nothing is honest and degrades to the pre-1213 resume; recording `null` would
+ * be a fact we do not have.
+ */
+export function parkedBasket(basket: CheckoutBasketIdentity | undefined): string | null | undefined {
+  if (!basket || !basket.ready) return undefined;
+  return basket.signature;
+}

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

@@ -0,0 +1,81 @@
+import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
+import type { CheckoutDecline } from "./decline";
+import { rememberHostedOrder } from "./hosted-return";
+import type { CheckoutNavigate } from "./navigate-context";
+import type { ChargeOutcome, CheckoutOrder, OnCheckoutResolved } from "./types";
+
+/**
+ * WHAT HAPPENS TO A CHARGE'S ANSWER — the two endings a card submit can have
+ * that are not "keep polling".
+ *
+ * Split out of `./use-card-checkout.ts`, which is at its size ceiling. Both
+ * halves are about the same moment: the provider has answered, and the buyer
+ * is either being sent somewhere or being told something.
+ */
+
+/** Whose store and which basket a challenge's parked order belongs to. */
+export interface ChallengeScope {
+  tenantSlug?: string;
+  basket?: CheckoutBasketIdentity;
+}
+
+/**
+ * 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.
+ *
+ * IT PARKS WITH THE SAME FACTS the other hand-off does, and that is a fix
+ * rather than a tidy-up: this call site named neither the store nor the basket,
+ * and both absences are read as "no opinion" by the resume — `belongsHere`
+ * passes an entry with no slug at ANY store, and the basket rule passes an
+ * entry with no basket against ANY basket. So a 3-D Secure challenge the buyer
+ * abandoned was exempt from both the multi-tenant scoping (FUT-556) and the
+ * basket binding (FUT-1213): it resumed over whatever checkout mounted next.
+ */
+export function handOverToChallenge(
+  order: CheckoutOrder,
+  url: string,
+  navigate: CheckoutNavigate,
+  scope: ChallengeScope = {},
+): 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.
+  const basket = parkedBasket(scope.basket);
+  rememberHostedOrder(order, {
+    ...(scope.tenantSlug ? { tenantSlug: scope.tenantSlug } : {}),
+    ...(basket === undefined ? {} : { basket }),
+    handoff: true,
+  });
+  navigate(url);
+}
+
+/**
+ * The refusal a charge answer carries, or nothing (FUT-1145).
+ *
+ * `undefined` for an outcome with neither field — an older server, a provider
+ * whose adapter classifies nothing — so the caller makes the same one-argument
+ * call it always did and every screen below behaves exactly as before.
+ */
+function declineOf(outcome: ChargeOutcome): CheckoutDecline | undefined {
+  const reason = outcome.declineReason;
+  const retriable = outcome.retriable;
+  if (reason === undefined && retriable === undefined) return undefined;
+  return {
+    ...(reason === undefined ? {} : { reason }),
+    ...(retriable === undefined ? {} : { retriable }),
+  };
+}
+
+/**
+ * Bubble a terminal status up, carrying the refusal when there is one.
+ *
+ * Called with ONE argument when the server said nothing new, so a host on an
+ * older mount produces exactly the call it always did.
+ */
+export function reportResolved(outcome: ChargeOutcome, onResolved: OnCheckoutResolved): void {
+  const refusal = declineOf(outcome);
+  if (refusal) onResolved(outcome.status, refusal);
+  else onResolved(outcome.status);
+}

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

@@ -11,8 +11,9 @@ import {
 import { useCheckoutCopy } from "./copy-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
 import { StalledWait } from "./stalled-wait";
+import type { CheckoutBasketIdentity } from "./basket";
 import type { CardChainLink } from "./method-capability";
-import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
+import type { BuyerInfo, CheckoutOrder, OnCheckoutResolved } from "./types";
 import { useCheckoutComponents } from "./ui";
 import { useCardCheckout, type CardCheckout } from "./use-card-checkout";
 
@@ -97,6 +98,40 @@ function ChargeFailure({
   );
 }
 
+/**
+ * What the buyer pays WITH: the saved cards they may reuse, and the form for a
+ * new one.
+ *
+ * The picker is absent when there is nothing saved, and the form is absent
+ * while a saved card is selected — so a buyer retrying a refused card (FUT-1145)
+ * lands on the form, because nothing is preselected for them.
+ */
+function CardInstrumentFields({ card }: { card: CardCheckout }): JSX.Element {
+  return (
+    <>
+      {card.savedCards.length > 0 ? (
+        <SavedCardsPicker
+          savedCards={card.savedCards}
+          selection={card.selection}
+          onSelect={card.setSelection}
+        />
+      ) : null}
+
+      {card.usingNewCard ? (
+        <NewCardForm
+          card={card.card}
+          fieldErrors={card.fieldErrors}
+          brand={card.brand}
+          saveCard={card.saveCard}
+          setCard={card.setCard}
+          setFieldErrors={card.setFieldErrors}
+          onSaveCardChange={card.setSaveCard}
+        />
+      ) : null}
+    </>
+  );
+}
+
 /**
  * Card payment view (FUT-58). Card data is validated + formatted client-side, then
  * tokenized (mock PagBank JS SDK) so the PAN never reaches our server; only the
@@ -115,6 +150,8 @@ export function CardView({
   tenantSlug,
   onResolved,
   pollIntervalMs = 2500,
+  freshInstrument = false,
+  basket,
 }: {
   order: CheckoutOrder;
   buyer?: BuyerInfo;
@@ -128,12 +165,33 @@ export function CardView({
   providerChain?: CardChainLink[];
   /** Scopes the saved-card list to cards the store's provider can charge. */
   tenantSlug?: string;
-  onResolved: (status: OrderStatus) => void;
+  onResolved: OnCheckoutResolved;
   pollIntervalMs?: number;
+  /**
+   * Preselect NOTHING from the saved list (FUT-1145): the buyer is back here
+   * because a card was refused, and the card this would otherwise choose for
+   * them is that one.
+   */
+  freshInstrument?: boolean;
+  /**
+   * WHICH basket this checkout is for (FUT-1213) — parked with the order when
+   * a 3-D Secure challenge sends the buyer to the provider's page.
+   */
+  basket?: CheckoutBasketIdentity;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.card;
-  const cc = useCardCheckout(order, buyer, providerConfig, onResolved, pollIntervalMs, tenantSlug, providerChain);
+  const cc = useCardCheckout(
+    order,
+    buyer,
+    providerConfig,
+    onResolved,
+    pollIntervalMs,
+    tenantSlug,
+    providerChain,
+    freshInstrument,
+    { tenantSlug, basket },
+  );
   // A charge NOBODY can confirm yet is not a decline (FUT-563). Some provider
   // may be holding the buyer's money, so it gets its own presentation: the
   // danger heading "Não foi possível pagar" contradicts the body's "não pague
@@ -150,25 +208,7 @@ export function CardView({
         {copy.heading}
       </Text>
 
-      {cc.savedCards.length > 0 ? (
-        <SavedCardsPicker
-          savedCards={cc.savedCards}
-          selection={cc.selection}
-          onSelect={cc.setSelection}
-        />
-      ) : null}
-
-      {cc.usingNewCard ? (
-        <NewCardForm
-          card={cc.card}
-          fieldErrors={cc.fieldErrors}
-          brand={cc.brand}
-          saveCard={cc.saveCard}
-          setCard={cc.setCard}
-          setFieldErrors={cc.setFieldErrors}
-          onSaveCardChange={cc.setSaveCard}
-        />
-      ) : null}
+      <CardInstrumentFields card={cc} />
 
       {cc.error ? <ChargeFailure message={cc.error} unresolved={unresolved} /> : null}
 

package/src/components/checkout/checkout-actions.ts

@@ -0,0 +1,341 @@
+import { useCallback, useEffect, useState, type Dispatch, type SetStateAction } from "react";
+
+import { buyerGateError } from "./buyer-gate";
+import type { CheckoutDecline } from "./decline";
+import { forgetHostedOrder, rememberHostedOrder } from "./hosted-return";
+import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
+import type { CheckoutNavigate } from "./navigate-context";
+import type { CheckoutScreensCopy } from "./screens-copy";
+import type {
+  BuyerContact,
+  BuyerField,
+  BuyerInfo,
+  CheckoutCustomerField,
+  CheckoutOrder,
+  CreateOrderRequest,
+  CreateOrderResult,
+  OrderStatus,
+  PaymentMethod,
+} from "./types";
+import { useResumeEffect, type HostedResume } from "./use-hosted-resume";
+
+/**
+ * The controller's own moving parts, one concern per hook.
+ *
+ * Split out of `./use-checkout-controller.ts` when the resumed leg grew a
+ * decision (FUT-1213), a general parked entry (FUT-1140) and a way out
+ * (FUT-1146) and that file's one exported function reached its size gate. The
+ * seam is the obvious one: everything here is state a step reads, and nothing
+ * here knows the ORDER the steps come in.
+ */
+
+/** Where the flow can be — the step ids, which are the flow's own contract. */
+export type Step = "dados" | "payment" | "status";
+
+/**
+ * The flow's navigation actions, split out of {@link useCheckoutController} for
+ * the 80-line per-function gate.
+ *
+ * `back` is where "the Dados step was skipped" has to be honoured: going back
+ * off Pagamento normally lands on Dados, but for a buyer with a CPF on file
+ * that step is not part of their flow, so the menu is the only honest
+ * destination — until they open it themselves via `editBuyer` ("alterar" on the
+ * payer block), after which it IS part of their flow and back returns to it.
+ */
+export function useCheckoutNav(
+  taxIdOnFile: boolean,
+  goToMenu: () => void,
+  setStep: Dispatch<SetStateAction<Step>>,
+): { back: () => void; editBuyer: (() => void) | undefined } {
+  const [dadosOpened, setDadosOpened] = useState(false);
+  const openDados = useCallback(() => {
+    setDadosOpened(true);
+    setStep("dados");
+  }, [setStep]);
+  const back = useCallback(() => {
+    setStep((current) => {
+      if (current === "payment" && (!taxIdOnFile || dadosOpened)) return "dados";
+      goToMenu();
+      return current;
+    });
+  }, [dadosOpened, goToMenu, setStep, taxIdOnFile]);
+  // Undefined unless Dados was skipped — the payer block keys off its presence,
+  // so the decision lives here rather than being re-derived by every caller.
+  return { back, editBuyer: taxIdOnFile ? openDados : undefined };
+}
+
+/**
+ * What the resumed leg contributes to the controller's surface.
+ *
+ * All of it is inert for a checkout that never left this tab and never raised
+ * anything: with nothing parked the poll is disabled, so the error stays null,
+ * the bound never elapses, and neither action has a wait to act on.
+ */
+export function resumeSurface(resume: HostedResume): {
+  resumeTimedOut: boolean;
+  resumeError: string | null;
+  resumeCheckAgain: () => void;
+  resumeRelease: (() => void) | undefined;
+  resumeReleasing: boolean;
+} {
+  return {
+    resumeTimedOut: resume.timedOut,
+    resumeError: resume.error,
+    resumeCheckAgain: resume.checkAgain,
+    resumeRelease: resume.release,
+    resumeReleasing: resume.releasing,
+  };
+}
+
+/**
+ * Open the flow on whatever was resumed, and close it again if the buyer
+ * releases the order (FUT-1140/FUT-1146).
+ *
+ * A LAYOUT effect, through `useResumeEffect`: the decision cannot be made
+ * during render (it waits for the host's cart), and an ordinary effect runs
+ * after paint — so a buyer coming back from a payment would see one frame of
+ * the Dados or Pagamento step before their confirmation replaced it.
+ */
+export function useResumedCheckout(
+  resume: HostedResume,
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>,
+  setStep: Dispatch<SetStateAction<Step>>,
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>,
+  setMethod: Dispatch<SetStateAction<PaymentMethod | null>>,
+): void {
+  const { order, step, released } = resume;
+  useResumeEffect(() => {
+    if (!order || !step) return;
+    setOrder(order);
+    setStep(step);
+    // The METHOD comes back with it, which matters for a resume that lands on
+    // the payment step: the picker keys off it, and a shopper looking at the
+    // PIX code they were already paying must not also be asked to choose how
+    // to pay. Set through the raw setter on purpose — the public `setMethod`
+    // drops the order on a change, which is the opposite of resuming one.
+    setMethod(order.method);
+  }, [order, step, setOrder, setStep, setMethod]);
+  useResumeEffect(() => {
+    if (!released) return;
+    // Back to a checkout they can actually use, with the basket they are
+    // holding. The order they released is gone from this screen; whether it is
+    // gone at the provider is the server's answer, not ours.
+    setOrder(null);
+    setFinalStatus(null);
+    setStep("payment");
+  }, [released, setOrder, setStep, setFinalStatus]);
+}
+
+/**
+ * The end of a checkout: tell the host, and let the parked entry go.
+ *
+ * PAID fires the host's `onPaid` port. FUT-601 made the SERVER empty the cart
+ * inside the confirmation transaction — but nothing told the SPA, whose cart
+ * provider survives every checkout route change and kept counting the items the
+ * buyer had just bought. A FAILED or EXPIRED order fires nothing: that shopper
+ * still has a basket to retry with, and the host must not be told otherwise.
+ *
+ * The parked entry is dropped on ANY terminal status (FUT-1140). It exists to
+ * carry one payment across a torn-down SPA; once that payment has an answer,
+ * resuming it could only re-show an outcome the buyer has already been given.
+ */
+export function useSettledPort(settled: OrderStatus | null, onPaid: (() => void) | undefined): void {
+  useEffect(() => {
+    if (!settled || settled === "AWAITING_PAYMENT") return;
+    forgetHostedOrder();
+    if (settled === "PAID") onPaid?.();
+  }, [settled, onPaid]);
+}
+
+/**
+ * The create-order refusal the steps render: what to say, which field to
+ * highlight, and the machine CODE that decides how it is presented — an
+ * unresolved charge is not a failed one, and the Pagamento step must not offer
+ * it a "Tentar novamente" (FUT-563). One hook so the three always move
+ * together; they were three `useState`s that could be cleared apart.
+ */
+export function useCreateFailure() {
+  const [message, setMessage] = useState<string | null>(null);
+  const [field, setField] = useState<BuyerField | null>(null);
+  const [code, setCode] = useState<string | null>(null);
+  const clear = useCallback(() => {
+    setMessage(null);
+    setField(null);
+    setCode(null);
+  }, []);
+  const fail = useCallback(
+    (next: { message: string; field?: BuyerField | null; code?: string }) => {
+      setMessage(next.message);
+      setField(next.field ?? null);
+      setCode(next.code ?? null);
+    },
+    [],
+  );
+  return { message, field, code, clear, fail };
+}
+
+
+/**
+ * "Continuar" on the Dados step: gate on what the store's chain demands, then
+ * PERSIST the buyer's details before advancing.
+ *
+ * The write happens HERE and not when a payment is raised, because everything
+ * after this step can fail — no provider configured, a declined card, an
+ * abandoned PIX, a closed tab — and the details must survive all of it.
+ * Fire-and-forget on purpose: making the buyer wait on the write, or blocking
+ * them when it fails, would trade the bug for a worse one. Gated on the
+ * "salvar meus dados" consent (LGPD), which is what the checkbox means.
+ */
+export function useGoToPayment(input: {
+  buyer: BuyerInfo;
+  buyerFields: readonly CheckoutCustomerField[];
+  taxIdOnFile: boolean;
+  saveProfile: boolean;
+  saveBuyerContact: ((contact: BuyerContact) => void) | undefined;
+  validation: CheckoutScreensCopy["validation"];
+  failure: { clear: () => void; fail: (next: { message: string; field?: BuyerField | null }) => void };
+  setStep: Dispatch<SetStateAction<Step>>;
+}): () => void {
+  const { buyer, buyerFields, taxIdOnFile, saveProfile, saveBuyerContact } = input;
+  const { validation, failure, setStep } = input;
+  return useCallback(() => {
+    failure.clear();
+    const complaint = buyerGateError(validation, buyer, buyerFields, taxIdOnFile);
+    if (complaint) {
+      failure.fail(complaint);
+      return;
+    }
+    if (saveProfile) {
+      saveBuyerContact?.({ name: buyer.name, phone: buyer.phone, taxId: buyer.taxId });
+    }
+    setStep("payment");
+  }, [buyer, buyerFields, saveProfile, taxIdOnFile, failure, saveBuyerContact, validation, setStep]);
+}
+
+/**
+ * "Tentar novamente" after a refusal — and WHICH order it goes against.
+ *
+ * A RETRIABLE decline keeps the order (FUT-1145). Minting a new one for every
+ * refused card leaves a trail of failed orders in the buyer's own history for
+ * one purchase they are still trying to make, and the money rule is unchanged
+ * either way: the server refuses a second charge on a payable it has already
+ * settled. `freshInstrument` is the other half — the saved card that just
+ * failed is not chosen for them again.
+ */
+export function useRetryAction(input: {
+  decline: CheckoutDecline | null;
+  order: CheckoutOrder | null;
+  clearError: () => void;
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+  setStep: Dispatch<SetStateAction<Step>>;
+  setFreshInstrument: Dispatch<SetStateAction<boolean>>;
+}): () => void {
+  const { decline, order, clearError, setOrder, setDecline } = input;
+  const { setFinalStatus, setStep, setFreshInstrument } = input;
+  return useCallback(() => {
+    setFinalStatus(null);
+    clearError();
+    setStep("payment");
+    if (decline?.retriable && order) {
+      setFreshInstrument(true);
+      return;
+    }
+    setOrder(null);
+    setDecline(null);
+    forgetHostedOrder();
+  }, [
+    clearError, decline, order, setDecline, setFinalStatus, setFreshInstrument, setOrder, setStep,
+  ]);
+}
+
+/**
+ * Hand the buyer to a redirect provider's own page, if that is where this
+ * charge settles (FUT-556).
+ *
+ * Called BEFORE the order is stored: storing it first would render the PIX or
+ * card step for a provider that returned neither, which is the dead end this
+ * fixes.
+ *
+ * A full navigation rather than the host's router, because the destination is
+ * another origin. The return trip comes back to this same checkout route
+ * carrying `transaction_nsu` + `slug`, which the status poll already reads.
+ *
+ * @returns true when the buyer is on their way and the caller must stop.
+ */
+function handOverToProvider(
+  order: CheckoutOrder,
+  navigate: CheckoutNavigate,
+  tenantSlug?: string,
+  basket?: CheckoutBasketIdentity,
+): boolean {
+  if (!order.hostedCheckoutUrl) return false;
+  // PARK FIRST, navigate second. The order is the only thing the return trip
+  // has to rehydrate from, and the navigation may tear this SPA down before
+  // any later write lands.
+  //
+  // The STORE goes with it: one tab holds one slot, and on a multi-tenant
+  // storefront every store shares an origin. Without the slug, abandoning this
+  // hand-off and opening another store's checkout resumed THIS order there.
+  //
+  // So does the BASKET (FUT-1213): a hand-off nobody completed must not resume
+  // itself over the shopper's next basket, and the only way to tell the two
+  // apart later is to record which basket this one was raised from.
+  rememberHostedOrder(order, {
+    tenantSlug,
+    basket: parkedBasket(basket),
+    handoff: true,
+  });
+  navigate(order.hostedCheckoutUrl);
+  return true;
+}
+
+/**
+ * Raise the order for a chosen method, and decide what happens to it.
+ *
+ * Three outcomes, in order: a refusal the step renders, a HAND-OFF that leaves
+ * this page for the provider's own, and an order raised here.
+ */
+export function useStartPayment(input: {
+  buyer: BuyerInfo;
+  saveProfile: boolean;
+  createOrder: (request: CreateOrderRequest) => Promise<CreateOrderResult>;
+  navigate: CheckoutNavigate;
+  tenantSlug: string | undefined;
+  basket: CheckoutBasketIdentity | undefined;
+  failure: { clear: () => void; fail: (next: { message: string; field?: BuyerField | null; code?: string }) => void };
+  setCreating: Dispatch<SetStateAction<boolean>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+}): (chosen: PaymentMethod, override?: BuyerInfo) => Promise<void> {
+  const { buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure } = input;
+  const { setCreating, setDecline, setOrder, setFinalStatus } = input;
+  return useCallback(
+    async (chosen: PaymentMethod, override?: BuyerInfo) => {
+      failure.clear();
+      setDecline(null);
+      setCreating(true);
+      const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
+      setCreating(false);
+      if (!result.ok) {
+        failure.fail(result.error);
+        return;
+      }
+      if (handOverToProvider(result.data, navigate, tenantSlug, basket)) return;
+      // PARKED EVEN THOUGH NOBODY IS LEAVING (FUT-1140). A low-memory phone
+      // discards this tab while the shopper is in their bank app, and the SPA
+      // that comes back has never heard of the order it raised — so the buyer
+      // meets an empty cart and a retry button instead of the confirmation for
+      // the payment they just made.
+      rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
+      setOrder(result.data);
+      setFinalStatus(null);
+    },
+    [
+      buyer, saveProfile, createOrder, failure, navigate, tenantSlug, basket,
+      setCreating, setDecline, setOrder, setFinalStatus,
+    ],
+  );
+}