@12-apps/payments-frontend 1.7.0 → 1.8.0

package/src/components/checkout/checkout-steps.tsx

@@ -9,6 +9,7 @@ import {
   cardPathAvailable,
   cardTokenization,
   offeredMethods,
+  selectableMethods,
   usePreselectSoleMethod,
 } from "./method-capability";
 import { MethodPicker } from "./method-picker";
@@ -18,6 +19,7 @@ import { PixView } from "./pix-view";
 import type {
   BuyerField,
   BuyerInfo,
+  CheckoutCustomerField,
   CheckoutOrder,
   CheckoutProviderConfig,
   OrderStatus,
@@ -155,6 +157,7 @@ export function DadosStep({
   errorField,
   onContinue,
   cartTotals,
+  buyerFields,
   discountLines,
   totalOverride,
 }: {
@@ -167,6 +170,8 @@ export function DadosStep({
   onContinue: () => void;
   /** The host cart's own totals — what the pay bar shows in cart mode. */
   cartTotals: { totalLabel: string; totalItems: number };
+  /** What the store's chain declares it needs (FUT-595); absent ⇒ CPF-required. */
+  buyerFields?: readonly CheckoutCustomerField[];
   /**
    * The saving, itemized under the total the buyer is about to authorize
    * (FUT-246) — RENDERED BY THE HOST from its cart (the storefront passes its
@@ -177,7 +182,7 @@ export function DadosStep({
   /** Comanda settlement (FUT-comandas): totals come from the comanda, not the cart. */
   totalOverride?: { label: string; items: number };
 }): JSX.Element {
-  const { ActionBar, Alert, Button, Checkbox, Text } = useCheckoutComponents();
+  const { Checkbox } = useCheckoutComponents();
   const { label: totalLabel, items: totalItems } = displayTotals(totalOverride, cartTotals);
 
   return (
@@ -186,6 +191,7 @@ export function DadosStep({
         <BuyerInfoForm
           value={buyer}
           onChange={onBuyerChange}
+          fields={buyerFields}
           fieldError={errorField && createError ? { field: errorField, message: createError } : null}
         />
         <Checkbox
@@ -196,32 +202,57 @@ export function DadosStep({
         />
       </Box>
 
-      <ActionBar dataTestId="checkout-pay-bar">
-        <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
-          {createError ? (
-            <Alert variant="danger" title="Não foi possível continuar" description={createError} showIcon data-testid="checkout-error" />
-          ) : null}
-          <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
-            <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>
-              {/* Suppressed while settling a comanda: those totals come from
-                  the frozen ticket, not the cart. */}
-              {totalOverride ? null : discountLines}
-            </PayBarTotal>
-            <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
-              <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
-                Continuar
-              </Button>
-              <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
-                <LockOutlinedIcon sx={{ fontSize: 13 }} />
-                <Text variant="caption" size="xs" color="secondary" as="span">
-                  Pagamento seguro
-                </Text>
-              </Box>
+      <DadosPayBar
+        totalLabel={totalLabel}
+        totalItems={totalItems}
+        createError={createError}
+        onContinue={onContinue}
+      >
+        {/* Suppressed while settling a comanda: those totals come from the
+            frozen ticket, not the cart. */}
+        {totalOverride ? null : discountLines}
+      </DadosPayBar>
+    </>
+  );
+}
+
+/** The sticky "Continuar" bar: the refusal, the money, and the one action. */
+function DadosPayBar({
+  totalLabel,
+  totalItems,
+  createError,
+  onContinue,
+  children,
+}: {
+  totalLabel: string;
+  totalItems: number;
+  createError: string | null;
+  onContinue: () => void;
+  children?: ReactNode;
+}): JSX.Element {
+  const { ActionBar, Alert, Button, Text } = useCheckoutComponents();
+  return (
+    <ActionBar dataTestId="checkout-pay-bar">
+      <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
+        {createError ? (
+          <Alert variant="danger" title="Não foi possível continuar" description={createError} showIcon data-testid="checkout-error" />
+        ) : null}
+        <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
+          <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>{children}</PayBarTotal>
+          <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
+            <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
+              Continuar
+            </Button>
+            <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
+              <LockOutlinedIcon sx={{ fontSize: 13 }} />
+              <Text variant="caption" size="xs" color="secondary" as="span">
+                Pagamento seguro
+              </Text>
             </Box>
           </Box>
         </Box>
-      </ActionBar>
-    </>
+      </Box>
+    </ActionBar>
   );
 }
 
@@ -283,8 +314,9 @@ export function PaymentStep({
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
   const cardUnavailable = !cardPathAvailable(providerConfig ?? null);
+  const offered = offeredMethods(providerConfig ?? null);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
-  usePreselectSoleMethod(cardUnavailable, method, onMethodChange);
+  usePreselectSoleMethod(selectableMethods(offered, cardUnavailable), method, onMethodChange);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
@@ -295,7 +327,7 @@ export function PaymentStep({
         value={method}
         onChange={onMethodChange}
         cardUnavailable={cardUnavailable}
-        offered={offeredMethods(providerConfig ?? null)}
+        offered={offered}
       />
 
       <PaymentBody

package/src/components/checkout/client-context.tsx

@@ -0,0 +1,57 @@
+/**
+ * WHICH client the checkout screens talk through (FUT-741).
+ *
+ * Before this, every screen imported the free functions in `client.ts`
+ * directly, so the mount they reach was a module-level constant: one prefix,
+ * the ambient `fetch`, no headers. That is right for the shipped storefront
+ * and impossible for anything else — a story, a harness page or a second host
+ * on a different mount could only get at the wire by replacing `globalThis.
+ * fetch`, which is a mock of OUR OWN client and the exact blind spot the
+ * FUT-740 review's three criticals lived in.
+ *
+ * So the client is context now, with the module-level one as the default. A
+ * tree with no provider behaves exactly as it did; a tree under
+ * `createPaymentFlows`'s provider talks through the bound transport.
+ *
+ * The default is built from the `client.ts` bindings LAZILY (inside each
+ * arrow), so a suite that `vi.mock`s that module still intercepts the call.
+ */
+import { createContext, useContext, type JSX, type ReactNode } from "react";
+
+import {
+  chargeCard,
+  fetchCheckoutConfig,
+  listSavedCards,
+  pollOrderStatus,
+  refreshCardPublicKey,
+} from "./client";
+import type { CheckoutClient } from "./transport";
+
+/** The unbound client: `/api/checkout` on the ambient `fetch`. */
+const DEFAULT_CLIENT: CheckoutClient = {
+  getConfig: (tenantSlug) => fetchCheckoutConfig(tenantSlug),
+  getStatus: (ref) => pollOrderStatus(ref),
+  charge: (input) => chargeCard(input),
+  listInstruments: (tenantSlug) => listSavedCards(tenantSlug),
+  refreshBrowserKey: (input) => refreshCardPublicKey(input),
+};
+
+const CheckoutClientContext = createContext<CheckoutClient | null>(null);
+
+/** Point everything below at one bound {@link CheckoutClient}. */
+export function CheckoutClientProvider({
+  client,
+  children,
+}: {
+  client: CheckoutClient;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <CheckoutClientContext.Provider value={client}>{children}</CheckoutClientContext.Provider>
+  );
+}
+
+/** The bound client, or the module default when no provider sits above. */
+export function useCheckoutClientApi(): CheckoutClient {
+  return useContext(CheckoutClientContext) ?? DEFAULT_CLIENT;
+}

package/src/components/checkout/client.ts

@@ -4,6 +4,14 @@
  * provider-protocol read, against the host-mounted `/api/checkout*` surface
  * (documented in `packages/payments/ADOPTING.md` §3).
  *
+ * Since FUT-741 these are the UNBOUND door onto `createCheckoutClient` — the
+ * same five calls, on the default `/api/checkout` prefix and the ambient
+ * `fetch`. They stay exported, and stay byte-identical on the wire, because
+ * they are what is already running in buyers' browsers and what both pinned
+ * wire suites drive. A host that needs a different mount, its own headers or an
+ * injected `fetch` reaches for `createPaymentFlows({ transport })` instead;
+ * nothing about these functions changes when it does.
+ *
  * Order CREATION and the buyer-profile save are deliberately NOT here: both
  * are host domain (the cart, the account) and reach the flow as ports
  * (`createOrder` / `saveBuyerContact` on `CheckoutFlowProps`).
@@ -14,8 +22,9 @@
  */
 
 import type { SavedCard } from "../../card";
-import { err, ok, type Result } from "../../result";
+import type { Result } from "../../result";
 
+import { createCheckoutClient } from "./transport";
 import type {
   ChargeCardInput,
   ChargeOutcome,
@@ -23,91 +32,15 @@ import type {
   OrderStatus,
 } from "./types";
 
-// ---------------------------------------------------------------------------
-// Transport
-// ---------------------------------------------------------------------------
-
-/** 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);
-}
-
-/** Call an API route and normalize the response into a {@link Result}. */
-async function requestResult<T>(input: string, init?: RequestInit): Promise<Result<T>> {
-  try {
-    const res = await fetch(input, {
-      ...init,
-      headers: { "Content-Type": "application/json", ...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.");
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
 /**
- * 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.
+ * The default binding: `/api/checkout` on the ambient `fetch`. Built once, but
+ * it resolves `fetch` per call, so a suite that stubs the global still wins.
  */
-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 } : {}),
-  };
-}
+const defaultClient = createCheckoutClient();
 
 /** Poll an order's reconciled status (async provider webhook confirmation). */
 export async function pollOrderStatus(orderId: string): Promise<Result<OrderStatus>> {
-  const params = new URLSearchParams({ orderId, ...returnedSettlement() });
-  return requestResult<OrderStatus>(`/api/checkout/status?${params.toString()}`, {
-    method: "GET",
-  });
+  return defaultClient.getStatus(orderId);
 }
 
 /**
@@ -119,10 +52,7 @@ export async function pollOrderStatus(orderId: string): Promise<Result<OrderStat
 export async function fetchCheckoutConfig(
   tenantSlug: string,
 ): Promise<Result<CheckoutProviderConfig>> {
-  return requestResult<CheckoutProviderConfig>(
-    `/api/checkout/config?tenantSlug=${encodeURIComponent(tenantSlug)}`,
-    { method: "GET" },
-  );
+  return defaultClient.getConfig(tenantSlug);
 }
 
 /**
@@ -135,10 +65,7 @@ export async function fetchCheckoutConfig(
 export async function refreshCardPublicKey(input: {
   orderId: string;
 }): Promise<Result<{ publicKey: string | null }>> {
-  return requestResult<{ publicKey: string | null }>("/api/checkout/refresh-key", {
-    method: "POST",
-    body: JSON.stringify({ orderId: input.orderId }),
-  });
+  return defaultClient.refreshBrowserKey(input);
 }
 
 /**
@@ -147,29 +74,10 @@ export async function refreshCardPublicKey(input: {
  * page (3-D Secure, FUT-698) — the caller then hands the buyer over.
  */
 export async function chargeCard(input: ChargeCardInput): Promise<Result<ChargeOutcome>> {
-  return requestResult<ChargeOutcome>("/api/checkout/charge", {
-    method: "POST",
-    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,
-    }),
-  });
+  return defaultClient.charge(input);
 }
 
 /** List saved cards available for reuse (empty on any error — non-blocking). */
 export async function listSavedCards(tenantSlug?: string): Promise<SavedCard[]> {
-  // 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 requestResult<SavedCard[]>(`/api/checkout/cards${query}`, {
-    method: "GET",
-  });
-  return result.ok ? result.data : [];
+  return defaultClient.listInstruments(tenantSlug);
 }

package/src/components/checkout/method-capability.ts

@@ -128,16 +128,38 @@ export function offeredMethods(config: CheckoutProviderConfig | null): PaymentMe
 }
 
 /**
- * When the card path is unavailable, PIX is the only choice left — choose it
- * (FUT-697 review): a one-option radiogroup that still demands a tap is a
- * click that buys the buyer nothing.
+ * The methods a buyer can actually pick right now.
+ *
+ * `null` offered — still loading, or a fetch blip — fails OPEN and offers both;
+ * the server still refuses the charge closed. A CARD tile with no in-browser
+ * path is not selectable, so it does not count towards a "sole" method either.
  */
-export function usePreselectSoleMethod(
+export function selectableMethods(
+  offered: PaymentMethod[] | null,
   cardUnavailable: boolean,
+): PaymentMethod[] {
+  return (offered ?? ["PIX", "CARD"]).filter(
+    (method) => !(method === "CARD" && cardUnavailable),
+  );
+}
+
+/**
+ * A SOLE remaining method is not a choice — take it (FUT-697 review, widened by
+ * FUT-741).
+ *
+ * A one-option radiogroup that still demands a tap is a click that buys the
+ * buyer nothing. It used to fire only when the CARD tile was disabled, which
+ * missed the other shape entirely: a store whose chain declares PIX alone
+ * renders one tile, nothing preselects it, and the buyer sits on a picker with
+ * a single option and no payment below it.
+ */
+export function usePreselectSoleMethod(
+  selectable: readonly PaymentMethod[],
   method: PaymentMethod | null,
   onMethodChange: (method: PaymentMethod) => void,
 ): void {
+  const sole = selectable.length === 1 ? selectable[0] : undefined;
   useEffect(() => {
-    if (cardUnavailable && method === null) onMethodChange("PIX");
-  }, [cardUnavailable, method, onMethodChange]);
+    if (method === null && sole) onMethodChange(sole);
+  }, [sole, method, onMethodChange]);
 }

package/src/components/checkout/navigate-context.tsx

@@ -0,0 +1,40 @@
+/**
+ * WHERE a hosted handover sends the buyer (FUT-741).
+ *
+ * The handover is a full navigation to ANOTHER ORIGIN — a redirect provider's
+ * page, or a 3-DS challenge — so it can never be the host's router. But it is
+ * still a thing some hosts must observe: log it, confirm it, or render an
+ * interstitial around it. Left as a bare `window.location.assign` inside the
+ * controller it was none of those, and a browser that blocks or stalls the
+ * navigation left the buyer on a page with nothing on it.
+ *
+ * So it is a port with a default. No provider ⇒ exactly today's behaviour.
+ */
+import { createContext, useContext, type JSX, type ReactNode } from "react";
+
+/** Take the buyer to another origin. */
+export type CheckoutNavigate = (url: string) => void;
+
+/** The unchanged default: a full navigation, in this tab. */
+const DEFAULT_NAVIGATE: CheckoutNavigate = (url) => {
+  window.location.assign(url);
+};
+
+const CheckoutNavigateContext = createContext<CheckoutNavigate | null>(null);
+
+export function CheckoutNavigateProvider({
+  navigate,
+  children,
+}: {
+  navigate: CheckoutNavigate;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <CheckoutNavigateContext.Provider value={navigate}>{children}</CheckoutNavigateContext.Provider>
+  );
+}
+
+/** The host's navigate port, or `window.location.assign`. */
+export function useCheckoutNavigate(): CheckoutNavigate {
+  return useContext(CheckoutNavigateContext) ?? DEFAULT_NAVIGATE;
+}

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 }),
+      }),
+  };
+}