@12-apps/payments-frontend 3.29.0 → 3.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "type": "module",
   "sideEffects": false,
   "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.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.29.0",
+    "@12-apps/payments-backend": "^4.30.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/CredentialFieldStack.tsx

@@ -6,6 +6,7 @@ import type { PaymentEnvironment, ProviderDescriptor } from '@12-apps/payments-b
 
 import { CredentialField } from './CredentialFields';
 import { appliesIn, saveLabel } from './credential-rules';
+import { checksLocally } from './checks-locally';
 import { FormActions, ReverifyWarning } from './CredentialFormAlerts';
 import type { CredentialFormState } from './ProviderCredentialForm';
 import { usePaymentsSettingsCopy } from './settings-copy-context';
@@ -58,6 +59,7 @@ export function CredentialFields({
         willTest={form.complete}
         disabled={form.nothingEdited || !form.valid}
         onSave={form.requestSave}
+        local={checksLocally(descriptor)}
       />
     </Stack>
   );

package/src/components/CredentialFields.tsx

@@ -116,9 +116,11 @@ export function CredentialField({ spec, state, value, onChange, check }: Credent
         sx={{ display: 'block', fontSize: '12px', fontWeight: 650, color: T.ink2, mb: '5px' }}
       >
         {spec.label}
-        {spec.advanced ? (
-          <Box component="span" sx={{ fontWeight: 500, color: T.ink4 }}>
-            {copy.advancedSuffix}
+        {spec.advanced || spec.optional ? (
+          // `ink3`, not `ink4`: "opcional" carries real information, and at 12px
+          // the lighter ink fell under AA contrast.
+          <Box component="span" sx={{ fontWeight: 500, color: spec.optional ? T.ink3 : T.ink4 }}>
+            {spec.advanced ? copy.advancedSuffix : copy.optionalSuffix}
           </Box>
         ) : null}
       </Typography>

package/src/components/CredentialFormAlerts.tsx

@@ -189,12 +189,20 @@ export function ReverifyWarning({ displayName }: { displayName: string }) {
  * Nothing is learned by separating them: the probe reads what was just stored,
  * so the only useful moment to run it is immediately after a save.
  */
+/** What the bar promises: testing now, what a save will do, or that it only writes down. */
+function barMessage(copy: CredentialFormCopy, verifying: boolean, willTest: boolean, local: boolean): string {
+  if (verifying) return (local ? copy.probeLocalRunning : undefined) ?? copy.probeRunning;
+  if (!willTest) return copy.probeIncompleteNote;
+  return (local ? copy.probeLocalSaveNote : undefined) ?? copy.probeSaveNote;
+}
+
 export function FormActions({
   busy,
   label,
   willTest,
   disabled,
   onSave,
+  local = false,
 }: {
   busy: string | null;
   label: string;
@@ -202,17 +210,14 @@ export function FormActions({
   willTest: boolean;
   disabled: boolean;
   onSave: () => void;
+  /** The "test" is a local check (`checksLocally`): nothing is sent to a provider. */
+  local?: boolean;
 }) {
   // The bar states what pressing it costs, which is the half a verb cannot
   // carry: a complete set is sent to the provider on save, and a partial one is
   // only written down. The owner reads the promise and the button in one line.
   const copy = usePaymentsSettingsCopy().credentials;
-  const message =
-    busy === 'verify'
-      ? copy.probeRunning
-      : willTest
-        ? copy.probeSaveNote
-        : copy.probeIncompleteNote;
+  const message = barMessage(copy, busy === 'verify', willTest, local);
 
   return (
     <Box sx={BAR_SX} data-testid="payments-form-bar">

package/src/components/ProviderPanel.tsx

@@ -226,12 +226,49 @@ function oauthWalkthrough(props: ActivePanelProps, path: 'oauth' | 'credentials'
  * a FUNCTION: which steps to show depends on the disclosure, whose state lives
  * in `OAuthPanel`.
  */
+/** The one environment a provider has, when it declares a single one. */
+function soleEnvironment(descriptor: ActivePanelProps['descriptor']): PaymentEnvironment | null {
+  // Read defensively: a host-built descriptor (and many fixtures) may carry no capabilities at all.
+  const declared = (descriptor.capabilities as typeof descriptor.capabilities | undefined)?.environments;
+  return declared && declared.length === 1 ? (declared[0] ?? null) : null;
+}
+
+/**
+ * The environment selector and its notice — full-bleed across the card, and
+ * inset for the manual disclosure, where it no longer spans anything (see
+ * `EnvironmentNotice`). A provider with ONE environment (no sandbox: every code
+ * is real money) gets neither: there is nothing to choose, and a "test
+ * environment" notice would promise that no money moves.
+ */
+function environmentChrome(
+  sole: PaymentEnvironment | null,
+  environment: PaymentEnvironment,
+  onChange: (next: PaymentEnvironment) => void,
+  active: PaymentEnvironment | null,
+): { selector: ReactNode; band: ReactNode; notice: ReactNode } {
+  // Nothing to choose with one environment. The notice goes only for a
+  // PRODUCTION-only provider (it would promise no money moves); a sandbox-only
+  // one keeps its truthful "nothing is real" notice.
+  if (sole === 'PRODUCTION') return { selector: null, band: undefined, notice: null };
+  if (sole) {
+    return {
+      selector: null,
+      band: <EnvironmentNotice environment={environment} active={active} />,
+      notice: <EnvironmentNotice environment={environment} active={active} band={false} />,
+    };
+  }
+  return {
+    selector: <EnvironmentSelector environment={environment} onChange={onChange} />,
+    band: <EnvironmentNotice environment={environment} active={active} />,
+    notice: <EnvironmentNotice environment={environment} active={active} band={false} />,
+  };
+}
+
 export function ActivePanel(props: ActivePanelProps) {
   const { descriptor, config, client, onChanged, reload, guide, verification } = props;
   const statusBar = <EnableBar {...props} />;
-  const [environment, setEnvironment] = useState<PaymentEnvironment>(
-    config?.environment ?? 'SANDBOX',
-  );
+  const sole = soleEnvironment(descriptor);
+  const [environment, setEnvironment] = useState<PaymentEnvironment>(sole ?? config?.environment ?? 'SANDBOX');
   const [editing, setEditing] = useState(false);
 
   const oauthConnect = oauthWithConnect(props);
@@ -251,12 +288,7 @@ export function ActivePanel(props: ActivePanelProps) {
     />
   );
 
-  const selector = <EnvironmentSelector environment={environment} onChange={setEnvironment} />;
-  // Full-bleed across the card, and the same notice inset for the manual
-  // disclosure, where it no longer spans anything. See `EnvironmentNotice`.
-  const active = config?.environment ?? null;
-  const band = <EnvironmentNotice environment={environment} active={active} />;
-  const notice = <EnvironmentNotice environment={environment} active={active} band={false} />;
+  const { selector, band, notice } = environmentChrome(sole, environment, setEnvironment, config?.environment ?? null);
 
   const storedHere = requiredStored(descriptor, config, environment);
 

package/src/components/ProviderStatusBar.tsx

@@ -5,6 +5,7 @@ import { Box, Stack, Switch, Tooltip, Typography } from '@mui/material';
 import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
 
 import { certificateExpiryProximity, isConnected } from './connection-state';
+import { checksLocally } from './checks-locally';
 import { T } from './panel-tokens';
 import type { ConnectionStatusCopy } from './settings-copy';
 import { usePaymentsSettingsCopy } from './settings-copy-context';
@@ -54,7 +55,9 @@ export function statusBadge(
   if (config?.status === 'RECONNECT_REQUIRED') {
     return { label: copy.reconnectRequired, color: 'error' };
   }
-  if (isConnected(config)) return { label: copy.connectionOk, color: 'info' };
+  if (isConnected(config)) {
+    return { label: (checksLocally(descriptor) ? copy.detailsOk : undefined) ?? copy.connectionOk, color: 'info' };
+  }
   // A FAILED probe lands here, and it says NÃO VERIFICADO like every other
   // not-yet-connected state. `FALHOU` was a third word for the same fact — the
   // store cannot take money through this provider yet — and it was the only
@@ -125,7 +128,7 @@ function toggleGate(
   if (!lockedOff) return { lockedOff, hint: '' };
   return {
     lockedOff,
-    hint: provable ? copy.threeStepsAhead : copy.connectAndVerifyFirst,
+    hint: provable ? copy.threeStepsAhead : ((checksLocally(descriptor) ? copy.checkDetailsFirst : undefined) ?? copy.connectAndVerifyFirst),
   };
 }
 

package/src/components/SetupGuideSection.tsx

@@ -186,12 +186,25 @@ export function SetupGuideSection({
   // have to render: they are the credential form, and swallowing them left a
   // provider with a status chip, a pair of environment tabs and no way to type
   // anything in.
+  // They take the card's 20px inset themselves, as every block in its
+  // unpadded body does (`ProviderCard`) — a guide's step panel carries it for
+  // them, and without one the boxes ran into the card's edges.
   if (!guide) {
     return (
-      <>
+      // The save bar and the saved-details row carry their own inset for the
+      // guided layout; here the wrapper already supplies it, so theirs is zeroed
+      // and their rule, text and button line up with the fields.
+      <Box
+        data-testid="payments-setup-unguided"
+        sx={{
+          px: '20px',
+          '& [data-testid="payments-form-bar"]': { px: 0 },
+          '& [data-testid="payments-credential-summary"]': { mx: 0 },
+        }}
+      >
         {rows}
         {sectionFooter}
-      </>
+      </Box>
     );
   }
 

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

@@ -59,11 +59,14 @@ interface LiveWait {
 type LoopRef = { readonly current: PollLoop | null };
 
 /**
- * Ask now — and if the loop declines because it asked a moment ago, ask again
- * once that quiet window is over. The window exists so a flapping network does
- * not stampede `/status`; a hint is different, because the ask it lands just
- * after may have been answered BEFORE the order moved. Dropping it would leave
- * the buyer on the live floor with the news already sent.
+ * A channel that DROPS: ask now — and if the loop declines because it asked a
+ * moment ago, ask again once that quiet window is over. The ask it lands just
+ * after may have been answered before the drop, and its next tick sleeps out
+ * the live floor, so declining for good would leave the buyer waiting with
+ * nobody left to wake them.
+ *
+ * A HINT does not come here. It is `PollLoop.hint` (FUT-3205): deferring a
+ * hint by the quiet window cost a paid buyer a full second on the pay step.
  */
 function wake(loop: LoopRef, pending: { timer?: ReturnType<typeof setTimeout> }): void {
   if (loop.current?.poke() !== false) return;
@@ -94,7 +97,7 @@ export function useLiveWait(loop: LoopRef): LiveWait {
   useEffect(() => {
     if (!subscribe) return undefined;
     const retry = pending.current;
-    const unsubscribe = subscribe(() => wake(loop, retry));
+    const unsubscribe = subscribe(() => loop.current?.hint());
     return () => {
       unsubscribe();
       clearTimeout(retry.timer);

package/src/components/checkout/poll-delay.ts

@@ -0,0 +1,54 @@
+import { withLive } from "./poll-live";
+import type { PollingOptions } from "./poll-loop";
+
+/**
+ * How long a payment wait sleeps before its next ask — pure functions of the
+ * options and the run's counters, split out of `poll-loop.ts` so the loop
+ * stays one question: WHEN to ask, not how long.
+ */
+
+/**
+ * The slowest a failing poll may go (FUT-1144).
+ *
+ * Consecutive failures double the delay — 2.5 s, 5 s, 10 s — and stop there.
+ * The cap is what keeps the recovery cheap: a shopper whose signal comes back
+ * during a Wi-Fi→4G handoff waits at most this long to be told they paid, and
+ * the re-arm events (`poll-rearm.ts`) usually beat it outright.
+ */
+const MAX_ERROR_BACKOFF_MS = 10_000;
+
+/**
+ * How long before the next ask, given how many healthy polls have happened.
+ *
+ * A pure function of the options, so it lives out here rather than inside the
+ * effect — the hook is at its size gate, and a scheduling RULE is easier to
+ * read (and to test) stated once than threaded through a closure.
+ *
+ * Reads the count AFTER the poll just made, so the slow phase begins on the
+ * poll FOLLOWING the threshold rather than one early: a wait described as "N
+ * fast polls" has to actually make N of them.
+ */
+function healthyDelay(healthy: number, options: PollingOptions): number {
+  const { intervalMs = 2500, slowAfterPolls, slowIntervalMs } = options;
+  const backingOff =
+    slowAfterPolls !== undefined && slowIntervalMs !== undefined && healthy >= slowAfterPolls;
+  return withLive(backingOff ? slowIntervalMs : intervalMs, options);
+}
+
+/**
+ * The same rule with consecutive FAILURES folded in (FUT-1144).
+ *
+ * Errors never stop the wait, they only slow it. Doubling from the healthy
+ * cadence is what makes a ten-second blip cost one extra beat instead of the
+ * whole confirmation: four failures used to be terminal, and four failures is
+ * what a Wi-Fi→4G handoff produces at the default 2.5 s.
+ *
+ * The cap is `MAX_ERROR_BACKOFF_MS` or the healthy cadence, whichever is
+ * larger — a failing poll must never ask FASTER than a succeeding one, which
+ * is what a bare cap would do to a consumer whose slow interval is longer.
+ */
+export function pollDelay(healthy: number, errors: number, options: PollingOptions): number {
+  const base = healthyDelay(healthy, options);
+  if (errors === 0) return base;
+  return Math.min(base * 2 ** (errors - 1), Math.max(base, MAX_ERROR_BACKOFF_MS));
+}

package/src/components/checkout/poll-hint.ts

@@ -0,0 +1,58 @@
+import { claimRearm, REARM_QUIET_MS } from "./poll-rearm";
+
+/**
+ * What a realtime hint does to a running payment wait (FUT-3205).
+ *
+ * A hint is NOT a re-arm. `poke`'s quiet window exists to collapse
+ * `visibilitychange` and `online` bursts, and a hint is a server fact.
+ * Deferring it by that window cost a paid buyer a full second on the pay step
+ * (P-040: the hint at 12,145 ms, the second read at 13,148 ms). So, by the
+ * loop's state:
+ *
+ * - The wait ended (settled, stopped, cancelled): nothing (FUT-1144).
+ * - No ask in flight: ask now.
+ * - An ask in flight for `REARM_QUIET_MS` or longer: supersede it the way
+ *   `poke` does, within `claimRearm`'s budget — the hung-socket case (FUT-1259).
+ * - Otherwise, or with that budget spent: keep the ask and MARK the run. One
+ *   more ask is owed the moment it answers non-terminal, so a hint is never
+ *   dropped (FUT-649), and a burst of hints during one ask costs one extra ask.
+ *
+ * The mark is cleared by `restart`, by a `poke` that supersedes the marked
+ * ask, by sending its follow-up and by a terminal answer. The deadline does
+ * NOT clear it: a marked ask answering after the deadline is caught by
+ * {@link owedAfterAnswer} and neither asks nor schedules.
+ *
+ * Structural state, as in `poll-rearm.ts`: the loop's run satisfies it.
+ */
+interface HintState {
+  cancelled: boolean;
+  settled: boolean;
+  stopped: boolean;
+  inFlight: boolean;
+  askedAt: number;
+  supersededAsks: number;
+  hinted: boolean;
+}
+
+/** Take a hint: whether the loop must ask now. Marks the run when it may not. */
+export function claimHint(run: HintState): boolean {
+  if (run.cancelled || run.settled || run.stopped) return false;
+  const young = run.inFlight && Date.now() - run.askedAt < REARM_QUIET_MS;
+  if (!run.inFlight || (!young && claimRearm(run))) {
+    run.hinted = false;
+    return true;
+  }
+  run.hinted = true;
+  return false;
+}
+
+/**
+ * After a non-terminal answer: `"ask"` when a mark owes one more ask now,
+ * `"ended"` when the wait stopped while that ask was out, `"none"` when nothing
+ * is owed and the loop schedules as usual. Clears the mark.
+ */
+export function owedAfterAnswer(run: Pick<HintState, "hinted" | "stopped">): "ask" | "ended" | "none" {
+  if (!run.hinted) return "none";
+  run.hinted = false;
+  return run.stopped ? "ended" : "ask";
+}

package/src/components/checkout/poll-loop.ts

@@ -1,5 +1,7 @@
 import type { Result } from "../../result";
-import { waitsForDeadline, withLive, type LiveCadence } from "./poll-live";
+import { pollDelay } from "./poll-delay";
+import { waitsForDeadline, type LiveCadence } from "./poll-live";
+import { claimHint, owedAfterAnswer } from "./poll-hint";
 import { claimRearm } from "./poll-rearm";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
@@ -64,16 +66,6 @@ export interface PollingOptions extends LiveCadence {
   slowIntervalMs?: number;
 }
 
-/**
- * The slowest a failing poll may go (FUT-1144).
- *
- * Consecutive failures double the delay — 2.5 s, 5 s, 10 s — and stop there.
- * The cap is what keeps the recovery cheap: a shopper whose signal comes back
- * during a Wi-Fi→4G handoff waits at most this long to be told they paid, and
- * the two re-arm events below usually beat it outright.
- */
-const MAX_ERROR_BACKOFF_MS = 10_000;
-
 /**
  * How long ONE status ask may take before the loop stops waiting on it.
  *
@@ -92,42 +84,6 @@ const DEFAULT_ASK_TIMEOUT_MS = 15_000;
  */
 const ASK_TIMED_OUT = "timeout";
 
-/**
- * How long before the next ask, given how many healthy polls have happened.
- *
- * A pure function of the options, so it lives out here rather than inside the
- * effect — the hook is at its size gate, and a scheduling RULE is easier to
- * read (and to test) stated once than threaded through a closure.
- *
- * Reads the count AFTER the poll just made, so the slow phase begins on the
- * poll FOLLOWING the threshold rather than one early: a wait described as "N
- * fast polls" has to actually make N of them.
- */
-function healthyDelay(healthy: number, options: PollingOptions): number {
-  const { intervalMs = 2500, slowAfterPolls, slowIntervalMs } = options;
-  const backingOff =
-    slowAfterPolls !== undefined && slowIntervalMs !== undefined && healthy >= slowAfterPolls;
-  return withLive(backingOff ? slowIntervalMs : intervalMs, options);
-}
-
-/**
- * The same rule with consecutive FAILURES folded in (FUT-1144).
- *
- * Errors never stop the wait, they only slow it. Doubling from the healthy
- * cadence is what makes a ten-second blip cost one extra beat instead of the
- * whole confirmation: four failures used to be terminal, and four failures is
- * what a Wi-Fi→4G handoff produces at the default 2.5 s.
- *
- * The cap is `MAX_ERROR_BACKOFF_MS` or the healthy cadence, whichever is
- * larger — a failing poll must never ask FASTER than a succeeding one, which
- * is what a bare cap would do to a consumer whose slow interval is longer.
- */
-function pollDelay(healthy: number, errors: number, options: PollingOptions): number {
-  const base = healthyDelay(healthy, options);
-  if (errors === 0) return base;
-  return Math.min(base * 2 ** (errors - 1), Math.max(base, MAX_ERROR_BACKOFF_MS));
-}
-
 /** Where a running wait writes what it has learned. */
 export interface PollSink {
   setStatus: (status: OrderStatus) => void;
@@ -166,6 +122,8 @@ function newRun() {
     askedAt: 0,
     /** Live asks abandoned by a re-arm since the last answer. See `claimRearm`. */
     supersededAsks: 0,
+    /** A hint owes one more ask once the one in flight answers. See `poll-hint.ts`. */
+    hinted: false,
     timer: undefined as ReturnType<typeof setTimeout> | undefined,
     /**
      * The wall clock, as a timer rather than a check after an ask. `outOfTime`
@@ -314,12 +272,29 @@ function scheduleNext(
   run.timer = setTimeout(again, delay);
 }
 
+/** Abandon whatever ask is current and ask now, keeping the clock. */
+function askNow(run: PollRun, tick: () => Promise<void>): void {
+  run.attempt += 1;
+  run.inFlight = false;
+  clearPending(run);
+  void tick();
+}
+
+/** After a non-terminal answer: the ask a hint owes, or the usual schedule. */
+function continueAfter(run: PollRun, tick: () => Promise<void>, schedule: () => void): void {
+  const owed = owedAfterAnswer(run);
+  if (owed === "ask") askNow(run, tick);
+  else if (owed === "none") schedule();
+}
+
 /** The handle the hook holds on one running wait. */
 export interface PollLoop {
   /** Reset the clock and the counters, then ask immediately. */
   restart: () => void;
   /** Ask immediately, keeping the clock — the re-arm events' entry point. Whether it asked. */
   poke: () => boolean;
+  /** A realtime hint: ask now, or owe one ask after the current one (`poll-hint.ts`, FUT-3205). */
+  hint: () => void;
   /** Tear down: nothing further is scheduled and nothing further is written. */
   stop: () => void;
 }
@@ -353,11 +328,12 @@ export function createPollLoop(
     if (run.attempt === mine) run.inFlight = false;
     if (run.cancelled || run.settled) return;
     if (!absorb(run, result, sink)) {
+      run.hinted = false;
       clearDeadline(run);
       return;
     }
     if (run.attempt !== mine) return;
-    scheduleNext(run, options, sink, () => void tick());
+    continueAfter(run, tick, () => scheduleNext(run, options, sink, () => void tick()));
   };
 
   return {
@@ -372,6 +348,7 @@ export function createPollLoop(
       run.errors = 0;
       run.healthy = 0;
       run.supersededAsks = 0;
+      run.hinted = false;
       run.startedAt = Date.now();
       armDeadline(run, options, sink);
       sink.setTimedOut(false);
@@ -385,12 +362,14 @@ export function createPollLoop(
       // socket that died while the screen was hidden. Abandon it and ask now —
       // but `claimRearm` bounds how many live asks that may abandon in a row.
       if (!claimRearm(run)) return false;
-      run.attempt += 1;
-      run.inFlight = false;
-      clearPending(run);
-      void tick();
+      // The new ask is sent after any hint that marked the old one.
+      run.hinted = false;
+      askNow(run, tick);
       return true;
     },
+    hint: (): void => {
+      if (claimHint(run)) askNow(run, tick);
+    },
     stop: (): void => {
       run.cancelled = true;
       clearPending(run);

package/src/components/checks-locally.ts

@@ -0,0 +1,13 @@
+import type { ProviderDescriptor } from '@12-apps/payments-backend';
+
+/**
+ * Whether this provider's "test" is a LOCAL check — there is no provider to
+ * connect to (the store's own Pix key, `capabilities.confirmation: 'MANUAL'`).
+ * Its screen must not say keys are tested "no provedor" or call a passing
+ * check a CONNECTION. Read defensively: a host-built descriptor may carry no
+ * capabilities.
+ */
+export function checksLocally(descriptor: Pick<ProviderDescriptor, 'capabilities'> | undefined): boolean {
+  const capabilities = descriptor?.capabilities as ProviderDescriptor['capabilities'] | undefined;
+  return capabilities?.confirmation === 'MANUAL';
+}

package/src/components/credential-rules.ts

@@ -5,6 +5,7 @@ import type {
   ProviderDescriptor,
 } from '@12-apps/payments-backend';
 
+import { checksLocally } from './checks-locally';
 import type { PendingSave } from './ConfirmCredentialSave';
 import type { CredentialFormCopy } from './settings-copy';
 
@@ -49,7 +50,7 @@ export function credentialsComplete(
 ): boolean {
   const stored = config?.environments[environment] ?? {};
   return descriptor.credentialSchema.every((spec) => {
-    if (spec.advanced || !appliesIn(spec, environment)) return true;
+    if (spec.advanced || spec.optional || !appliesIn(spec, environment)) return true;
     const typed = values[spec.key];
     if (typed !== undefined && typed.trim() !== '') return true;
     return stored[spec.key]?.configured === true;
@@ -104,10 +105,15 @@ export function saveLabel(
 ): string {
   const required = descriptor.credentialSchema.filter((field) => field.required);
   const only = required.length === 1 ? required[0] : undefined;
-  if (!only) return complete ? copy.saveAndTest : copy.save;
+  if (!only) return complete ? saveAndTestLabel(copy, descriptor) : copy.save;
   return copy.saveOnly(only.label.replace(/\s*\([^)]*\)\s*$/, ''));
 }
 
+/** "Salvar e testar conexão", or "Salvar e conferir" where nothing leaves for a provider. */
+function saveAndTestLabel(copy: CredentialFormCopy, descriptor: ProviderDescriptor): string {
+  return (checksLocally(descriptor) ? copy.saveAndCheck : undefined) ?? copy.saveAndTest;
+}
+
 /**
  * The stored value of the field a finished step collapses around.
  *

package/src/components/settings-copy.ts

@@ -30,6 +30,12 @@ export interface ConnectionStatusCopy {
   unverified: string;
   /** The credential probe passed; no charge has been made. */
   connectionOk: string;
+  /**
+   * `connectionOk` for a provider there is nothing to connect to — the store's
+   * own Pix key, checked here (`checksLocally`). Optional: absent, the chip
+   * falls back to `connectionOk`.
+   */
+  detailsOk?: string;
   /**
    * A connection that WAS working and stopped — the one red chip, because it
    * is news rather than a step still to finish.
@@ -41,6 +47,8 @@ export interface ConnectionStatusCopy {
   threeStepsAhead: string;
   /** The same, when the store must connect and verify first. */
   connectAndVerifyFirst: string;
+  /** `connectAndVerifyFirst` for a provider checked locally. Optional, falls back to it. */
+  checkDetailsFirst?: string;
   /** Live: this provider is taking money. */
   receiving: { state: string; sub: string };
   /** Proven, and switched off by the owner. */
@@ -194,6 +202,8 @@ export interface CredentialFormCopy {
   configuredKeepBlank: string;
   /** The suffix on an `advanced` field most stores must leave empty. */
   advancedSuffix: string;
+  /** The suffix on an `optional` field: blank keeps its default. */
+  optionalSuffix: string;
   probeAction: string;
   /**
    * What replacing a PROVEN connection's credentials costs.
@@ -206,6 +216,13 @@ export interface CredentialFormCopy {
   reverifyWarning(displayName: string): string;
   probeRunning: string;
   probeSaveNote: string;
+  /**
+   * `probeRunning` / `probeSaveNote` for a provider checked locally: nothing is
+   * sent anywhere, so saying the keys are tested "no provedor" would be false.
+   * Optional; absent, the provider sentences are used.
+   */
+  probeLocalRunning?: string;
+  probeLocalSaveNote?: string;
   probeIncompleteNote: string;
   probeFailed(environmentName: string): string;
   /** The per-credential marks beside each field. */
@@ -219,6 +236,8 @@ export interface CredentialFormCopy {
    * only written down, and a one-field provider names its field instead.
    */
   saveAndTest: string;
+  /** `saveAndTest` for a provider checked locally (no connection to test). Optional. */
+  saveAndCheck?: string;
   save: string;
   saveOnly(fieldLabel: string): string;
   /** Reopen a finished credential step — unaccented, so only a reading found it. */

package/src/components/settings-en-US.ts

@@ -22,10 +22,12 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     verified: 'VERIFIED',
     unverified: 'NOT VERIFIED',
     connectionOk: 'CONNECTION OK',
+    detailsOk: 'DETAILS OK',
     reconnectRequired: 'RECONNECT',
     notConnected: 'Not connected',
     threeStepsAhead: 'This provider only starts taking sales after the 3 steps below.',
     connectAndVerifyFirst: 'Connect and verify the provider before switching sales on.',
+    checkDetailsFirst: 'Fill in and check the details before switching sales on.',
     receiving: {
       state: 'Taking sales',
       sub: 'Your store is being paid through this provider.',
@@ -131,12 +133,15 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     configuredKeepBlank: 'Configured — leave blank to keep the current value.',
     // Leading space: it is appended to a field label.
     advancedSuffix: ' · Connect platforms only',
+    optionalSuffix: ' · optional',
     probeAction: 'Test connection',
     reverifyWarning: (displayName) =>
       `This store is already verified. Changing the credentials **requires re-verification** ` +
       `and the store **stops taking payments** through ${displayName} until it finishes.`,
     probeRunning: 'Testing the connection…',
     probeSaveNote: 'We save and test the keys with the provider before going on.',
+    probeLocalRunning: 'Checking the details…',
+    probeLocalSaveNote: 'We check the details before saving.',
     probeIncompleteNote: 'We kept what you have filled in. Complete the fields to test.',
     probeFailed: (environmentName) =>
       `Could not connect in ${environmentName}. Check the credentials for this environment.`,
@@ -144,6 +149,7 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     checkFail: 'Fix',
     uncheckable: 'Not verifiable',
     saveAndTest: 'Save and test connection',
+    saveAndCheck: 'Save and check',
     save: 'Save',
     saveOnly: (fieldLabel) => `Save ${fieldLabel}`,
     changeAction: 'Change',

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

@@ -14,10 +14,12 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     verified: 'VERIFICADO',
     unverified: 'NÃO VERIFICADO',
     connectionOk: 'CONEXÃO OK',
+    detailsOk: 'DADOS 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.',
+    checkDetailsFirst: 'Preencha e confira os dados antes de ativar as vendas.',
     receiving: {
       state: 'Recebendo vendas',
       sub: 'Sua loja está recebendo por este provedor.',
@@ -119,12 +121,15 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
   credentials: {
     configuredKeepBlank: 'Configurado — deixe em branco para manter o valor atual.',
     advancedSuffix: ' · só para plataformas Connect',
+    optionalSuffix: ' · opcional',
     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.',
+    probeLocalRunning: 'Conferindo os dados…',
+    probeLocalSaveNote: 'Conferimos os dados antes de salvar.',
     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.`,
@@ -132,6 +137,7 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     checkFail: 'Corrigir',
     uncheckable: 'Não verificável',
     saveAndTest: 'Salvar e testar conexão',
+    saveAndCheck: 'Salvar e conferir',
     save: 'Salvar',
     saveOnly: (fieldLabel) => `Salvar ${fieldLabel}`,
     changeAction: 'Alterar',