@12-apps/payments-frontend 3.9.0 → 3.11.0

package/src/components/settings-pt-BR.ts

@@ -0,0 +1,172 @@
+import type { PaymentsSettingsCopy } from './settings-copy';
+
+/**
+ * The pt-BR pack for the payments settings surface — a NAMED constant a host
+ * passes by hand, never a default.
+ *
+ * The filename is what exempts this file from the copy-portability gate:
+ * Portuguese may ship, it may not be silent. Every sentence is VERBATIM what
+ * the screen used to render, so a host adopting it sees no change — what
+ * changes is that the words are chosen in a diff.
+ */
+export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
+  status: {
+    verified: 'VERIFICADO',
+    unverified: 'NÃO VERIFICADO',
+    connectionOk: 'CONEXÃO OK',
+    reconnectRequired: 'RECONECTAR',
+    notConnected: 'Não conectado',
+    threeStepsAhead: 'Este provedor só passa a receber vendas depois dos 3 passos abaixo.',
+    connectAndVerifyFirst: 'Conecte e verifique o provedor antes de ativar as vendas.',
+    receiving: {
+      state: 'Recebendo vendas',
+      sub: 'Sua loja está recebendo por este provedor.',
+    },
+    pausedByOwner: {
+      state: 'Pausado',
+      sub: 'Conexão pronta e pausada por você — nenhum pedido novo é cobrado aqui.',
+    },
+    pausedChip: 'Pausado',
+    readyNotReceiving: {
+      state: 'Ainda não está recebendo',
+      sub: 'Tudo pronto — ligue a chave para começar a receber.',
+    },
+  },
+  listBadge: {
+    active: 'Ativo',
+    connected: 'Conectado',
+    reconnect: 'Reconectar',
+    notConnected: 'Não conectado',
+  },
+  environment: {
+    production: 'Produção',
+    sandbox: 'Sandbox',
+    groupLabel: 'Ambiente desta conexão',
+    productionMeaning: 'Produção — dinheiro real.',
+    sandboxMeaning: 'Sandbox — ambiente de teste.',
+    productionConsequence: 'Tudo o que você fizer aqui vale para as vendas da loja.',
+    sandboxConsequence: 'Nenhum valor sai ou entra de verdade.',
+    storeIsUsing: (environmentName) => ` Hoje a loja está usando ${environmentName}.`,
+  },
+  oauth: {
+    connectAction: (displayName) => `Conectar com ${displayName}`,
+    reconnectAction: 'Reconectar',
+    removeAction: 'Remover conexão',
+    invitation: (displayName) =>
+      `Conecte sua conta ${displayName} autorizando o acesso no site do provedor. Nenhuma chave precisa ser copiada.`,
+    roundTripNote: 'Você sai para o provedor e volta para cá — leva menos de um minuto.',
+    connectedExplainer:
+      'Sua conta está conectada. As cobranças são criadas em seu nome — nenhuma chave precisa ser copiada.',
+    connectedNote: (displayName) =>
+      `Conta ${displayName} conectada. Revogue quando quiser, aqui ou no painel do provedor.`,
+    connectedAt: (when) => `Conectada em ${when}`,
+    validUntil: (when) => `Autorização válida até ${when}`,
+    expiredAt: (when) =>
+      `A autorização expirou em ${when}. Reconecte para voltar a receber pagamentos.`,
+    expiresAt: (when) =>
+      `A autorização expira em ${when}. Se o aviso continuar, reconecte a conta.`,
+    revoked: 'A autorização expirou ou foi revogada. Reconecte para voltar a receber pagamentos.',
+    notAvailableHere: (displayName) =>
+      `A conexão automática com ${displayName} não está disponível nesta instalação — ` +
+      'o aplicativo de autorização não foi cadastrado. Para conectar agora, abra ' +
+      '“Prefiro informar as credenciais manualmente” abaixo e cole as suas próprias chaves.',
+    connectUnavailable:
+      'Este provedor conecta por autorização, mas o botão de conexão não está disponível nesta ' +
+      'instalação. Você ainda pode conectar informando as credenciais manualmente.',
+    preferOAuth: 'Prefiro conectar por autorização',
+    preferCredentials: 'Prefiro informar as credenciais manualmente',
+    scopes: {
+      read: 'Consultar pagamentos',
+      create: 'Criar cobranças',
+      refund: 'Estornar pagamentos',
+      account: 'Consultar dados da conta',
+    },
+  },
+  card: {
+    accountHeading: (displayName) => `Conta ${displayName}`,
+    accountLabel: 'Conta',
+    connectionLabel: 'Conexão',
+    authorizedAt: (displayName) => `Autorizada no ${displayName}`,
+    environmentLabel: 'Ambiente',
+    connectedAtLabel: 'Conectada em',
+    sandboxWithNote: 'Sandbox (testes)',
+    steps: {
+      signIn: (displayName) =>
+        `Entre na sua conta ${displayName} — dá para criar uma na hora, se ainda não tiver.`,
+      authorize: 'Autorize o acesso na tela do provedor.',
+      comeBack: 'Você volta para cá com a conta conectada.',
+    },
+    removeAction: 'Remover conexão',
+    removeQuestion: (displayName) => `Remover a conexão com ${displayName}?`,
+    removeConsequenceLive:
+      'A loja para de receber na hora e fica sem provedor ativo — pedidos novos não conseguem ser pagos até você conectar outro.',
+    removeConsequenceIdle: 'Esta conexão sai da loja. Você pode conectar de novo depois.',
+    removeStopsChargingNow: 'Pedidos novos deixam de ser cobrados imediatamente.',
+    removeRevokes: (displayName) =>
+      `A autorização é revogada no ${displayName}. Sua conta e seu histórico continuam lá, intactos.`,
+    removeKeepsSettled: (displayName) =>
+      `Pagamentos já aprovados e estornos em andamento seguem normalmente pelo ${displayName}.`,
+    removeRestartsSetup: 'Para reconectar, os passos recomeçam do zero.',
+    pauseInstead: 'Só pausar o recebimento',
+    cancel: 'Cancelar',
+  },
+  credentials: {
+    configuredKeepBlank: 'Configurado — deixe em branco para manter o valor atual.',
+    advancedSuffix: ' · só para plataformas Connect',
+    probeAction: 'Testar conexão',
+    reverifyWarning: (displayName) =>
+      `Esta loja já está verificada. Trocar as credenciais **exige uma nova verificação** ` +
+      `e a loja **para de receber** pelo ${displayName} até que ela termine.`,
+    probeRunning: 'Testando a conexão…',
+    probeSaveNote: 'Salvamos e testamos as chaves no provedor antes de seguir.',
+    probeIncompleteNote: 'Guardamos o que você já preencheu. Complete os campos para testar.',
+    probeFailed: (environmentName) =>
+      `Não foi possível conectar em ${environmentName}. Confira as credenciais deste ambiente.`,
+    checkPass: 'Verificado',
+    checkFail: 'Corrigir',
+    uncheckable: 'Não verificável',
+    saveAndTest: 'Salvar e testar conexão',
+    save: 'Salvar',
+    saveOnly: (fieldLabel) => `Salvar ${fieldLabel}`,
+    changeAction: 'Alterar',
+  },
+  priority: {
+    moveUp: (label) => `Mover ${label} para cima`,
+    moveDown: (label) => `Mover ${label} para baixo`,
+    saveFailed: 'Não foi possível salvar a ordem.',
+    firstInChain: 'primeiro',
+    orderHeading: 'Ordem de tentativa',
+    chainExplainer: (firstProviderLabel) =>
+      `O checkout tenta **${firstProviderLabel}** primeiro. Se uma cobrança falhar por motivo ` +
+      'técnico, ele tenta o próximo da lista — mas só quando é possível comprovar que a ' +
+      'tentativa anterior não gerou cobrança.',
+    noneActive:
+      'Nenhum provedor está ativo. O checkout não conseguirá cobrar até que você ative ao menos um.',
+    retryDeclinedLabel: 'Tentar cartão **recusado** no próximo provedor',
+    retryDeclinedOn:
+      'Uma recusa passa para o próximo da lista. Isso pode aumentar custos de transação e sinais de fraude.',
+    retryDeclinedOff:
+      'Padrão: uma recusa encerra a cobrança. Só falhas técnicas passam para o próximo.',
+  },
+  providerList: {
+    heading: 'Escolha o provedor de pagamento',
+    subheading: 'Selecione onde sua loja recebe — a configuração é feita sob medida para ele.',
+  },
+  confirmSave: {
+    title: 'Confirme para onde vai o dinheiro',
+    body: (fieldLabel) =>
+      `Todo pagamento recebido por esta loja será depositado na conta desta ${fieldLabel}:`,
+    fieldFallback: 'credencial',
+    warning:
+      'Um valor errado envia os pagamentos desta loja para outra pessoa, e não há como reverter.',
+    cancelAction: 'Voltar e revisar',
+    confirmAction: 'É essa, salvar',
+  },
+  setupGuide: {
+    defaultConfirmLabel: 'Já habilitei o Checkout Integrado',
+    confirmedByYou: 'Confirmado por você',
+    reviewAction: 'Revisar',
+    copyValue: (fieldLabel) => `Copiar ${fieldLabel}`,
+    copied: 'Copiado',
+  },
+};

