@12-apps/payments-frontend 3.9.0 → 3.11.0

package/src/components/checkout/buyer-gate.ts

@@ -0,0 +1,68 @@
+/**
+ * What the "Continuar" gate objects to (FUT-595), split out of
+ * `use-checkout-controller.ts`.
+ *
+ * Its own module because the answer is a pure function of what the store's
+ * chain declared, the buyer's form, and the words a host chose — nothing in
+ * here touches React, a network or the controller's state machine, and the
+ * controller was over the file-size gate carrying it.
+ */
+import { buyerFormComplete } from "./buyer-info-form";
+import type { CheckoutValidationCopy } from "./screens-copy";
+import type { BuyerField, BuyerInfo, CheckoutCustomerField } from "./types";
+
+/**
+ * The message shown when a declared field is missing or malformed — the HOST's
+ * words (FUT-760), keyed by the field the chain declared.
+ *
+ * Built from the copy rather than held as a module constant: a frozen table
+ * could only carry the origin host's Portuguese, and it would reach every
+ * adopter's buyer on the very first field they got wrong.
+ */
+function fieldComplaints(copy: CheckoutValidationCopy): Record<string, string> {
+  return {
+    taxId: copy.taxIdInvalid,
+    name: copy.nameRequired,
+    email: copy.emailInvalid,
+    phone: copy.phoneInvalid,
+  };
+}
+
+/** 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, or undefined to advance.
+ *
+ * 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.
+ */
+export function buyerGateError(
+  copy: CheckoutValidationCopy,
+  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: fieldComplaints(copy)[offending.key] ?? copy.required,
+    field: FIELD_INPUT[offending.key] ?? "cpf",
+  };
+}
+

package/src/components/checkout/buyer-info-form.tsx

@@ -6,6 +6,8 @@ import { formatCpf, validateCpf } from "../../card";
 import { fieldSatisfied } from "./buyer-fields";
 import type { BuyerField, BuyerInfo, CheckoutCustomerField } from "./types";
 import { useCheckoutComponents } from "./ui";
+import type { CardFieldCopy } from "../../card/copy";
+import { useCheckoutCopy, type BuyerInfoCopy } from "./copy-context";
 
 const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
@@ -62,18 +64,20 @@ function deriveErrors(
   value: BuyerInfo,
   fieldError: FieldError,
   required: ReadonlySet<InputKey>,
+  copy: BuyerInfoCopy,
+  cardCopy: CardFieldCopy,
 ): BuyerFieldErrors {
   const override = (field: BuyerField): string | undefined =>
     fieldError?.field === field ? fieldError.message : undefined;
   const localEmail =
-    value.email && !EMAIL_PATTERN.test(value.email) ? "E-mail inválido." : undefined;
+    value.email && !EMAIL_PATTERN.test(value.email) ? copy.emailInvalid : undefined;
   const missing = (key: InputKey, message: string): string | undefined =>
     required.has(key) && !valueOf(value, key).trim() ? message : undefined;
   return {
-    cpf: override("cpf") ?? (value.taxId ? validateCpf(value.taxId) : undefined),
-    email: override("email") ?? localEmail ?? missing("email", "E-mail obrigatório."),
-    name: override("name") ?? missing("name", "Nome obrigatório."),
-    phone: override("phone") ?? missing("phone", "Telefone obrigatório."),
+    cpf: override("cpf") ?? (value.taxId ? validateCpf(value.taxId, cardCopy) : undefined),
+    email: override("email") ?? localEmail ?? missing("email", copy.emailRequired),
+    name: override("name") ?? missing("name", copy.nameRequired),
+    phone: override("phone") ?? missing("phone", copy.phoneRequired),
   };
 }
 
