@12-apps/payments-frontend 1.21.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.21.0",
+  "version": "2.0.0",
   "type": "module",
   "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.",
   "exports": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^2.1.0",
+    "@12-apps/payments-backend": "^3.0.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/ProviderConnection.tsx

@@ -163,9 +163,22 @@ function ConnectionSummary(props: {
           />
         </Stack>
       ) : null}
+      {/*
+        The connected sentence names NO platform. It used to open with one
+        adopter's product name, hard-coded — so every other host installing this
+        package told its own merchants that somebody else's product was creating
+        their charges, with no prop to change it. The tell that it was an
+        oversight rather than a decision is the branch right below, which already
+        templates the provider from props.
+
+        Nothing was lost by removing it. The sentence exists to answer ONE
+        question — why no API key had to be copied — and the answer is the OAuth
+        grant, not whose logo is on the page. The subject is the connection
+        itself, which is true for every host and needs no new configuration.
+      */}
       <Typography variant="body2" color="text.secondary">
         {props.connected
-          ? 'Sua conta está conectada. O Future Pay cria as cobranças em seu nome — nenhuma chave precisa ser copiada.'
+          ? 'Sua conta está conectada. As cobranças são criadas em seu nome — nenhuma chave precisa ser copiada.'
           : `Conecte sua conta ${props.displayName} autorizando o acesso no site do provedor. Nenhuma chave precisa ser copiada.`}
       </Typography>
       {props.connected && props.connectedAccount ? (

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

@@ -5,7 +5,7 @@ import { buyerFieldsFor } from "./buyer-fields";
 import { DadosStep, EmptyCart, PaymentStep } from "./checkout-steps";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
-import type { BuyerInfo, CheckoutProviderConfig, ComandaCheckout } from "./types";
+import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
 import { CheckoutComponentsProvider, useCheckoutComponents, type CheckoutComponents } from "./ui";
 import { useCheckoutController, type CheckoutHostPorts } from "./use-checkout-controller";
 
@@ -17,7 +17,7 @@ const STEPPER_STEPS = [
 
 /** What the flow reads off the host's cart — display facts, never money math. */
 export interface CheckoutCartView {
-  /** Nothing to check out (cart mode only; a comanda settlement ignores it). */
+  /** Nothing to check out (cart mode only; a settlement settlement ignores it). */
   empty: boolean;
   totalLabel: string;
   totalItems: number;
@@ -30,7 +30,7 @@ export interface CheckoutCartView {
  * three-step flow — Dados → Pagamento → Confirmação — with the payment step
  * speaking the store's ACTIVE provider protocol (PagBank PIX + card, Stone
  * card, InfinitePay hosted redirect) against the host-mounted `/api/checkout*`
- * surface. Cart, catalog, comanda and order CREATION stay in the host and
+ * surface. Cart, catalog, settlement and order CREATION stay in the host and
  * arrive through {@link CheckoutHostPorts} + {@link CheckoutCartView};
  * pixels render through the slot contract (`components`, see `ui.tsx`).
  */
@@ -38,8 +38,8 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   /** The host's cart, reduced to what the flow displays. */
   cart: CheckoutCartView;
   defaultBuyer?: BuyerInfo;
-  /** Present ⇒ this checkout settles a comanda, not the cart (FUT-comandas). */
-  comanda?: ComandaCheckout | null;
+  /** Present ⇒ this checkout settles an open balance, not the cart . */
+  settlement?: SettlementCheckout | null;
   /** The buyer has a CPF saved ⇒ open on Pagamento, skipping Dados (FUT-465). */
   taxIdOnFile?: boolean;
   /** The store's active payment protocol (FUT-697); absent while loading. */
@@ -51,7 +51,7 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
    * session's `validationURL` for an Apple merchant session, SERVER-SIDE.
    * Optional — without it the Apple Pay sheet cannot start, and the card form
    * remains the way to pay.
-   */
+ */
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** Host content shown on the paid confirmation (the storefront's install invite). */
   confirmationExtra?: ReactNode;
@@ -59,11 +59,11 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   components?: Partial<CheckoutComponents>;
 }
 
-/** The pay-bar total override when settling a comanda (else the cart's own totals). */
-function comandaTotalOverride(
-  comanda: ComandaCheckout | null | undefined,
+/** The pay-bar total override when settling a settlement (else the cart's own totals). */
+function settlementTotalOverride(
+  settlement: SettlementCheckout | null | undefined,
 ): { label: string; items: number } | undefined {
-  return comanda ? { label: comanda.totalLabel, items: comanda.totalItems } : undefined;
+  return settlement ? { label: settlement.totalLabel, items: settlement.totalItems } : undefined;
 }
 
 /**
@@ -78,13 +78,13 @@ function confirmationFacts(
   return { orderId: order?.orderId, buyerEmail: buyer.email };
 }
 
-/** The confirmation total: the created order's, else the comanda scope's, else the cart's. */
+/** The confirmation total: the created order's, else the settlement scope's, else the cart's. */
 function statusTotalLabel(
   order: { totalLabel: string } | null,
-  comanda: ComandaCheckout | null | undefined,
+  settlement: SettlementCheckout | null | undefined,
   cart: { totalLabel: string },
 ): string {
-  return order?.totalLabel ?? comanda?.totalLabel ?? cart.totalLabel;
+  return order?.totalLabel ?? settlement?.totalLabel ?? cart.totalLabel;
 }
 
 /**
@@ -125,7 +125,7 @@ function ProgressHeader({ step, completed }: { step: string; completed: Set<stri
  * card public key are loaded lazily by the card path (order-scoped REST).
  */
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { cart, defaultBuyer, comanda, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, ...ports } = props;
+  const { cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, ...ports } = props;
   // Resolved for NO method on purpose (FUT-595): the Dados step opens before
   // the picker, and the form is filled once — so it asks for the union of what
   // any chain member may need rather than re-opening after the choice. A chain
@@ -133,14 +133,14 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   const buyerFields = useMemo(() => buyerFieldsFor(providerConfig?.chain, null), [providerConfig]);
   const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields);
 
-  // A comanda settlement pays already-sent kitchen items — the cart is
+  // A settlement settlement pays already-sent kitchen items — the cart is
   // legitimately empty here, so the empty-cart guard only applies to cart mode.
   //
   // The guard cannot key on the Dados step any more: skipping it (FUT-465) makes
   // Pagamento the first screen, so an empty cart would otherwise reach the
   // method picker. It holds until an order exists — once one does, its lines are
   // snapshotted server-side and the cart no longer speaks for it.
-  if (!comanda && cart.empty && !c.order && c.step !== "status") {
+  if (!settlement && cart.empty && !c.order && c.step !== "status") {
     return <EmptyCart onBack={c.goToMenu} />;
   }
 
@@ -162,7 +162,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
           cartTotals={cart}
           buyerFields={buyerFields}
           discountLines={cart.discountLines}
-          totalOverride={comandaTotalOverride(comanda)}
+          totalOverride={settlementTotalOverride(settlement)}
         />
       ) : null}
 
@@ -191,7 +191,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       {c.step === "status" ? (
         <PaymentStatus
           status={c.finalStatus}
-          totalLabel={statusTotalLabel(c.order, comanda, cart)}
+          totalLabel={statusTotalLabel(c.order, settlement, cart)}
           {...confirmationFacts(c.order, c.buyer)}
           onRetry={c.retry}
           onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}

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

@@ -113,8 +113,8 @@ export function EmptyCart({ onBack }: { onBack: () => void }): JSX.Element {
 }
 
 /**
- * The totals shown on the pay bar: the comanda scope's when settling a comanda
- * (FUT-comandas), otherwise the cart's own — both supplied by the host, which
+ * The totals shown on the pay bar: the settled balance's when settling a settlement
+ * one, otherwise the cart's own — both supplied by the host, which
  * is the only side that knows either.
  */
 function displayTotals(
@@ -184,9 +184,9 @@ export function DadosStep({
    * (FUT-246) — RENDERED BY THE HOST from its cart (the storefront passes its
    * cart footer's money block), never re-implemented here, so the two surfaces
    * can never word the same discount differently.
-   */
+ */
   discountLines?: ReactNode;
-  /** Comanda settlement (FUT-comandas): totals come from the comanda, not the cart. */
+  /** Settling an open balance: totals come from the settlement, not the cart. */
   totalOverride?: { label: string; items: number };
 }): JSX.Element {
   const { Checkbox } = useCheckoutComponents();
@@ -215,7 +215,7 @@ export function DadosStep({
         createError={createError}
         onContinue={onContinue}
       >
-        {/* Suppressed while settling a comanda: those totals come from the
+        {/* Suppressed while settling a balance: those totals come from the
             frozen ticket, not the cart. */}
         {totalOverride ? null : discountLines}
       </DadosPayBar>
@@ -275,21 +275,21 @@ interface PaymentStepProps {
   /**
    * The refusal's machine code (FUT-563). An UNRESOLVED charge is not a failed
    * one — the panel below must not offer to raise a second.
-   */
+ */
   errorCode?: string | null;
   onGenerate: (method: PaymentMethod) => void;
   onUseEmail: (email: string) => void;
   /**
    * Present ⇒ the buyer reached this step without a Dados step (FUT-465), so
    * the payer block states who is being charged and reopens Dados to change it.
-   */
+ */
   onEditBuyer?: () => void;
   /**
    * The store's active payment protocol (`GET /api/checkout/config`, FUT-697).
    * `null` while loading or on a transient fetch failure — methods then render
    * as before and the card path degrades to the PagBank per-order key refresh,
    * WITHOUT mock permission (fail-open for the UI, fail-closed for the money).
-   */
+ */
   providerConfig?: CheckoutProviderConfig | null;
   /** Scopes the saved-card list to the store being paid (host routing owns it). */
   tenantSlug?: string;

package/src/components/checkout/hosted-return.ts

@@ -18,7 +18,31 @@ import type { CheckoutOrder } from "./types";
  * unrelated session.
  */
 
-const KEY = "futurepay.checkout.hostedOrder";
+/**
+ * Where the parked order lives, namespaced to this PACKAGE.
+ *
+ * It used to carry one adopter's brand as its namespace, written into every
+ * adopter's browser. A storage key is not a private detail: it is observable
+ * surface, asserted on by `@12-apps/payments-e2e` and visible in devtools to
+ * anyone running the host. The sibling handover in this same folder already got
+ * this right with a `payments:` prefix; this one did not.
+ *
+ * Exported so a host or a spec names it rather than retyping it.
+ */
+export const HOSTED_ORDER_STORAGE_KEY = "payments.checkout.hostedOrder";
+
+/**
+ * The key before the rename, READ ONLY.
+ *
+ * A buyer who left for the provider's page on the old bundle comes back to the
+ * new one with their order parked under the old name. Without this they land on
+ * the plain return screen — the order still settles, because the webhook does
+ * that and never depended on any of this, but the confirmation they were
+ * promised is missing for a reason they could not possibly understand.
+ *
+ * Delete once no session can still be mid-redirect across that deploy.
+ */
+const LEGACY_KEY = "futurepay.checkout.hostedOrder";
 
 /**
  * What a hosted provider appends to the return URL. InfinitePay sends the
@@ -46,7 +70,7 @@ function isReturnTrip(): boolean {
 /** Park the raised order before handing the buyer to the provider's page. */
 export function rememberHostedOrder(order: CheckoutOrder): void {
   try {
-    window.sessionStorage?.setItem(KEY, JSON.stringify(order));
+    window.sessionStorage?.setItem(HOSTED_ORDER_STORAGE_KEY, JSON.stringify(order));
   } catch {
     // Storage disabled or full. The redirect must still happen: the webhook
     // settles the order either way, and refusing to send the buyer to pay
@@ -62,15 +86,37 @@ export function rememberHostedOrder(order: CheckoutOrder): void {
  * of resuming one they never paid. Read-and-clear for the same reason: the
  * resumed view belongs to exactly one return.
  */
-export function takeHostedOrder(): CheckoutOrder | null {
-  if (!isReturnTrip()) return null;
-  let raw: string | null = null;
+/**
+ * The raw parked payload under either key, cleared as it is read.
+ *
+ * Split out from {@link takeHostedOrder} so the storage handling and the
+ * parsing stay separately readable — reading two keys and clearing both put the
+ * combined function over the complexity gate, and the two halves fail for
+ * unrelated reasons anyway (storage disabled vs. a value that is not an order).
+ *
+ * BOTH keys are cleared whichever one answered: this is read-and-clear, and a
+ * legacy entry left behind would let a later return trip resume an order that
+ * was already consumed.
+ */
+function takeParkedPayload(): string | null {
   try {
-    raw = window.sessionStorage?.getItem(KEY) ?? null;
-    window.sessionStorage?.removeItem(KEY);
+    const raw =
+      window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
+      window.sessionStorage?.getItem(LEGACY_KEY) ??
+      null;
+    window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
+    window.sessionStorage?.removeItem(LEGACY_KEY);
+    return raw;
   } catch {
+    // Storage disabled or unavailable — the same "no parked order" as an empty
+    // slot, and the webhook still settles the order regardless.
     return null;
   }
+}
+
+export function takeHostedOrder(): CheckoutOrder | null {
+  if (!isReturnTrip()) return null;
+  const raw = takeParkedPayload();
   if (!raw) return null;
   try {
     const parsed: unknown = JSON.parse(raw);

package/src/components/checkout/types.ts

@@ -92,7 +92,7 @@ export interface CheckoutOrder {
   totalCents: number;
   /**
    * GROSS total before discounts, or null when the discount engine never ran
-   * for this order (every order predating FUT-235, and the comanda path): the
+   * for this order (every order predating FUT-235, and the settlement path): the
    * subtotal then simply IS {@link totalCents}.
    */
   subtotalCents: number | null;
@@ -117,13 +117,25 @@ export interface CheckoutOrder {
 }
 
 /**
- * Comanda settlement context for the checkout (FUT-comandas): the scope plus
- * the host-resolved totals shown in place of the cart total when settling a
- * comanda. HOW a comanda is resolved is the host's business; the flow only
- * renders the answer.
+ * SETTLEMENT context: this checkout pays an already-open balance rather than
+ * the cart.
+ *
+ * Named for what it does, not for the one product it came from. It was
+ * `SettlementCheckout` with `scope: "MINE" | "TABLE"` — a restaurant tab and its
+ * two ways of splitting one — which is a real concept but that host's, and it
+ * arrived in every adopter's type surface. The shape underneath is general: a
+ * host has resolved SOME balance, by whatever rule it likes, and the flow shows
+ * that total in place of the cart's.
+ *
+ * `scope` is an opaque string the library only echoes back. It exists so a host
+ * can tell its own two settlement modes apart in the events it receives; this
+ * package neither reads it nor enumerates it, which is exactly why it must not
+ * publish a closed set of somebody else's words.
+ *
+ * HOW a balance is resolved is the host's business; the flow renders the answer.
  */
-export interface ComandaCheckout {
-  scope: "MINE" | "TABLE";
+export interface SettlementCheckout {
+  scope: string;
   totalLabel: string;
   totalItems: number;
 }
@@ -153,7 +165,7 @@ export type CreateOrderResult =
 
 /**
  * What the flow hands the host's `createOrder` port. Everything else an order
- * needs — WHICH cart, WHICH comanda scope, WHICH tenant — is the host's own
+ * needs — WHICH cart, WHICH settlement scope, WHICH tenant — is the host's own
  * context, closed over by its port implementation.
  */
 export interface CreateOrderRequest {

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

@@ -35,15 +35,15 @@ const CPF_ONLY: readonly CheckoutCustomerField[] = [
 export interface CheckoutHostPorts {
   /**
    * Raise the order (and its first charge). The host closes over everything
-   * the flow must not know: WHICH cart, WHICH tenant, WHICH comanda scope.
-   */
+   * the flow must not know: WHICH cart, WHICH tenant, WHICH settlement scope.
+ */
   createOrder: (input: CreateOrderRequest) => Promise<CreateOrderResult>;
   /**
    * Persist the buyer's contact when they press "Continuar" on Dados — the
    * host's account surface owns the write (and the blank-CPF-never-clears
    * rule). Fire-and-forget by contract: the flow advances regardless of the
    * outcome, and only calls this under the "salvar meus dados" consent.
-   */
+ */
   saveBuyerContact?: (contact: BuyerContact) => void;
   /** Leave checkout for the host's menu/catalog. */
   onExitToMenu: () => void;
@@ -52,7 +52,7 @@ export interface CheckoutHostPorts {
    * server emptied it inside the confirmation transaction (FUT-601) and
    * nothing else tells the SPA. Never fired for FAILED/EXPIRED: that shopper
    * still has a basket to retry with.
-   */
+ */
   onPaid?: () => void;
 }
 

package/src/flows/copy.ts

@@ -9,8 +9,13 @@
  * 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.
+ * THE DEFAULTS ARE GONE (FUT-760). `DEFAULT_CHECKOUT_COPY_FE` held one
+ * product's RESTAURANT vocabulary — "Pagamento com o garçom", "Chame o garçom
+ * para fechar a conta na mesa", "Ver cardápio" — and was spread into every
+ * adopter that passed no `copy`. A host selling insurance got a waiter, and
+ * nothing failed, because saying nothing is exactly how a host silently adopts
+ * another product's voice. `copy` is required on the config now; this file is
+ * the port and nothing else.
  */
 
 /** Every buyer-facing string the factory's own screens render. */
@@ -49,33 +54,3 @@ export interface CheckoutCopyFE {
   manageCardsEmpty: string;
   manageCardsAdd: 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",
-  addCardTitle: "Adicionar cartão",
-  addCardAction: "Salvar cartão",
-  addCardPreparing: "Preparando o formulário…",
-  addCardSavedTitle: "Cartão salvo",
-  addCardSavedBody: "Você poderá usá-lo nas próximas compras.",
-  addCardFailedTitle: "Não foi possível salvar o cartão",
-  addCardUnavailable: "Esta loja não aceita salvar cartões no momento.",
-  manageCardsTitle: "Meus cartões",
-  manageCardsEmpty: "Você ainda não tem cartões salvos.",
-  manageCardsAdd: "Adicionar cartão",
-};

package/src/flows/create-payment-flows.tsx

@@ -7,7 +7,7 @@
  *
  * ## Why the scope arrives as HOOKS
  *
- * `useScope`, `useCart`, `useBuyerDefaults`, `useComanda` and
+ * `useScope`, `useCart`, `useBuyerDefaults`, `useSettlement` and
  * `ports.useAvailability` are hooks, not values, and they are invoked in a
  * component BODY — never read at factory time. The factory runs once, at module
  * evaluation, so a value-shaped config would freeze the first store's slug and
@@ -19,10 +19,9 @@ import { useCallback, type JSX, type ReactNode } from "react";
 import { buyerFieldsFor } from "../components/checkout/buyer-fields";
 import { CheckoutFlow } from "../components/checkout/checkout-flow";
 import { createCheckoutClient } from "../components/checkout/transport";
-import type { CheckoutProviderConfig, ComandaCheckout } from "../components/checkout/types";
+import type { CheckoutProviderConfig, SettlementCheckout } from "../components/checkout/types";
 import { useCheckoutController } from "../components/checkout/use-checkout-controller";
 
-import { DEFAULT_CHECKOUT_COPY_FE } from "./copy";
 import { FlowsProvider, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import { buyerScreens } from "./screens-buyer";
 import { hostedScreens } from "./screens-hosted";
@@ -50,7 +49,7 @@ function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
   return {
     config,
     client,
-    copy: { ...DEFAULT_CHECKOUT_COPY_FE, ...config.copy },
+    copy: config.copy,
     navigate,
     // Both of these are HOOKS. They are called from a component body on every
     // render, so the slug follows the host's router and the availability vote
@@ -68,10 +67,10 @@ function buildCheckout(
   const { ports } = runtime.config;
   const Unavailable = screens.PaymentsUnavailable;
 
-  function CheckoutBody({ comanda }: { comanda?: ComandaCheckout | null }): JSX.Element {
+  function CheckoutBody({ settlement }: { settlement?: SettlementCheckout | null }): JSX.Element {
     const cart = runtime.config.useCart();
     const defaults = runtime.config.useBuyerDefaults?.() ?? {};
-    const hostComanda = runtime.config.useComanda?.() ?? null;
+    const hostSettlement = runtime.config.useSettlement?.() ?? null;
     const { config, pending } = useResolvedConfig(runtime);
     const availability = runtime.useAvailability();
     const tenantSlug = runtime.useTenantSlug();
@@ -93,7 +92,7 @@ function buildCheckout(
         onPaid={ports.onPaid}
         defaultBuyer={defaults.buyer}
         taxIdOnFile={defaults.taxIdOnFile ?? false}
-        comanda={comanda ?? hostComanda}
+        settlement={settlement ?? hostSettlement}
         providerConfig={config}
         tenantSlug={tenantSlug}
         confirmationExtra={runtime.config.confirmation?.extra}

package/src/flows/types.ts

@@ -31,7 +31,7 @@ import type {
   ChargeOutcome,
   CheckoutOrder,
   CheckoutProviderConfig,
-  ComandaCheckout,
+  SettlementCheckout,
   CreateOrderRequest,
   CreateOrderResult,
   OrderStatus,
@@ -100,8 +100,8 @@ export interface PaymentFlowsConfig {
   useCart(): CheckoutCartView;
   /** The buyer's saved details, and whether a CPF is already on file. */
   useBuyerDefaults?(): { buyer?: BuyerInfo; taxIdOnFile?: boolean; pending?: boolean };
-  /** Present ⇒ this checkout settles a comanda rather than the cart. */
-  useComanda?(): ComandaCheckout | null;
+  /** Present ⇒ this checkout settles a settlement rather than the cart. */
+  useSettlement?(): SettlementCheckout | null;
 
   /** Design-system slots, filled ONCE instead of per screen. */
   components?: Partial<CheckoutComponents>;
@@ -117,7 +117,20 @@ export interface PaymentFlowsConfig {
   // "what happens WHEN it fires": a timed-out mint must decide whether the walk
   // advances to the next entry or the whole charge refuses, and that is a money
   // rule (FUT-563), not a wire-up.
-  copy?: Partial<CheckoutCopyFE>;
+  /**
+   * Every buyer-facing sentence the factory's own screens render.
+   *
+   * REQUIRED, and not partial. It used to be `Partial<…>` over a pt-BR default
+   * spread in at `create-payment-flows.tsx`, and that default was one product's
+   * RESTAURANT vocabulary — "Pagamento com o garçom", "Chame o garçom para
+   * fechar a conta na mesa", "Ver cardápio" — reaching every adopter that said
+   * nothing. A host selling insurance got a waiter.
+   *
+   * That is the failure a default cannot warn about: saying nothing is exactly
+   * how a host adopts another product's voice, and nothing fails. Required
+   * makes a new host answer once, at the one call site that knows the answer.
+   */
+  copy: CheckoutCopyFE;
   /** Host content under the paid receipt (the storefront's PWA install invite). */
   confirmation?: { extra?: ReactNode };
   /**
@@ -187,7 +200,7 @@ export interface CheckoutConfigState {
 /** What `createPaymentFlows` returns. */
 export interface PaymentFlows {
   /** THE mount: a complete buyer checkout in one line. */
-  Checkout: ComponentType<{ comanda?: ComandaCheckout | null }>;
+  Checkout: ComponentType<{ settlement?: SettlementCheckout | null }>;
   /** Slots + transport + scope + the fetched config, for a nesting host. */
   Provider: ComponentType<{ children: ReactNode; config?: CheckoutProviderConfig | null }>;
   screens: CheckoutScreens;

package/src/index.ts

@@ -57,7 +57,6 @@ export {
 // ---------------------------------------------------------------------------
 export { createPaymentFlows } from './flows/create-payment-flows';
 export {
-  DEFAULT_CHECKOUT_COPY_FE,
   type CheckoutCopyFE,
 } from './flows/copy';
 export {
@@ -87,6 +86,13 @@ export {
 export { type CheckoutHostPorts } from './components/checkout/use-checkout-controller';
 export { PaymentsUnavailable } from './components/checkout/payments-unavailable';
 export { fetchCheckoutConfig } from './components/checkout/client';
+/**
+ * The `sessionStorage` key the hosted-checkout return leg parks the raised
+ * order under. Public because it is already observable — a spec asserting the
+ * handover, or a host clearing storage on sign-out, otherwise retypes the
+ * literal and silently drifts when it changes.
+ */
+export { HOSTED_ORDER_STORAGE_KEY } from './components/checkout/hosted-return';
 // ---------------------------------------------------------------------------
 // Digital wallets (FUT-471/472) — the Google-branded button and the capability
 // read it is gated on. `CheckoutFlow` wires these automatically; they are
@@ -136,7 +142,7 @@ export {
   type CheckoutOrder,
   type CheckoutProviderConfig,
   type CheckoutWalletType,
-  type ComandaCheckout,
+  type SettlementCheckout,
   type CreateOrderRequest,
   type CreateOrderResult,
   type OrderStatus,