@12-apps/payments-frontend 1.7.1 → 1.8.1

package/src/components/checkout/transport.ts

@@ -0,0 +1,191 @@
+/**
+ * The checkout's HTTP transport, as a bound client (FUT-741).
+ *
+ * Everything `client.ts` used to do with a hard-coded prefix and the ambient
+ * `fetch` now lives here behind {@link createCheckoutClient}, so the same five
+ * calls can be pointed at a different mount, carry a host's auth headers, or —
+ * the reason this exists — be driven through an injected `fetch` that routes
+ * straight into a real `createPaymentFlowsBE` mount. A story or a harness page
+ * can then exercise the WIRE rather than a mock of our own client, which is the
+ * only place the FUT-740 review found its three criticals.
+ *
+ * `baseUrl` defaults to `/api/checkout` VERBATIM — not normalized, not
+ * re-derived. The published client already posts those exact paths, and both
+ * pinned wire suites drive them; a prefix that is "cleaned up" here breaks the
+ * shipped contract in the same release that introduces the factory.
+ */
+
+import type { SavedCard } from "../../card";
+import { err, ok, type Result } from "../../result";
+
+import type {
+  ChargeCardInput,
+  ChargeOutcome,
+  CheckoutProviderConfig,
+  OrderStatus,
+} from "./types";
+
+/**
+ * The prefix every shipped buyer checkout posts to today. Exported so a host
+ * (or a test) can state it rather than re-type it, and so a change to it is a
+ * change to one named constant with this comment attached.
+ */
+export const DEFAULT_CHECKOUT_BASE_URL = "/api/checkout";
+
+/** Where the `createPaymentFlowsBE` mount lives, and how to reach it. */
+export interface CheckoutTransport {
+  /** Prefix for `/config`, `/status`, `/charge`, `/cards`, `/refresh-key`. */
+  baseUrl?: string;
+  /**
+   * The `fetch` to call. Omitted ⇒ the ambient one, resolved PER CALL so a
+   * suite that stubs the global after the client was built still sees its stub.
+   */
+  fetchImpl?: typeof fetch;
+  /** Extra headers per request (a bearer token, a tenant header). */
+  headers?: () => HeadersInit | Promise<HeadersInit>;
+}
+
+/** The five 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>>;
+  charge(input: ChargeCardInput): Promise<Result<ChargeOutcome>>;
+  listInstruments(tenantSlug?: string): Promise<SavedCard[]>;
+  refreshBrowserKey(input: { orderId: string }): Promise<Result<{ publicKey: string | null }>>;
+}
+
+/** Envelope the API routes return: `{ data }` on success, `{ error }` on failure. */
+interface ApiEnvelope<T> {
+  data?: T;
+  error?: string;
+  /**
+   * Stable machine code for the failure (`checkoutErrorResponse` always sends
+   * one). Carried through so a surface can PRESENT a refusal for what it is —
+   * an unresolved charge is not a decline, and rendering it under "não foi
+   * possível pagar" with a live pay button invites the second payment its own
+   * text forbids.
+   */
+  code?: string;
+}
+
+/**
+ * A non-2xx envelope as a {@link Result} failure, carrying its machine CODE.
+ * The message is what the buyer reads; the code is what a surface uses to
+ * decide how to PRESENT it, which a message cannot be parsed for.
+ */
+function refused<T>(json: ApiEnvelope<T> | null): Result<T> {
+  return err(json?.error ?? "Não foi possível concluir a operação. Tente novamente.", json?.code);
+}
+
+/**
+ * What a hosted checkout appended to the return URL when it sent the buyer
+ * back, or undefined.
+ *
+ * InfinitePay's `payment_check` refuses to confirm without BOTH the
+ * `transaction_nsu` and the invoice `slug`, and neither exists until somebody
+ * has actually paid — they arrive here, on the redirect. Left in the URL: the
+ * server treats them as hints, so re-sending them on later polls is harmless.
+ *
+ * Note the buyer has to press "Continuar" on the provider's receipt for this
+ * redirect to happen at all, which is exactly why it is a hint and never the
+ * mechanism: the webhook, and the server-side reconciliation behind it, are
+ * what must work when they simply close the tab.
+ */
+function returnedSettlement(): Record<string, string> {
+  if (typeof window === "undefined") return {};
+  const params = new URLSearchParams(window.location.search);
+  // BOTH. Measured against the live API: handle + order_nsu +
+  // transaction_nsu + slug answers {"success":true,"paid":true,…}, and the
+  // same call missing EITHER answers {"success":false}. Neither exists before
+  // the payment, and the slug is not in the link-creation response — the
+  // redirect and the webhook are the only places both appear together.
+  const transactionNsu = params.get("transaction_nsu") ?? params.get("transaction_id") ?? "";
+  const slug = params.get("slug") ?? "";
+  return {
+    ...(transactionNsu ? { transactionNsu } : {}),
+    ...(slug ? { slug } : {}),
+  };
+}
+
+/** The ambient `fetch`, wrapped so it is never invoked detached from its global. */
+function ambientFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  return globalThis.fetch(input, init);
+}
+
+/**
+ * The five checkout calls, bound to one transport.
+ *
+ * Passing no transport reproduces exactly what the free functions in
+ * `client.ts` have always done: `/api/checkout/**` on the ambient `fetch`.
+ */
+export function createCheckoutClient(transport: CheckoutTransport = {}): CheckoutClient {
+  const baseUrl = transport.baseUrl ?? DEFAULT_CHECKOUT_BASE_URL;
+
+  /** Call a checkout route and normalize the response into a {@link Result}. */
+  async function call<T>(route: string, init?: RequestInit): Promise<Result<T>> {
+    // Resolved here, not captured at build time: a suite (or a story) that
+    // replaces the global afterwards must still be the one that answers.
+    const doFetch = transport.fetchImpl ?? ambientFetch;
+    try {
+      const extra = transport.headers ? await transport.headers() : undefined;
+      const res = await doFetch(`${baseUrl}${route}`, {
+        ...init,
+        headers: { "Content-Type": "application/json", ...extra, ...init?.headers },
+      });
+      const json = (await res.json().catch(() => null)) as ApiEnvelope<T> | null;
+      if (!res.ok) return refused(json);
+      if (!json || json.data === undefined) {
+        return err(json?.error ?? "Resposta inválida do servidor.");
+      }
+      return ok(json.data);
+    } catch {
+      return err("Não foi possível conectar. Verifique sua conexão e tente novamente.");
+    }
+  }
+
+  return {
+    getConfig: (tenantSlug) =>
+      call<CheckoutProviderConfig>(`/config?tenantSlug=${encodeURIComponent(tenantSlug)}`, {
+        method: "GET",
+      }),
+
+    getStatus: (ref) =>
+      call<OrderStatus>(
+        `/status?${new URLSearchParams({ orderId: ref, ...returnedSettlement() }).toString()}`,
+        { method: "GET" },
+      ),
+
+    charge: (input) =>
+      call<ChargeOutcome>("/charge", {
+        method: "POST",
+        // The FLAT body the shipped client has always sent. Pinned from both
+        // ends by `charge-wire.contract.test.ts`; nothing here may re-nest it.
+        body: JSON.stringify({
+          orderId: input.orderId,
+          token: input.token,
+          // One instrument per provider (FUT-563) — the server hands each
+          // provider in the chain its own, which is what lets a card charge
+          // fail over.
+          ...(input.tokensByProvider ? { tokensByProvider: input.tokensByProvider } : {}),
+          saveCard: input.saveCard,
+          cardMeta: input.cardMeta,
+          taxId: input.taxId,
+        }),
+      }),
+
+    listInstruments: async (tenantSlug) => {
+      // Scoped to the store when known (FUT-697): only cards the store's ACTIVE
+      // provider can actually charge come back — a PagBank-vaulted card is not
+      // offered for a Stone charge it would fail (or misroute).
+      const query = tenantSlug ? `?tenantSlug=${encodeURIComponent(tenantSlug)}` : "";
+      const result = await call<SavedCard[]>(`/cards${query}`, { method: "GET" });
+      return result.ok ? result.data : [];
+    },
+
+    refreshBrowserKey: (input) =>
+      call<{ publicKey: string | null }>("/refresh-key", {
+        method: "POST",
+        body: JSON.stringify({ orderId: input.orderId }),
+      }),
+  };
+}