@@ -82,17 +86,11 @@ function deriveErrors(
  * declared. It used to name the CPF unconditionally, which is wrong the moment
  * a store's provider wants something else (or nothing).
  */
-function instructionFor(required: ReadonlySet<InputKey>): string {
+function instructionFor(required: ReadonlySet<InputKey>, copy: BuyerInfoCopy): string {
   const names = FIELD_ORDER.filter((key) => required.has(key)).map((key) =>
     key === "taxId" ? "CPF" : INPUTS[key].label.toLowerCase(),
   );
-  if (names.length === 0) {
-    return "Nome, e-mail e telefone são opcionais — usados apenas para o comprovante.";
-  }
-  return (
-    `Informe seu ${names.join(", ")} (${names.length === 1 ? "obrigatório" : "obrigatórios"} ` +
-    "para o pagamento). Os demais campos são opcionais — usados apenas para o comprovante."
-  );
+  return copy.fieldsHint(names);
 }
 
 /** Which inputs to render, and which of them are required. */
@@ -184,12 +182,13 @@ export function BuyerInfoForm({
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const { shown, required } = resolveShape(fields);
-  const errors = deriveErrors(value, fieldError ?? null, required);
+  const copy = useCheckoutCopy();
+  const errors = deriveErrors(value, fieldError ?? null, required, copy.buyer, copy.card.fields);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       <Text variant="caption" size="xs" color="secondary" as="p">
-        {instructionFor(required)}
+        {instructionFor(required, copy.buyer)}
       </Text>
 
       {shown.map((key) => (

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

@@ -7,16 +7,18 @@ import {
 } from "../../card";
 import { err, ok, type Result } from "../../result";
 
-import { refreshCardPublicKey } from "./client";
 import type { CardChainLink } from "./method-capability";
 import type { SavedCardMeta } from "./types";
+import type { CardCopy } from "../../card/copy";
 
 /**
  * The order-scoped key refresh, as a parameter (FUT-741).
  *
  * The self-heal is a call to OUR OWN mount, so it has to go through whichever
- * transport the surrounding checkout was bound to. Defaulted to the unbound
- * module function, which is exactly what it always called.
+ * transport the surrounding checkout was bound to. Required since FUT-760: the
+ * default was the unbound module call, and that now needs words this module
+ * has no business choosing. Every real caller already passed the bound
+ * `client.refreshBrowserKey`.
  */
 export type RefreshBrowserKey = (input: {
   orderId: string;
@@ -51,15 +53,16 @@ async function tokenizeNewCard(
   orderId: string,
   onKeyRefreshed: (key: string) => void,
   refreshKey: RefreshBrowserKey,
+  copy: CardCopy,
 ): Promise<Result<CardToken>> {
-  const first = await tokenizeForCheckout(card, config);
+  const first = await tokenizeForCheckout(card, config, copy);
   if (first.ok || !config.publicKey) return first;
   if (config.provider === null || tokenizerFor(config.provider) !== "pagbank-sdk") return first;
 
   const refreshed = await refreshKey({ orderId });
   if (refreshed.ok && refreshed.data.publicKey && refreshed.data.publicKey !== config.publicKey) {
     onKeyRefreshed(refreshed.data.publicKey);
-    return tokenizeForCheckout(card, { ...config, publicKey: refreshed.data.publicKey });
+    return tokenizeForCheckout(card, { ...config, publicKey: refreshed.data.publicKey }, copy);
   }
   return first;
 }
@@ -92,6 +95,7 @@ async function mintChainInstruments(
   card: CardDetails,
   chain: readonly CardChainLink[],
   timeoutMs: number,
+  copy: CardCopy,
 ): Promise<Record<string, CardToken>> {
   const results = await Promise.all(
     chain.map(async (link) => {
@@ -100,7 +104,7 @@ async function mintChainInstruments(
       // stub mode and an error everywhere else. It still travels in `chain`,
       // because the walk will reach it.
       if (!link.provider || !link.mintable) return null;
-      const tokenized = await mintWithDeadline(card, link, timeoutMs);
+      const tokenized = await mintWithDeadline(card, link, timeoutMs, copy);
       return tokenized.ok ? ([link.provider, tokenized.data] as const) : null;
     }),
   );
@@ -125,6 +129,7 @@ async function mintWithDeadline(
   card: CardDetails,
   link: CardChainLink,
   timeoutMs: number,
+  copy: CardCopy,
 ): Promise<Result<CardToken>> {
   const controller = new AbortController();
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -133,11 +138,14 @@ async function mintWithDeadline(
   const deadline = new Promise<Result<CardToken>>((resolve) => {
     timer = setTimeout(() => {
       controller.abort();
-      resolve(err("O provedor do cartão não respondeu a tempo."));
+      resolve(err(copy.tokenize.providerTimedOut));
     }, timeoutMs);
   });
   try {
-    return await Promise.race([tokenizeForCheckout(card, link, controller.signal), deadline]);
+    return await Promise.race([
+      tokenizeForCheckout(card, link, copy, controller.signal),
+      deadline,
+    ]);
   } finally {
     clearTimeout(timer);
   }
@@ -197,12 +205,20 @@ async function mintEveryEntry(input: {
   onKeyRefreshed: (key: string) => void;
   refreshKey: RefreshBrowserKey;
   timeoutMs: number;
+  copy: CardCopy;
 }): Promise<{ headToken: Result<CardToken>; minted: Record<string, CardToken> }> {
   const head = mintingConfig(input.config, input.entries);
   const rest = input.entries.filter((link) => link.provider !== head.provider);
   const [headToken, tail] = await Promise.all([
-    tokenizeNewCard(input.card, head, input.orderId, input.onKeyRefreshed, input.refreshKey),
-    mintChainInstruments(input.card, rest, input.timeoutMs),
+    tokenizeNewCard(
+      input.card,
+      head,
+      input.orderId,
+      input.onKeyRefreshed,
+      input.refreshKey,
+      input.copy,
+    ),
+    mintChainInstruments(input.card, rest, input.timeoutMs, input.copy),
   ]);
   // A failure in the tail is not fatal: that provider is simply one the walk
   // will skip.
@@ -226,10 +242,12 @@ export async function resolveNewCardToken(
   onKeyRefreshed: (key: string) => void,
   saveCard: boolean,
   chain: readonly CardChainLink[],
+  /** The words a failed mint reports with — the host's (FUT-760). */
+  copy: CardCopy,
+  /** The bound key refresh (FUT-741) — the surrounding checkout's transport. */
+  refreshKey: RefreshBrowserKey,
   /** Per-entry mint deadline. Overridable so tests need not wait it out. */
   timeoutMs: number = MINT_TIMEOUT_MS,
-  /** The bound key refresh (FUT-741); defaults to the unbound module call. */
-  refreshKey: RefreshBrowserKey = refreshCardPublicKey,
 ): Promise<Result<CardInstruments>> {
   // No chain served (an older host, or a fetch blip): the active provider
   // alone, exactly the pre-FUT-563 behaviour.
@@ -242,6 +260,7 @@ export async function resolveNewCardToken(
     onKeyRefreshed,
     refreshKey,
     timeoutMs,
+    copy,
   });
 
   // Refused only when NO entry could be minted for. While one still can, the

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

@@ -8,6 +8,7 @@ import {
   type CardTokenizationConfig,
 } from "../../card";
 
+import { useCheckoutCopy } from "./copy-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
 import type { CardChainLink } from "./method-capability";
 import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
@@ -28,11 +29,12 @@ function SubmittedState({
   pollTimedOut: boolean;
 }): JSX.Element {
   const { Alert, LoadingState } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.settling;
   if (pollError) {
     return (
       <Alert
         variant="danger"
-        title="Não foi possível confirmar o pagamento"
+        title={copy.cannotConfirm}
         description={pollError}
         showIcon
         data-testid="card-poll-error"
@@ -43,8 +45,8 @@ function SubmittedState({
     return (
       <Alert
         variant="warning"
-        title="O pagamento está demorando mais que o esperado"
-        description="Você pode aguardar ou verificar seu pedido em instantes — não realize um novo pagamento."
+        title={copy.takingLonger}
+        description={copy.takingLongerHelp}
         showIcon
         data-testid="card-poll-timeout"
       />
@@ -54,7 +56,7 @@ function SubmittedState({
     <LoadingState
       variant="spinner"
       size="md"
-      message="Processando pagamento…"
+      message={copy.processing}
       dataTestId="card-processing"
     />
   );
@@ -76,11 +78,12 @@ function ChargeFailure({
   unresolved: boolean;
 }): JSX.Element {
   const { Alert } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.settling;
   if (unresolved) {
     return (
       <Alert
         variant="warning"
-        title="Estamos confirmando seu pagamento"
+        title={copy.confirming}
         description={message}
         showIcon
         data-testid="card-unresolved"
@@ -88,7 +91,7 @@ function ChargeFailure({
     );
   }
   return (
-    <Alert variant="danger" title="Não foi possível pagar" description={message} showIcon data-testid="card-error" />
+    <Alert variant="danger" title={copy.cannotPay} description={message} showIcon data-testid="card-error" />
   );
 }
 
@@ -127,6 +130,7 @@ export function CardView({
   pollIntervalMs?: number;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.card;
   const cc = useCardCheckout(order, buyer, providerConfig, onResolved, pollIntervalMs, tenantSlug, providerChain);
   // 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
@@ -141,7 +145,7 @@ export function CardView({
   return (
     <Box data-testid="card-view" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       <Text variant="heading" size="md" weight="bold" as="h2">
-        Pague com cartão
+        {copy.heading}
       </Text>
 
       {cc.savedCards.length > 0 ? (

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

@@ -6,6 +6,7 @@ import { DadosStep, EmptyCart, PaymentStep } from "./checkout-steps";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
+import { CheckoutCopyProvider } from "./copy-context";
 import { CheckoutComponentsProvider, useCheckoutComponents, type CheckoutComponents } from "./ui";
 import type { CheckoutViewCopy } from "./view-copy";
 import { useCheckoutController, type CheckoutHostPorts } from "./use-checkout-controller";
@@ -245,7 +246,9 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
 export function CheckoutFlow({ components, ...props }: CheckoutFlowProps): JSX.Element {
   return (
     <CheckoutComponentsProvider components={components}>
-      <CheckoutFlowBody {...props} />
+      <CheckoutCopyProvider copy={props.copy.screens}>
+        <CheckoutFlowBody {...props} />
+      </CheckoutCopyProvider>
     </CheckoutComponentsProvider>
   );
 }

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

@@ -2,6 +2,7 @@ import { Box } from "@mui/material";
 import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import { BuyerInfoForm } from "./buyer-info-form";
+import { useCheckoutCopy } from "./copy-context";
 import { LockOutlinedIcon } from "./icons";
 import { useMethodChoice } from "./method-choice";
 import { MethodPicker } from "./method-picker";
@@ -345,6 +346,7 @@ export function PaymentStep({
   onResolved,
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
+  const screens = useCheckoutCopy().screens;
   const config = providerConfig ?? null;
   const choice = useMethodChoice(config, method, onMethodChange);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
@@ -381,7 +383,7 @@ export function PaymentStep({
           raised, and two stacked spinners saying the same thing is what the
           buyer actually saw. */}
       {!order && creating && !choice.atProvider ? (
-        <LoadingState variant="spinner" size="md" message="Gerando pagamento…" dataTestId="payment-generating" />
+        <LoadingState variant="spinner" size="md" message={screens.generatingPayment} dataTestId="payment-generating" />
       ) : null}
 
       {!order && method && createError ? (

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

@@ -15,8 +15,14 @@
  *
  * 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.
+ *
+ * Since FUT-760 that default also needs the transport's WORDS, and it takes
+ * them from the checkout's copy context — which is why {@link
+ * useCheckoutClientApi} builds it instead of holding it as a module constant.
+ * No screen passes them: a screen already has the copy provider above it, or
+ * it would not render at all.
  */
-import { createContext, useContext, type JSX, type ReactNode } from "react";
+import { createContext, useContext, useMemo, type JSX, type ReactNode } from "react";
 
 import {
   chargeCard,
@@ -26,22 +32,26 @@ import {
   pollOrderStatus,
   refreshCardPublicKey,
 } from "./client";
+import { useCheckoutCopy } from "./copy-context";
+import type { CheckoutTransportCopy } from "./screens-copy";
 import { createCheckoutClient, 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),
-  chargeWallet: (input) => chargeWallet(input),
-  listInstruments: (tenantSlug) => listSavedCards(tenantSlug),
-  // The vault pair (FUT-183) has no `client.ts` free function to bind — it is
-  // newer than that module. Built lazily from the default transport instead,
-  // which is the same wire: `/api/checkout`, ambient `fetch` resolved per call.
-  beginVault: () => createCheckoutClient().beginVault(),
-  completeVault: (input) => createCheckoutClient().completeVault(input),
-  refreshBrowserKey: (input) => refreshCardPublicKey(input),
-};
+function unboundClient(copy: CheckoutTransportCopy): CheckoutClient {
+  return {
+    getConfig: (tenantSlug) => fetchCheckoutConfig(tenantSlug, copy),
+    getStatus: (ref) => pollOrderStatus(ref, copy),
+    charge: (input) => chargeCard(input, copy),
+    chargeWallet: (input) => chargeWallet(input, copy),
+    listInstruments: (tenantSlug) => listSavedCards(copy, tenantSlug),
+    // The vault pair (FUT-183) has no `client.ts` free function to bind — it is
+    // newer than that module. Built lazily from the default transport instead,
+    // which is the same wire: `/api/checkout`, ambient `fetch` resolved per call.
+    beginVault: () => createCheckoutClient({ copy }).beginVault(),
+    completeVault: (input) => createCheckoutClient({ copy }).completeVault(input),
+    refreshBrowserKey: (input) => refreshCardPublicKey(input, copy),
+  };
+}
 
 const CheckoutClientContext = createContext<CheckoutClient | null>(null);
 
@@ -58,7 +68,9 @@ export function CheckoutClientProvider({
   );
 }
 
-/** The bound client, or the module default when no provider sits above. */
+/** The bound client, or the unbound one when no provider sits above. */
 export function useCheckoutClientApi(): CheckoutClient {
-  return useContext(CheckoutClientContext) ?? DEFAULT_CLIENT;
+  const provided = useContext(CheckoutClientContext);
+  const copy = useCheckoutCopy().screens.transport;
+  return useMemo(() => provided ?? unboundClient(copy), [provided, copy]);
 }

package/src/components/checkout/client.ts

@@ -12,6 +12,12 @@
  * injected `fetch` reaches for `createPaymentFlows({ transport })` instead;
  * nothing about these functions changes when it does.
  *
+ * Each takes the transport's COPY (FUT-760). Unbound is about the mount, not
+ * about the language: a wire failure still has to say something to a buyer,
+ * and the one thing this package must not do is pick those words itself. The
+ * caller is `client-context.tsx`, which reads them from the checkout's copy
+ * context — so no screen passes them by hand.
+ *
  * 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`).
@@ -24,6 +30,7 @@
 import type { SavedCard } from "../../card";
 import type { Result } from "../../result";
 
+import type { CheckoutTransportCopy } from "./screens-copy";
 import { createCheckoutClient } from "./transport";
 import type {
   ChargeCardInput,
@@ -34,14 +41,23 @@ import type {
 } from "./types";
 
 /**
- * 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.
+ * The default binding: `/api/checkout` on the ambient `fetch`, saying what the
+ * caller's copy says when the wire fails.
+ *
+ * Built per call rather than once, because the words are now an argument. It
+ * costs one closure and resolves `fetch` per call either way, so a suite that
+ * stubs the global still wins.
  */
-const defaultClient = createCheckoutClient();
+function defaultClient(copy: CheckoutTransportCopy) {
+  return createCheckoutClient({ copy });
+}
 
 /** Poll an order's reconciled status (async provider webhook confirmation). */
-export async function pollOrderStatus(orderId: string): Promise<Result<OrderStatus>> {
-  return defaultClient.getStatus(orderId);
+export async function pollOrderStatus(
+  orderId: string,
+  copy: CheckoutTransportCopy,
+): Promise<Result<OrderStatus>> {
+  return defaultClient(copy).getStatus(orderId);
 }
 
 /**
@@ -52,8 +68,9 @@ export async function pollOrderStatus(orderId: string): Promise<Result<OrderStat
  */
 export async function fetchCheckoutConfig(
   tenantSlug: string,
+  copy: CheckoutTransportCopy,
 ): Promise<Result<CheckoutProviderConfig>> {
-  return defaultClient.getConfig(tenantSlug);
+  return defaultClient(copy).getConfig(tenantSlug);
 }
 
 /**
@@ -63,10 +80,11 @@ export async function fetchCheckoutConfig(
  * (the web page resolved it server-side) and for the FUT-174 rotated-key
  * self-heal retry.
  */
-export async function refreshCardPublicKey(input: {
-  orderId: string;
-}): Promise<Result<{ publicKey: string | null }>> {
-  return defaultClient.refreshBrowserKey(input);
+export async function refreshCardPublicKey(
+  input: { orderId: string },
+  copy: CheckoutTransportCopy,
+): Promise<Result<{ publicKey: string | null }>> {
+  return defaultClient(copy).refreshBrowserKey(input);
 }
 
 /**
@@ -74,8 +92,11 @@ export async function refreshCardPublicKey(input: {
  * `hostedCheckoutUrl` when the provider demands the buyer finish on its own
  * page (3-D Secure, FUT-698) — the caller then hands the buyer over.
  */
-export async function chargeCard(input: ChargeCardInput): Promise<Result<ChargeOutcome>> {
-  return defaultClient.charge(input);
+export async function chargeCard(
+  input: ChargeCardInput,
+  copy: CheckoutTransportCopy,
+): Promise<Result<ChargeOutcome>> {
+  return defaultClient(copy).charge(input);
 }
 
 /**
@@ -83,11 +104,17 @@ export async function chargeCard(input: ChargeCardInput): Promise<Result<ChargeO
  * `/charge` route as {@link chargeCard}, carrying `wallet: { type, key }` in
  * place of a card token.
  */
-export async function chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>> {
-  return defaultClient.chargeWallet(input);
+export async function chargeWallet(
+  input: ChargeWalletInput,
+  copy: CheckoutTransportCopy,
+): Promise<Result<ChargeOutcome>> {
+  return defaultClient(copy).chargeWallet(input);
 }
 
 /** List saved cards available for reuse (empty on any error — non-blocking). */
-export async function listSavedCards(tenantSlug?: string): Promise<SavedCard[]> {
-  return defaultClient.listInstruments(tenantSlug);
+export async function listSavedCards(
+  copy: CheckoutTransportCopy,
+  tenantSlug?: string,
+): Promise<SavedCard[]> {
+  return defaultClient(copy).listInstruments(tenantSlug);
 }

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

@@ -0,0 +1,83 @@
+'use client';
+
+import { createContext, useContext, type JSX, type ReactNode } from 'react';
+
+import type { CardCopy } from '../../card/copy';
+import type { CheckoutScreensCopy } from './screens-copy';
+
+/**
+ * The buyer checkout's words, for the screens too deep to reach by prop
+ * (FUT-760).
+ *
+ * The existing `CheckoutViewCopy` is a required PROP, and that is still the
+ * right shape for the flow's own screens — a host wiring the checkout passes
+ * it at the one call that mounts them. This context exists for the parts that
+ * prop cannot reach without threading it through four intermediate
+ * components: the card fields, the wallet panes, the method tiles.
+ *
+ * It sits beside `CheckoutComponentsProvider` because the two answer the same
+ * kind of question — a host's design system there, a host's language here —
+ * and a screen that has one always has the other.
+ */
+export interface CheckoutCopy {
+  /** The card form and its tokenizers. */
+  card: CardCopy;
+  /** The buyer-details step's own fields and their refusals. */
+  buyer: BuyerInfoCopy;
+  /**
+   * Everything inside the steps — the method tiles, the PIX and card panes,
+   * the wallet buttons, the hosted handover, and the refusals any of them can
+   * produce.
+   */
+  screens: CheckoutScreensCopy;
+}
+
+/**
+ * The buyer-details step: what it asks for, and what it says when the answer
+ * will not do.
+ */
+export interface BuyerInfoCopy {
+  emailInvalid: string;
+  emailRequired: string;
+  nameRequired: string;
+  phoneRequired: string;
+  /**
+   * The hint above the fields, built from what the store's provider actually
+   * DEMANDS — which fields those are is the package's answer, and it changes
+   * per store.
+   *
+   * A function over the required field names, not a template with a slot: the
+   * sentence agrees its adjective with how many there are ("obrigatório" /
+   * "obrigatórios"), and a `{fields}` hole would have this package deciding
+   * that agreement for every language.
+   */
+  fieldsHint(requiredFieldNames: readonly string[]): string;
+}
+
+const CheckoutCopyContext = createContext<CheckoutCopy | null>(null);
+
+export function CheckoutCopyProvider({
+  copy,
+  children,
+}: {
+  copy: CheckoutCopy;
+  children: ReactNode;
+}): JSX.Element {
+  return <CheckoutCopyContext.Provider value={copy}>{children}</CheckoutCopyContext.Provider>;
+}
+
+/**
+ * The words this checkout renders — THROWS outside a provider rather than
+ * falling back.
+ *
+ * A fallback could only be the origin host's Portuguese, handed silently to
+ * the next adopter's shopper. Failing at the mount is the whole point: it is
+ * the one moment a host can still be told it forgot.
+ */
+export function useCheckoutCopy(): CheckoutCopy {
+  const copy = useContext(CheckoutCopyContext);
+  if (!copy) {
+    throw new Error('useCheckoutCopy must be rendered inside a <CheckoutCopyProvider>');
+  }
+  return copy;
+}