package/src/flows/copy.ts

@@ -89,4 +89,16 @@ export interface CheckoutCopyFE {
   manageCardsTitle: string;
   manageCardsEmpty: string;
   manageCardsAdd: string;
+  /**
+   * How a card on file READS — the network's name when the provider shared
+   * none, and the expiry line beside it.
+   *
+   * Both were Portuguese literals inside this screen ("Cartão", "Validade
+   * MM/AAAA"), which is the whole of what a buyer sees of a saved card when
+   * the provider is stingy with metadata. `cardExpiry` is a function because
+   * the order of month and year, and whether the word leads or trails, is the
+   * translator's call — the two numbers arrive already padded.
+   */
+  cardUnknownBrand: string;
+  cardExpiry(month: string, year: number): string;
 }

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

@@ -40,7 +40,14 @@ const ALWAYS_PAYABLE: CheckoutAvailability = { payable: true };
 
 /** Build the runtime every screen closes over. */
 function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
-  const client = createCheckoutClient(config.transport);
+  // The transport's own failure sentences come from the SAME copy pack the
+  // screens read (FUT-760), so a host answers the question once. A `transport`
+  // that names its own `copy` still wins — a second mount may talk to a
+  // different surface with a different voice.
+  const client = createCheckoutClient({
+    copy: config.copy.views.screens.screens.transport,
+    ...config.transport,
+  });
   const navigate =
     config.ports.navigate ??
     ((url: string) => {

package/src/flows/runtime.tsx

@@ -27,6 +27,7 @@ import { CheckoutClientProvider } from "../components/checkout/client-context";
 import { CheckoutNavigateProvider } from "../components/checkout/navigate-context";
 import type { CheckoutClient } from "../components/checkout/transport";
 import type { CheckoutProviderConfig } from "../components/checkout/types";
+import { CheckoutCopyProvider } from "../components/checkout/copy-context";
 import { CheckoutComponentsProvider } from "../components/checkout/ui";
 
 import type { CheckoutCopyFE } from "./copy";
@@ -102,7 +103,7 @@ export function useResolvedConfig(runtime: FlowsRuntime): CheckoutConfigState {
   return provided ?? own;
 }
 
-/** Slots, transport and the navigate port — what a screen cannot work without. */
+/** Slots, WORDS, transport and the navigate port — what a screen cannot work without. */
 export function FlowsShell({
   runtime,
   children,
@@ -112,9 +113,16 @@ export function FlowsShell({
 }): JSX.Element {
   return (
     <CheckoutComponentsProvider components={runtime.config.components}>
-      <CheckoutClientProvider client={runtime.client}>
-        <CheckoutNavigateProvider navigate={runtime.navigate}>{children}</CheckoutNavigateProvider>
-      </CheckoutClientProvider>
+      {/* The factory's STANDALONE screens (add-card, manage-cards) render the
+          same card fields the checkout does, so they need the same words —
+          and they are mounted here rather than under `CheckoutFlow`. */}
+      <CheckoutCopyProvider copy={runtime.config.copy.views.screens}>
+        <CheckoutClientProvider client={runtime.client}>
+          <CheckoutNavigateProvider navigate={runtime.navigate}>
+            {children}
+          </CheckoutNavigateProvider>
+        </CheckoutClientProvider>
+      </CheckoutCopyProvider>
     </CheckoutComponentsProvider>
   );
 }

package/src/flows/screens-vault.tsx

@@ -29,15 +29,15 @@ import type { CheckoutScreens } from "./types";
 import { useAddCard, type AddCardController } from "./use-add-card";
 
 /** `visa •••• 4242`, or just the brand when the provider shared no last4. */
-function displayLabel(display: VaultedCardDisplay): string {
-  const brand = display.brand ?? "Cartão";
+function displayLabel(copy: CheckoutCopyFE, display: VaultedCardDisplay): string {
+  const brand = display.brand ?? copy.cardUnknownBrand;
   return display.last4 ? `${brand} •••• ${display.last4}` : brand;
 }
 
 /** `Validade 12/2031`, or nothing when the provider shared no expiry. */
-function expiryLabel(display: VaultedCardDisplay): string | null {
+function expiryLabel(copy: CheckoutCopyFE, display: VaultedCardDisplay): string | null {
   if (display.expMonth === null || display.expYear === null) return null;
-  return `Validade ${String(display.expMonth).padStart(2, "0")}/${display.expYear}`;
+  return copy.cardExpiry(String(display.expMonth).padStart(2, "0"), display.expYear);
 }
 
 /** The card is on file — display metadata only, never the vault token. */
@@ -49,7 +49,7 @@ function SavedConfirmation({
   copy: CheckoutCopyFE;
 }): JSX.Element {
   const { Alert, Text } = useCheckoutComponents();
-  const expiry = expiryLabel(display);
+  const expiry = expiryLabel(copy, display);
   return (
     <Box data-testid="add-card-saved" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       <Alert
@@ -60,7 +60,7 @@ function SavedConfirmation({
       />
       <Box>
         <Text variant="body" size="sm" weight="semibold" as="p">
-          {displayLabel(display)}
+          {displayLabel(copy, display)}
         </Text>
         {expiry ? (
           <Text variant="caption" size="xs" color="secondary" as="p">
@@ -195,12 +195,12 @@ function useInstrumentList(
 }
 
 /** The list itself, or the empty-state sentence. Read-only by design. */
-function CardList({ cards, emptyCopy }: { cards: SavedCard[]; emptyCopy: string }): JSX.Element {
+function CardList({ cards, copy }: { cards: SavedCard[]; copy: CheckoutCopyFE }): JSX.Element {
   const { Text } = useCheckoutComponents();
   if (cards.length === 0) {
     return (
       <Text variant="body" size="sm" color="secondary" as="p" data-testid="manage-cards-empty">
-        {emptyCopy}
+        {copy.manageCardsEmpty}
       </Text>
     );
   }
@@ -213,7 +213,7 @@ function CardList({ cards, emptyCopy }: { cards: SavedCard[]; emptyCopy: string
           </Text>
           {card.expMonth && card.expYear ? (
             <Text variant="caption" size="xs" color="secondary" as="p">
-              {`Validade ${String(card.expMonth).padStart(2, "0")}/${card.expYear}`}
+              {copy.cardExpiry(String(card.expMonth).padStart(2, "0"), card.expYear)}
             </Text>
           ) : null}
         </Box>
@@ -235,7 +235,7 @@ function ManageCardsBody({ runtime }: { runtime: FlowsRuntime }): JSX.Element {
       <Text variant="heading" size="md" weight="bold" as="h2">
         {copy.manageCardsTitle}
       </Text>
-      {pending ? null : <CardList cards={cards} emptyCopy={copy.manageCardsEmpty} />}
+      {pending ? null : <CardList cards={cards} copy={copy} />}
       {adding ? (
         <AddCardSection runtime={runtime} onSaved={() => setRefresh((count) => count + 1)} />
       ) : (

package/src/flows/types.ts

@@ -37,7 +37,10 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "../components/checkout/types";
-import type { CheckoutTransport, VaultedCardDisplay } from "../components/checkout/transport";
+import type {
+  CheckoutTransportBinding,
+  VaultedCardDisplay,
+} from "../components/checkout/transport";
 import type { useCheckoutController } from "../components/checkout/use-checkout-controller";
 import type { Result } from "../result";
 
@@ -88,7 +91,7 @@ export interface CheckoutPorts {
 /** What `createPaymentFlows` is configured with. */
 export interface PaymentFlowsConfig {
   /** Where the `createPaymentFlowsBE` mount lives. Default `/api/checkout`. */
-  transport?: CheckoutTransport;
+  transport?: CheckoutTransportBinding;
 
   /**
    * The store being paid. A HOOK because the host's router owns it: taking a

package/src/flows/use-add-card.ts

@@ -143,11 +143,12 @@ export function useAddCard(
 
   const brand = detectBrand(onlyDigits(card.number));
 
+  const fieldCopy = runtime.copy.views.screens.card.fields;
   const validate = (): CardFieldErrors => ({
-    number: validateCardNumber(card.number),
-    holder: validateHolder(card.holder),
-    expiry: validateExpiry(card.expiry),
-    cvv: validateCvv(card.cvv, brand),
+    number: validateCardNumber(card.number, fieldCopy),
+    holder: validateHolder(card.holder, fieldCopy),
+    expiry: validateExpiry(card.expiry, fieldCopy),
+    cvv: validateCvv(card.cvv, fieldCopy, brand),
   });
 
   const submit = async (): Promise<void> => {
@@ -158,7 +159,11 @@ export function useAddCard(
     if (Object.values(errors).some(Boolean)) return;
 
     setSaving(true);
-    const minted = await tokenizeForCheckout(card, sessionTokenization(phase.session, config));
+    const minted = await tokenizeForCheckout(
+      card,
+      sessionTokenization(phase.session, config),
+      runtime.copy.views.screens.card,
+    );
     if (!minted.ok) {
       setError(minted.error);
       setSaving(false);

package/src/index.ts

@@ -37,6 +37,17 @@ export {
   type CheckoutPaymentProps,
   type SavedCardOption,
 } from './components/CheckoutPayment';
+// The words that step renders — required on the prop above, so a host wiring
+// the legacy surface has to answer them (FUT-760).
+export type {
+  CheckoutPaymentCopy,
+  LegacyCardCopy,
+  LegacyMethodCopy,
+  LegacyMoneyCopy,
+  LegacyPixCopy,
+  LegacyRefusalCopy,
+} from './components/checkout-payment-copy';
+export { PT_BR_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-pt-BR';
 
 // ---------------------------------------------------------------------------
 // The buyer checkout surface (FUT-564) — the storefront's three-step flow,
@@ -80,6 +91,7 @@ export {
   type BuyerVaultSession,
   type CheckoutClient,
   type CheckoutTransport,
+  type CheckoutTransportBinding,
   type CompleteVaultInput,
   type VaultedCardDisplay,
 } from './components/checkout/transport';
@@ -98,9 +110,37 @@ export type {
   StatusOutcomeCopy,
 } from './components/checkout/view-copy';
 export {
+  PT_BR_CHECKOUT_COPY,
   PT_BR_CHECKOUT_VIEW_COPY,
   PT_BR_PAYMENT_STATUS_COPY,
 } from './components/checkout/pt-BR';
+// The provider the card fields and buyer inputs read their words from — a host
+// mounting a screen BELOW `CheckoutFlow` (or composing by hand) opens it
+// itself; `CheckoutFlow` and `FlowsShell` already do (FUT-760).
+export {
+  CheckoutCopyProvider,
+  useCheckoutCopy,
+  type BuyerInfoCopy,
+  type CheckoutCopy,
+} from './components/checkout/copy-context';
+// The screens BELOW the steps — the method tiles, the PIX and card panes, the
+// wallet buttons, the hosted handover and the transport's own three sentences.
+// Every slice is named on the barrel, not just the whole: a host writing its
+// pack section by section types the section it is writing (FUT-760).
+export type {
+  CardPaneCopy,
+  CheckoutScreensCopy,
+  CheckoutTransportCopy,
+  CheckoutValidationCopy,
+  HostedHandoverCopy,
+  MethodPickerCopy,
+  PayerSummaryCopy,
+  PaymentErrorCopy,
+  PixPaneCopy,
+  SettlingCopy,
+  WalletCopy,
+} from './components/checkout/screens-copy';
+export { PT_BR_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-pt-BR';
 export { fetchCheckoutConfig } from './components/checkout/client';
 /**
  * The `sessionStorage` key the hosted-checkout return leg parks the raised
@@ -199,7 +239,11 @@ export {
   validateExpiry,
   validateHolder,
   NEW_CARD,
+  PT_BR_CARD_COPY,
   type CardBrand,
+  type CardCopy,
+  type CardFieldCopy,
+  type CardTokenizeCopy,
   type CardDetails,
   type CardFieldErrors,
   type CardToken,
@@ -207,6 +251,25 @@ export {
   type CardTokenizer,
   type SavedCard,
 } from './card';
+// The settings surface's words. `PaymentProviderSettings` takes the pack as a
+// required prop and mounts the provider; the provider is exported for a host
+// that composes the pieces itself (FUT-760).
+export {
+  PaymentsSettingsCopyProvider,
+  usePaymentsSettingsCopy,
+} from './components/settings-copy-context';
+export { PT_BR_PAYMENTS_SETTINGS_COPY } from './components/settings-pt-BR';
+export type {
+  ConnectionBadgeCopy,
+  ConnectionCardCopy,
+  ConnectionStatusCopy,
+  CredentialFormCopy,
+  EnvironmentCopy,
+  OAuthConnectionCopy,
+  PaymentsSettingsCopy,
+  ProviderPriorityCopy,
+  SetupGuideCopy,
+} from './components/settings-copy';
 export {
   ProviderConnection,
   type ProviderConnectionProps,