package/src/components/checkout/types.ts

@@ -198,6 +198,17 @@ export interface ChargeCardInput {
   taxId?: string;
 }
 
+/** A buyer field a provider asks for, as `/config` publishes it (FUT-595). */
+export interface CheckoutCustomerField {
+  key: "name" | "email" | "taxId" | "phone";
+  /** Which validation rule applies. `MOBILE` is the strictly narrower `PHONE`. */
+  type: "NAME" | "EMAIL" | "PHONE" | "MOBILE" | "CPF";
+  /** The provider refuses (or its own page stalls) without this field. */
+  required: boolean;
+  /** Methods this spec applies to; omitted means every method the adapter takes. */
+  methods?: ("PIX" | "CARD" | "BOLETO")[];
+}
+
 /**
  * ONE enabled provider of the store's chain (FUT-563), as the buyer's config
  * answers it. The same protocol facts as the head, stated per provider —
@@ -209,6 +220,22 @@ export interface CheckoutChainLink {
   publicKey: string | null;
   mockTokenization: boolean;
   methods: ("PIX" | "CARD" | "BOLETO")[];
+  /**
+   * What this provider needs to know about the buyer (FUT-595).
+   *
+   * `GET /api/checkout/config` has published this since FUT-740; this mirror
+   * type simply dropped it, so the buyer form could not be honest about what
+   * the chain requires and a missing field was only discoverable as a 400 AFTER
+   * the buyer had finished filling it in — the third FUT-740 critical, one
+   * layer up.
+   *
+   * Optional, and the DEGRADE DIRECTION IS LOAD-BEARING: absent (an older host,
+   * a hand-written config) must mean today's behaviour — CPF required — never
+   * "this chain asks for nothing". Asking for nothing produces a form the buyer
+   * completes and a charge the server then refuses for a document they were
+   * never shown a field for.
+   */
+  customerSchema?: CheckoutCustomerField[];
 }
 
 /**

package/src/components/checkout/ui.tsx

@@ -145,7 +145,18 @@ const CheckoutComponentsContext = createContext<CheckoutComponents>(defaultCheck
 /**
  * Fills the checkout's component slots for everything rendered beneath it.
  * Partial on purpose: a host overrides only the slots its design system
- * covers and inherits the raw-MUI default for the rest.
+ * covers and inherits the rest.
+ *
+ * Inherits from the NEAREST provider above, not from the raw-MUI defaults.
+ * That distinction is the whole contract once these nest — and they do nest:
+ * `createPaymentFlows` fills the slots once at the factory, and the
+ * `CheckoutFlow` inside its mount opens a provider of its own. Merging over
+ * the defaults there re-imposed raw MUI on a host that had already stated its
+ * design system, silently, one level in. Merging over the inherited set makes
+ * a nested provider ADD to what is above it, which is what "partial" has to
+ * mean for the surface to agree with itself. The context's own default is
+ * still `defaultCheckoutComponents`, so the outermost provider is unchanged:
+ * an unfilled slot is raw MUI exactly as before.
  */
 export function CheckoutComponentsProvider({
   components,
@@ -154,9 +165,10 @@ export function CheckoutComponentsProvider({
   components?: Partial<CheckoutComponents>;
   children: ReactNode;
 }): JSX.Element {
+  const inherited = useCheckoutComponents();
   const value = useMemo<CheckoutComponents>(
-    () => ({ ...defaultCheckoutComponents, ...components }),
-    [components],
+    () => ({ ...inherited, ...components }),
+    [inherited, components],
   );
   return (
     <CheckoutComponentsContext.Provider value={value}>

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

@@ -17,13 +17,14 @@ import {
 } from "../../card";
 import { ok, type Result } from "../../result";
 
-import { resolveNewCardToken, type CardInstruments } from "./card-instruments";
 import {
-  chargeCard,
-  listSavedCards,
-  refreshCardPublicKey,
-} from "./client";
+  resolveNewCardToken,
+  type CardInstruments,
+  type RefreshBrowserKey,
+} from "./card-instruments";
+import { useCheckoutClientApi } from "./client-context";
 import { rememberHostedOrder } from "./hosted-return";
+import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
 import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
 import { usePaymentPolling } from "./use-payment-polling";
@@ -43,10 +44,11 @@ function useSavedCards(tenantSlug: string | undefined): {
 } {
   const [savedCards, setSavedCards] = useState<SavedCard[]>([]);
   const [selection, setSelection] = useState<string>(NEW_CARD);
+  const client = useCheckoutClientApi();
 
   useEffect(() => {
     let active = true;
-    void listSavedCards(tenantSlug).then((cards) => {
+    void client.listInstruments(tenantSlug).then((cards) => {
       if (!active) return;
       setSavedCards(cards);
       const first = cards[0];
@@ -55,7 +57,7 @@ function useSavedCards(tenantSlug: string | undefined): {
     return () => {
       active = false;
     };
-  }, [tenantSlug]);
+  }, [tenantSlug, client]);
 
   return { savedCards, selection, setSelection };
 }
@@ -76,19 +78,20 @@ function useCardPublicKey(
   setPublicKey: (key: string) => void;
 } {
   const [publicKey, setPublicKey] = useState<string | null>(config.publicKey);
+  const client = useCheckoutClientApi();
   const refreshable =
     config.provider !== null && tokenizerFor(config.provider) === "pagbank-sdk";
 
   useEffect(() => {
     if (config.publicKey !== null || !refreshable) return undefined;
     let active = true;
-    void refreshCardPublicKey({ orderId }).then((result) => {
+    void client.refreshBrowserKey({ orderId }).then((result) => {
       if (active && result.ok && result.data.publicKey) setPublicKey(result.data.publicKey);
     });
     return () => {
       active = false;
     };
-  }, [orderId, config.publicKey, refreshable]);
+  }, [orderId, config.publicKey, refreshable, client]);
 
   return { publicKey, setPublicKey };
 }
@@ -151,9 +154,16 @@ const CARD_AWAITING_POLL_CAP = 36;
  * 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): void {
+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);
-  window.location.assign(url);
+  navigate(url);
 }
 
 /** The buyer's card is invalid — block the submit and show which field. */
@@ -178,6 +188,8 @@ async function resolveInstruments(input: {
   config: CardTokenizationConfig;
   onKeyRefreshed: (key: string) => void;
   providerChain: readonly CardChainLink[];
+  /** The bound key-refresh call (FUT-741) — the self-heal must hit OUR mount. */
+  refreshKey: RefreshBrowserKey;
 }): Promise<Result<CardInstruments>> {
   const { form } = input;
   if (!form.usingNewCard) return ok({ token: form.selection });
@@ -188,6 +200,8 @@ async function resolveInstruments(input: {
     input.onKeyRefreshed,
     form.saveCard,
     input.providerChain,
+    undefined,
+    input.refreshKey,
   );
 }
 
@@ -212,6 +226,8 @@ function useCardSubmit(
   // The active key: resolved by the checkout config, overridden by the
   // rotated-key self-heal for the rest of the session.
   const { publicKey, setPublicKey } = useCardPublicKey(order.orderId, providerConfig);
+  const client = useCheckoutClientApi();
+  const navigate = useCheckoutNavigate();
 
   const { status, error: pollError, timedOut: pollTimedOut } = usePaymentPolling(order.orderId, {
     enabled: submitted,
@@ -235,6 +251,7 @@ function useCardSubmit(
       config: { ...providerConfig, publicKey },
       onKeyRefreshed: setPublicKey,
       providerChain,
+      refreshKey: client.refreshBrowserKey,
     });
     if (!resolved.ok) {
       setError(resolved.error);
@@ -242,7 +259,7 @@ function useCardSubmit(
       return;
     }
 
-    const charged = await chargeCard({
+    const charged = await client.charge({
       orderId: order.orderId,
       token: resolved.data.token,
       tokensByProvider: resolved.data.tokensByProvider,
@@ -261,7 +278,7 @@ 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);
+      return handOverToChallenge(order, charged.data.hostedCheckoutUrl, navigate);
     }
     // A business outcome (e.g. declined → FAILED) shows the status screen;
     // an accepted charge begins polling for the async confirmation.

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

@@ -1,14 +1,16 @@
 import { useCallback, useEffect, useMemo, useState, type Dispatch, type SetStateAction } from "react";
 
-import { validateCpf } from "../../card";
+import { buyerFormComplete } from "./buyer-info-form";
 
 import { rememberHostedOrder, takeHostedOrder } from "./hosted-return";
+import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
 import type {
   BuyerContact,
   BuyerField,
   BuyerInfo,
   CheckoutOrder,
   CreateOrderRequest,
+  CheckoutCustomerField,
   CreateOrderResult,
   OrderStatus,
   PaymentMethod,
@@ -19,6 +21,11 @@ type Step = "dados" | "payment" | "status";
 
 const STEP_ORDER: Step[] = ["dados", "payment", "status"];
 
+/** The pre-FUT-595 demand, and the safe reading of a chain that declared none. */
+const CPF_ONLY: readonly CheckoutCustomerField[] = [
+  { key: "taxId", type: "CPF", required: true },
+];
+
 /**
  * Everything the flow needs FROM its host, as explicit ports (FUT-564). The
  * package owns the payment surface; the host owns the cart, the catalog,
@@ -81,19 +88,49 @@ function useCheckoutNav(
   return { back, editBuyer: taxIdOnFile ? openDados : undefined };
 }
 
+/** The message shown when a declared field is missing or malformed. */
+const FIELD_COMPLAINT: Record<string, string> = {
+  taxId: "CPF inválido.",
+  name: "Informe seu nome.",
+  email: "E-mail inválido.",
+  phone: "Telefone inválido.",
+};
+
+/** Which input to highlight for a declared key. */
+const FIELD_INPUT: Record<string, BuyerField> = {
+  taxId: "cpf",
+  name: "name",
+  email: "email",
+  phone: "phone",
+};
+
 /**
- * What the "Continuar" gate objects to about the CPF, or undefined to advance.
+ * What the "Continuar" gate objects to, or undefined to advance.
  *
- * A blank field is only an error when the store has NO CPF for this buyer. With
+ * The fields come from the chain's own declaration (FUT-595) — absent, they
+ * degrade to CPF-required, which is exactly what this gate has always demanded.
+ *
+ * A blank CPF is only an error when the store has NO CPF for this buyer. With
  * one on file the field starts empty by design (the client is never sent the
  * saved CPF), so demanding one here trapped a returning buyer who opened Dados
  * through "Alterar" and changed their mind: they could not reach Pagamento
  * again, and back only led out to the menu. Leaving it blank means "charge me
  * as before", which is exactly what the server's `resolveBuyerTaxId` does.
  */
-function cpfGateError(typed: string, taxIdOnFile: boolean): string | undefined {
-  if (!typed && taxIdOnFile) return undefined;
-  return validateCpf(typed);
+function buyerGateError(
+  buyer: BuyerInfo,
+  fields: readonly CheckoutCustomerField[],
+  taxIdOnFile: boolean,
+): { message: string; field: BuyerField } | undefined {
+  const effective = taxIdOnFile
+    ? fields.filter((field) => !(field.key === "taxId" && !buyer.taxId?.trim()))
+    : fields;
+  const offending = buyerFormComplete(buyer, effective);
+  if (!offending) return undefined;
+  return {
+    message: FIELD_COMPLAINT[offending.key] ?? "Campo obrigatório.",
+    field: FIELD_INPUT[offending.key] ?? "cpf",
+  };
 }
 
 /**
@@ -119,10 +156,13 @@ function initialStep(resuming: boolean, taxIdOnFile: boolean): Step {
  *
  * @returns true when the buyer is on their way and the caller must stop.
  */
-function handOverToProvider(order: CheckoutOrder): boolean {
+function handOverToProvider(order: CheckoutOrder, navigate: CheckoutNavigate): 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.
   rememberHostedOrder(order);
-  window.location.assign(order.hostedCheckoutUrl);
+  navigate(order.hostedCheckoutUrl);
   return true;
 }
 
@@ -197,20 +237,24 @@ function useCreateFailure() {
  *   being saved.
  * - `startPayment` raises the order (PIX → QR, CARD → chargeable); `payWithEmail`
  *   re-raises with a corrected e-mail for the merchant-email rejection.
+ *
+ * @param taxIdOnFile The buyer already has a CPF saved (FUT-465) ⇒ the Dados
+ *   step has nothing left to ask, so checkout opens on Pagamento and `back`
+ *   goes to the menu rather than to a form the buyer never saw. The CPF itself
+ *   is never in the client's hands — the server reads it from the encrypted
+ *   profile when the charge is raised.
+ * @param buyerFields What the store's chain declares it needs from the buyer
+ *   (FUT-595). Absent ⇒ CPF-required, which is what this gate demanded before
+ *   there was a declaration to read — never "ask nothing".
  */
 export function useCheckoutController(
   ports: CheckoutHostPorts,
   defaultBuyer?: BuyerInfo,
-  /**
-   * The buyer already has a CPF saved (FUT-465) ⇒ the Dados step has nothing
-   * left to ask, so checkout opens on Pagamento and `back` goes to the menu
-   * rather than to a form the buyer never saw. The CPF itself is never in the
-   * client's hands — the server reads it from the encrypted profile when the
-   * charge is raised.
-   */
   taxIdOnFile = false,
+  buyerFields: readonly CheckoutCustomerField[] = CPF_ONLY,
 ) {
   const { createOrder, saveBuyerContact, onExitToMenu, onPaid } = ports;
+  const navigate = useCheckoutNavigate();
   const resume = useHostedResume();
   const [step, setStep] = useState<Step>(initialStep(Boolean(resume.order), taxIdOnFile));
   // No method pre-selected: the Pagamento step shows just the picker until the
@@ -232,8 +276,8 @@ export function useCheckoutController(
   }, [clearError]);
   const goToPayment = useCallback(() => {
     clearError();
-    const cpfError = cpfGateError(buyer.taxId?.trim() ?? "", taxIdOnFile);
-    if (cpfError) { failure.fail({ message: cpfError, field: "cpf" }); return; }
+    const complaint = buyerGateError(buyer, buyerFields, taxIdOnFile);
+    if (complaint) { failure.fail(complaint); return; }
     // Persist the buyer's details HERE, on "Continuar" — not when a payment is
     // raised. Everything after this step can fail (no provider configured, a
     // declined card, an abandoned PIX, a closed tab) and the details must
@@ -245,17 +289,17 @@ export function useCheckoutController(
       saveBuyerContact?.({ name: buyer.name, phone: buyer.phone, taxId: buyer.taxId });
     }
     setStep("payment");
-  }, [buyer.name, buyer.phone, buyer.taxId, saveProfile, taxIdOnFile, clearError, saveBuyerContact]);
+  }, [buyer, buyerFields, saveProfile, taxIdOnFile, clearError, saveBuyerContact]);
   const startPayment = useCallback(async (chosen: PaymentMethod, override?: BuyerInfo) => {
     clearError();
     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)) return;
+    if (handOverToProvider(result.data, navigate)) return;
     setOrder(result.data);
     setFinalStatus(null);
-  }, [buyer, saveProfile, createOrder, clearError]);
+  }, [buyer, saveProfile, createOrder, clearError, navigate]);
   const payWithEmail = useCallback((email: string) => {
     if (!method) return;
     const next = { ...buyer, email };

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

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 
-import { pollOrderStatus } from "./client";
+import { useCheckoutClientApi } from "./client-context";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
 interface PollingOptions {
@@ -34,6 +34,10 @@ export function usePaymentPolling(
   const [status, setStatus] = useState<OrderStatus | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [timedOut, setTimedOut] = useState(false);
+  // 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.
+  const client = useCheckoutClientApi();
 
   useEffect(() => {
     if (!orderId || !enabled) {
@@ -48,7 +52,7 @@ export function usePaymentPolling(
     setError(null);
 
     const tick = async (): Promise<void> => {
-      const result = await pollOrderStatus(orderId);
+      const result = await client.getStatus(orderId);
       if (cancelled) {
         return;
       }
@@ -87,7 +91,7 @@ export function usePaymentPolling(
         clearTimeout(timer);
       }
     };
-  }, [orderId, intervalMs, enabled, maxHealthyPolls]);
+  }, [orderId, intervalMs, enabled, maxHealthyPolls, client]);
 
   return { status, error, timedOut };
 }

package/src/flows/copy.ts

@@ -0,0 +1,57 @@
+/**
+ * The sentences `createPaymentFlows` renders on its OWN screens (FUT-741).
+ *
+ * Scope is deliberately narrow and stated rather than implied: this covers the
+ * copy the FACTORY owns — the unavailable screen's two remedies, the hosted
+ * handover and its fallback link, the empty cart, and the buyer form's continue
+ * action. The screens that already carried their own product copy before this
+ * ticket (PIX, card, status) keep it; moving all of it here in the same change
+ * that introduces the factory would be a copy rewrite disguised as an API.
+ *
+ * Every default below is today's pt-BR, verbatim — a host that passes no `copy`
+ * reads exactly what a buyer reads now.
+ */
+
+/** Every buyer-facing string the factory's own screens render. */
+export interface CheckoutCopyFE {
+  /** No provider connected AND no host remedy: the store simply does not charge. */
+  unavailableTitle: string;
+  unavailableBody: string;
+  /** No provider connected but the host offers a remedy (this repo: the waiter). */
+  unavailableWithRemedyTitle: string;
+  unavailableWithRemedyBody: string;
+  /** The hosted handover interstitial, and the link that is its fallback. */
+  handoffTitle: string;
+  handoffBody: string;
+  handoffLink: string;
+  handoffCancel: string;
+  /** The return leg, while the parked order is polled to a terminal state. */
+  returnPending: string;
+  /** The return leg when nothing was parked — the buyer came back to nothing. */
+  returnUnknown: string;
+  /** Nothing to check out (cart mode only). */
+  emptyCartTitle: string;
+  emptyCartAction: string;
+  /** The Dados step's primary action. */
+  continueAction: string;
+}
+
+export const DEFAULT_CHECKOUT_COPY_FE: CheckoutCopyFE = {
+  unavailableTitle: "Pagamento online indisponível",
+  unavailableBody:
+    "Esta loja não recebe pagamentos pelo site. Combine o pagamento diretamente com a loja para concluir seu pedido.",
+  unavailableWithRemedyTitle: "Pagamento com o garçom",
+  unavailableWithRemedyBody:
+    "Esta loja não recebe pagamentos pelo site. Chame o garçom para fechar a conta na mesa.",
+  handoffTitle: "Você será levado ao pagamento",
+  handoffBody:
+    "Estamos abrindo a página segura do meio de pagamento. Se ela não abrir sozinha, use o link abaixo.",
+  handoffLink: "Abrir a página de pagamento",
+  handoffCancel: "Voltar",
+  returnPending: "Confirmando seu pagamento…",
+  returnUnknown:
+    "Não encontramos um pagamento em andamento nesta sessão. Verifique seus pedidos em instantes.",
+  emptyCartTitle: "Seu carrinho está vazio.",
+  emptyCartAction: "Ver cardápio",
+  continueAction: "Continuar",
+};