@12-apps/payments-frontend 3.40.0 → 3.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.40.0",
+  "version": "3.42.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.30.0",
+    "@12-apps/payments-backend": "^4.32.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/activation/use-redirect-activation.ts

@@ -53,7 +53,10 @@ import { clearReturnedSettlement, takeReturnedSettlement } from './returned-sett
  * things that clear it are settlement and an explicit "give up".
  */
 
-/** How often to ask the provider whether the payment landed. */
+/**
+ * How often to ask the provider whether the payment landed — the recorded
+ * third-party-wait exception, see {@link usePollTimer}.
+ */
 const DEFAULT_POLL_MS = 4000;
 
 /** Give up asking after this long, rather than polling a tab forever. */
@@ -126,6 +129,25 @@ interface ActivationCallbacks {
 /**
  * Ask the provider every few seconds, and stop asking eventually.
  *
+ * ## A deliberate poll: the recorded exception to "hear, do not poll" (FUT-2433)
+ *
+ * Every other wait in this package hears the host's channel and keeps no timer
+ * while it is live. This one cannot, and it is the one exception class the
+ * origin host records: a timer-driven read of a THIRD PARTY's state that no
+ * webhook or publisher of the host's reaches yet, bounded in time, and named.
+ * Each tick is not a read of the host's own rows — `verify-charge` asks the
+ * PROVIDER whether the activation charge was paid, and while nobody has asked,
+ * nothing server-side has moved that a hint could carry. The activation webhook
+ * that would settle it is not guaranteed to arrive (a tunnel, a preview box), so
+ * the wait is the confirmation. It runs only while the owner is paying on the
+ * provider's page and gives up at `pollTimeoutMs` (ten minutes by default).
+ *
+ * Where it is recorded: the origin host's realtime doc ("Allowed exceptions")
+ * and a decision record that amends ADR 0071 with it. This bounded third-party
+ * wait is an amendment to that ADR, not a supersession: 0071 still stands for
+ * every other wait. If activation ever becomes webhook-only, this relaxes to
+ * the channel exactly as the checkout's waits did and the exception goes away.
+ *
  * The give-up is a `failed` state carrying the host's own sentence, because the
  * wording is load-bearing: the charge is STILL valid, and an owner who has
  * genuinely paid must not be told they did not pay in time.

package/src/components/PaymentProviderSettings.tsx

@@ -21,6 +21,7 @@ import {
   type ProviderChangeHandler,
 } from './settings-state';
 import { openSection, SetupGuideSection } from './SetupGuideSection';
+import { useSettingsLive, type PaymentsSettingsLiveSignal } from './settings-live';
 import type { PaymentsSettingsCopy } from './settings-copy';
 import { PaymentsSettingsCopyProvider } from './settings-copy-context';
 
@@ -102,6 +103,16 @@ export interface PaymentProviderSettingsProps {
    * its history ({@link ProviderChangeHandler}).
    */
   onProviderChange?: ProviderChangeHandler;
+  /**
+   * The host's realtime channel for this store's payment settings (FUT-648).
+   *
+   * A hint re-reads the view, and so does every (re)connect: an OAuth grant
+   * completed in another tab, a colleague's save, a webhook settling the
+   * activation charge all reach this screen without a reload. Omit it and the
+   * screen reads on mount and after its own actions, exactly as before — it
+   * keeps no timer either way. See {@link PaymentsSettingsLiveSignal}.
+   */
+  live?: PaymentsSettingsLiveSignal;
   /**
    * The activation step, rendered under the connection card.
    *
@@ -299,8 +310,10 @@ export function PaymentProviderSettings({
   selectedProvider,
   onProviderChange,
   renderVerification,
+  live,
 }: PaymentProviderSettingsProps) {
   const { view, error, reload } = useSettingsState(client);
+  useSettingsLive(live, () => void reload());
   const { selected, setSelected } = useSelectedProvider(
     initialProvider,
     selectedProvider,

package/src/components/platform/ConnectApplicationPanel.tsx

@@ -3,11 +3,17 @@
 import { Box, Button, Stack, Typography } from '@mui/material';
 import type { ReactNode } from 'react';
 
-import type { ConnectApplicationReport, PaymentEnvironment } from '@12-apps/payments-backend';
+import type {
+  ConnectApplicationReport,
+  ConnectApplicationStatus,
+  PastedConnectCredentials,
+  PaymentEnvironment,
+} from '@12-apps/payments-backend';
 
-import { CARD_SX, ConnectEnvironmentCard } from './ConnectEnvironmentCard';
+import { CARD_SX, ConnectEnvironmentCard, TAP_SX } from './ConnectEnvironmentCard';
 import type { PlatformHomologacaoCopy } from './copy';
 import { PlatformCopyProvider, usePlatformCopy } from './copy-context';
+import { PastedCredentialsCard } from './PastedCredentialsCard';
 
 /**
  * The platform's PagBank Connect application, per environment (FUT-479,
@@ -41,9 +47,17 @@ export interface ConnectApplicationPanelProps {
   /**
    * Which host-side variables feed one environment's application — the host's
    * own configuration surface, rendered as a collapsible per-environment help
-   * when provided.
+   * when provided. ORDER MATTERS: the first three name the client id, the
+   * client secret and the account token, in that order — the credential
+   * preview and the paste fields are labelled by position.
    */
   configVarsFor?: (environment: PaymentEnvironment) => string[];
+  /**
+   * Consult with PASTED credentials — the host's mounted call to the backend's
+   * `consultPastedConnectApplication`, resolving to the status it answered.
+   * Omitted, the paste block is not rendered.
+   */
+  onConsultPasted?: (pasted: PastedConnectCredentials) => Promise<ConnectApplicationStatus>;
   /** Every word this panel and its environment cards render. REQUIRED. */
   copy: PlatformHomologacaoCopy;
 }
@@ -57,12 +71,12 @@ export function ConnectApplicationPanel(props: ConnectApplicationPanelProps): Re
 }
 
 function ConnectApplicationBody(props: ConnectApplicationPanelProps): ReactNode {
-  const { report, onRefresh, configVarsFor } = props;
+  const { report, onRefresh, configVarsFor, onConsultPasted } = props;
   const copy = usePlatformCopy().connect;
   return (
     <Stack spacing={2} data-testid="connect-application-panel">
       <Stack spacing={0.5} data-testid="connect-expected-redirect" sx={CARD_SX}>
-        <Typography variant="caption" color="text.secondary" fontWeight={600}>
+        <Typography variant="caption" fontWeight={600}>
           {copy.expectedRedirectHeading}
         </Typography>
         <Box
@@ -79,6 +93,9 @@ function ConnectApplicationBody(props: ConnectApplicationPanelProps): ReactNode
           configVars={configVarsFor?.(status.environment)}
         />
       ))}
+      {onConsultPasted ? (
+        <PastedCredentialsCard onConsult={onConsultPasted} configVarsFor={configVarsFor} />
+      ) : null}
       {onRefresh ? (
         <Box>
           <Button
@@ -86,6 +103,7 @@ function ConnectApplicationBody(props: ConnectApplicationPanelProps): ReactNode
             size="small"
             onClick={() => onRefresh()}
             data-testid="connect-refresh"
+            sx={TAP_SX}
           >
             {copy.consultAgain}
           </Button>

package/src/components/platform/ConnectEnvironmentCard.tsx

@@ -1,9 +1,13 @@
 'use client';
 
 import { Alert, Box, Button, Stack, Typography } from '@mui/material';
-import { useState, type ReactNode } from 'react';
+import { Fragment, useState, type ReactNode } from 'react';
 
-import type { ConnectApplicationStatus, PaymentEnvironment } from '@12-apps/payments-backend';
+import type {
+  ConnectApplicationStatus,
+  ConnectCredentialPreview,
+  PaymentEnvironment,
+} from '@12-apps/payments-backend';
 import { usePlatformCopy } from './copy-context';
 
 /**
@@ -11,17 +15,15 @@ import { usePlatformCopy } from './copy-context';
  * Sandbox and production are SEPARATE applications with separate id/secret
  * pairs, so each card stands on its own: configured or not, what PagBank says
  * is registered, and whether the registered redirect URI matches the
- * deployment's callback.
+ * deployment's callback — plus the first characters of each value it was
+ * consulted with, so an operator can tell WHICH id, secret and token are in play.
  *
- * English, like the rest of this platform surface (FUT-760) — see
- * `ConnectApplicationPanel` for why.
+ * The same card renders the answer to a PASTED consult, so its test ids key on
+ * a `slot` — the environment for the host's two cards, `PASTED` for that one —
+ * rather than on the environment, which the pasted answer shares with one of
+ * them.
  */
 
-const ENV_LABEL: Record<PaymentEnvironment, string> = {
-  SANDBOX: 'Sandbox',
-  PRODUCTION: 'Production',
-};
-
 /** The bordered-card look every block of these screens shares. */
 export const CARD_SX = {
   border: 1,
@@ -30,13 +32,32 @@ export const CARD_SX = {
   p: 2,
 } as const;
 
+/** A small button that is still a 40px tap target on a phone. */
+export const TAP_SX = { minHeight: { xs: 40, sm: 'auto' } } as const;
+
+/**
+ * A label like `PAGBANK_OAUTH_CLIENT_SECRET` is one token, so a narrow card
+ * would break it anywhere ("…SECRE / T"). A `<wbr>` after each underscore lets
+ * it wrap at the word joints instead.
+ */
+function breakAfterUnderscores(label: string): ReactNode {
+  return label.split(/(?<=_)/).map((part, index) => (
+    // The parts are positional by construction; the label never reorders.
+    <Fragment key={index}>
+      {part}
+      <wbr />
+    </Fragment>
+  ));
+}
+
 function Field({ label, children }: { label: string; children: ReactNode }): ReactNode {
   return (
     <Box
-      sx={{ display: 'flex', flexDirection: 'column', gap: 0.25, minWidth: 180, wordBreak: 'break-all' }}
+      // Whole words stay whole; only an unbroken id or URL breaks mid-run.
+      sx={{ display: 'flex', flexDirection: 'column', gap: 0.25, minWidth: 180, overflowWrap: 'anywhere' }}
     >
-      <Typography variant="caption" color="text.secondary" fontWeight={600}>
-        {label}
+      <Typography variant="caption" fontWeight={600}>
+        {breakAfterUnderscores(label)}
       </Typography>
       <Typography component="span" variant="body2">
         {children}
@@ -46,32 +67,32 @@ function Field({ label, children }: { label: string; children: ReactNode }): Rea
 }
 
 /** The verdict the screen exists for: does the registered callback match ours? */
-function MismatchAlert({ status }: { status: ConnectApplicationStatus }): ReactNode {
+function MismatchAlert({ status, slot }: { status: ConnectApplicationStatus; slot: string }): ReactNode {
   const copy = usePlatformCopy().connect;
   if (status.application === null) return null;
   if (status.redirectUriMismatch === true) {
     return (
-      <Alert severity="error" data-testid={`connect-mismatch-${status.environment}`}>
+      <Alert severity="error" data-testid={`connect-mismatch-${slot}`}>
         {copy.redirectDiffers}
       </Alert>
     );
   }
   if (status.redirectUriMismatch === false) {
     return (
-      <Alert severity="success" data-testid={`connect-match-${status.environment}`}>
+      <Alert severity="success" data-testid={`connect-match-${slot}`}>
         {copy.redirectMatches}
       </Alert>
     );
   }
   return (
-    <Alert severity="warning" data-testid={`connect-unknown-${status.environment}`}>
+    <Alert severity="warning" data-testid={`connect-unknown-${slot}`}>
       {copy.redirectUnreported}
     </Alert>
   );
 }
 
 /** What PagBank reports as registered, plus whatever extra keys came back. */
-function ApplicationFields({ status }: { status: ConnectApplicationStatus }): ReactNode {
+function ApplicationFields({ status, slot }: { status: ConnectApplicationStatus; slot: string }): ReactNode {
   const copy = usePlatformCopy().connect;
   const app = status.application;
   if (app === null) return null;
@@ -88,8 +109,8 @@ function ApplicationFields({ status }: { status: ConnectApplicationStatus }): Re
         </Field>
       </Box>
       {extraKeys.length > 0 ? (
-        <Box data-testid={`connect-extra-${status.environment}`}>
-          <Typography variant="caption" color="text.secondary" fontWeight={600}>
+        <Box data-testid={`connect-extra-${slot}`}>
+          <Typography variant="caption" fontWeight={600}>
             {copy.extraKeys}
           </Typography>
           <Box component="pre" sx={{ m: 0, fontSize: 12, overflowX: 'auto' }}>
@@ -101,6 +122,69 @@ function ApplicationFields({ status }: { status: ConnectApplicationStatus }): Re
   );
 }
 
+const EMPTY_PREVIEW: ConnectCredentialPreview = {
+  clientId: null,
+  clientSecret: null,
+  accountToken: null,
+};
+
+/** One previewed value: unset, inherited from a fallback variable, or its own. */
+function PreviewValue({ value, inherited }: { value: string | null; inherited: boolean }): ReactNode {
+  const copy = usePlatformCopy().connect;
+  if (value === null) return copy.previewUnset;
+  const code = (
+    <Box component="code" sx={{ fontFamily: 'monospace', fontSize: 13 }}>
+      {`${value}…`}
+    </Box>
+  );
+  if (!inherited) return code;
+  return (
+    <>
+      {copy.previewInherited} {code}
+    </>
+  );
+}
+
+/**
+ * The first characters of each value the application was consulted with —
+ * never the value. Each is named by the host's own variable when it supplies
+ * them (`configVars`, in id / secret / token order), by the copy's names when not.
+ */
+function CredentialPreview({
+  status,
+  slot,
+  configVars,
+}: {
+  status: ConnectApplicationStatus;
+  slot: string;
+  configVars?: string[];
+}): ReactNode {
+  const copy = usePlatformCopy().connect;
+  // A payload from a backend older than the preview carries none — render it unset, never crash.
+  const preview = status.credentialPreview ?? EMPTY_PREVIEW;
+  const names = copy.credentialNames;
+  const fields = ['clientId', 'clientSecret', 'accountToken'] as const;
+  const rows = fields.map((field, index) => ({
+    name: configVars?.[index] ?? names[field],
+    value: preview[field],
+    inherited: preview.inherited?.includes(field) ?? false,
+  }));
+  return (
+    <Stack spacing={1} data-testid={`connect-preview-${slot}`}>
+      <Typography variant="caption" fontWeight={600}>
+        {copy.previewHeading}
+      </Typography>
+      <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 2.5 }}>
+        {rows.map(({ name, value, inherited }) => (
+          <Field key={name} label={name}>
+            <PreviewValue value={value} inherited={inherited} />
+          </Field>
+        ))}
+      </Box>
+    </Stack>
+  );
+}
+
 /**
  * The collapsible "what feeds this environment" help. The variable names are
  * the HOST's own configuration surface, so they arrive via `configVars`; with
@@ -123,6 +207,7 @@ function ConfigHelp({
         size="small"
         onClick={() => setOpen((value) => !value)}
         data-testid={`connect-config-toggle-${environment}`}
+        sx={TAP_SX}
       >
         {open ? copy.hideConfig : copy.showConfig}
       </Button>
@@ -149,18 +234,30 @@ function ConfigHelp({
 export function ConnectEnvironmentCard({
   status,
   configVars,
+  slot = status.environment,
+  showConfigHelp = true,
 }: {
   status: ConnectApplicationStatus;
   configVars?: string[];
+  /** What the test ids key on — see the module doc. */
+  slot?: string;
+  /** The variable help belongs to a host-configured environment, not a pasted answer. */
+  showConfigHelp?: boolean;
 }): ReactNode {
   const copy = usePlatformCopy().connect;
   return (
-    <Stack spacing={1.5} data-testid={`connect-env-${status.environment}`} sx={CARD_SX}>
-      <Box sx={{ display: 'flex', alignItems: 'baseline', gap: 1.5, wordBreak: 'break-all' }}>
-        <Typography variant="body2" fontWeight={600}>
-          {ENV_LABEL[status.environment]}
+    <Stack spacing={1.5} data-testid={`connect-env-${slot}`} sx={CARD_SX}>
+      {/* The label never yields to a long client_id: the id wraps beneath it. */}
+      <Box sx={{ display: 'flex', flexWrap: 'wrap', alignItems: 'baseline', columnGap: 1.5 }}>
+        <Typography variant="body2" fontWeight={600} sx={{ whiteSpace: 'nowrap' }}>
+          {copy.environmentLabels[status.environment]}
         </Typography>
-        <Typography component="span" variant="caption" color="text.secondary">
+        <Typography
+          component="span"
+          variant="caption"
+          color="text.secondary"
+          sx={{ wordBreak: 'break-all', minWidth: 0 }}
+        >
           {status.clientId !== null ? `client_id: ${status.clientId}` : ''}
         </Typography>
       </Box>
@@ -168,13 +265,14 @@ export function ConnectEnvironmentCard({
         <Typography variant="body2" color="text.secondary">{copy.noApplication}</Typography>
       ) : null}
       {status.error !== null ? (
-        <Alert severity="warning" data-testid={`connect-error-${status.environment}`}>
+        <Alert severity="warning" data-testid={`connect-error-${slot}`}>
           {status.error}
         </Alert>
       ) : null}
-      <MismatchAlert status={status} />
-      <ApplicationFields status={status} />
-      <ConfigHelp environment={status.environment} configVars={configVars} />
+      <MismatchAlert status={status} slot={slot} />
+      <ApplicationFields status={status} slot={slot} />
+      <CredentialPreview status={status} slot={slot} configVars={configVars} />
+      {showConfigHelp ? <ConfigHelp environment={status.environment} configVars={configVars} /> : null}
     </Stack>
   );
 }

package/src/components/platform/PastedCredentialsCard.tsx

@@ -0,0 +1,227 @@
+'use client';
+
+import { Alert, Box, Button, Stack, TextField, Typography } from '@mui/material';
+import { useRef, useState, type ReactNode } from 'react';
+
+import type {
+  ConnectApplicationStatus,
+  PastedConnectCredentials,
+  PaymentEnvironment,
+} from '@12-apps/payments-backend';
+
+import { CARD_SX, ConnectEnvironmentCard, TAP_SX } from './ConnectEnvironmentCard';
+import { usePlatformCopy } from './copy-context';
+
+/**
+ * Consult a Connect application with credentials PASTED here rather than the
+ * ones the host holds — the backend's `consultPastedConnectApplication`.
+ *
+ * The host's two cards answer "what is configured?"; this answers "is the
+ * application I am about to configure the right one, and is its redirect_uri
+ * ours?" before anyone edits a secret and redeploys to find out. The answer
+ * comes back in the same card the environments use, previews included, so the
+ * three blocks read the same way.
+ *
+ * Whatever `onConsult` sends is the host's to keep out of storage and logs —
+ * this card holds the values in component state and nowhere else.
+ */
+
+type PastedValues = Omit<PastedConnectCredentials, 'environment'>;
+
+const EMPTY: PastedValues = { clientId: '', clientSecret: '', accountToken: '' };
+
+/** The three paste fields; the secret two are masked as they are typed. */
+function CredentialInputs({
+  names,
+  values,
+  onChange,
+}: {
+  names: [string, string, string];
+  values: PastedValues;
+  onChange: (values: PastedValues) => void;
+}): ReactNode {
+  const fields: [keyof PastedValues, string, boolean][] = [
+    ['clientId', names[0], false],
+    ['clientSecret', names[1], true],
+    ['accountToken', names[2], true],
+  ];
+  return fields.map(([key, label, secret]) => (
+    <TextField
+      key={key}
+      size="small"
+      type={secret ? 'password' : 'text'}
+      label={label}
+      value={values[key]}
+      // "off", never "new-password": that value is the hint password managers use to
+      // offer saving what was typed, and these values are never to be stored.
+      autoComplete="off"
+      onChange={(event) => onChange({ ...values, [key]: event.target.value })}
+      // Shrunk for good: the names share a long prefix, so an empty field's
+      // placeholder-sized label is cut to the same "PAGBANK_OAUTH_CLIENT…" twice.
+      slotProps={{
+        inputLabel: { shrink: true },
+        htmlInput: {
+          'data-testid': `connect-pasted-${key}`,
+          // Password managers that ignore autocomplete honour these.
+          'data-1p-ignore': true,
+          'data-lpignore': 'true',
+        },
+      }}
+    />
+  ));
+}
+
+/** The input names: the host's own variables when it names them, the copy's when not. */
+function useCredentialNames(
+  environment: PaymentEnvironment,
+  configVarsFor?: (environment: PaymentEnvironment) => string[],
+): [string, string, string] {
+  const fallback = usePlatformCopy().connect.credentialNames;
+  const vars = configVarsFor?.(environment) ?? [];
+  return [
+    vars[0] ?? fallback.clientId,
+    vars[1] ?? fallback.clientSecret,
+    vars[2] ?? fallback.accountToken,
+  ];
+}
+
+/** One consult at a time: what it answered, whether it failed, whether it is running. */
+function usePastedConsult(
+  onConsult: (pasted: PastedConnectCredentials) => Promise<ConnectApplicationStatus>,
+): {
+  run: (pasted: PastedConnectCredentials) => void;
+  reset: () => void;
+  pending: boolean;
+  failed: boolean;
+  result: ConnectApplicationStatus | null;
+} {
+  const [pending, setPending] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const [result, setResult] = useState<ConnectApplicationStatus | null>(null);
+  // Which call the screen still wants an answer to. `reset` and every new `run`
+  // move it on, so a consult that settles after the values changed is dropped
+  // instead of landing beside values it was not given.
+  const current = useRef(0);
+  const run = (pasted: PastedConnectCredentials): void => {
+    const id = ++current.current;
+    const live = (): boolean => id === current.current;
+    setPending(true);
+    setFailed(false);
+    onConsult(pasted)
+      .then((status) => live() && setResult(status))
+      .catch(() => live() && setFailed(true))
+      .finally(() => live() && setPending(false));
+  };
+  // An answer belongs to the values it was given: editing any of them retires it.
+  const reset = (): void => {
+    current.current += 1;
+    setPending(false);
+    setFailed(false);
+    setResult(null);
+  };
+  return { run, reset, pending, failed, result };
+}
+
+export function PastedCredentialsCard({
+  onConsult,
+  configVarsFor,
+}: {
+  onConsult: (pasted: PastedConnectCredentials) => Promise<ConnectApplicationStatus>;
+  configVarsFor?: (environment: PaymentEnvironment) => string[];
+}): ReactNode {
+  const copy = usePlatformCopy().connect;
+  const [environment, setEnvironment] = useState<PaymentEnvironment>('SANDBOX');
+  const [values, setValues] = useState<PastedValues>(EMPTY);
+  const names = useCredentialNames(environment, configVarsFor);
+  const consult = usePastedConsult(onConsult);
+  const complete = Object.values(values).every((value) => value.trim() !== '');
+  const trimmed = {
+    environment,
+    clientId: values.clientId.trim(),
+    clientSecret: values.clientSecret.trim(),
+    accountToken: values.accountToken.trim(),
+  };
+
+  return (
+    <Stack spacing={1.5} data-testid="connect-pasted" sx={CARD_SX}>
+      <Typography variant="body2" fontWeight={600}>
+        {copy.pasted.heading}
+      </Typography>
+      <Typography variant="caption" component="p">
+        {copy.pasted.lede}
+      </Typography>
+      <Stack spacing={1.5} sx={{ maxWidth: 560 }}>
+        <TextField
+          select
+          size="small"
+          label={copy.pasted.environment}
+          value={environment}
+          onChange={(event) => {
+            setEnvironment(event.target.value as PaymentEnvironment);
+            consult.reset();
+          }}
+          slotProps={{
+            select: { native: true },
+            htmlInput: { 'data-testid': 'connect-pasted-environment' },
+          }}
+        >
+          <option value="SANDBOX">{copy.environmentLabels.SANDBOX}</option>
+          <option value="PRODUCTION">{copy.environmentLabels.PRODUCTION}</option>
+        </TextField>
+        <CredentialInputs
+          names={names}
+          values={values}
+          onChange={(next) => {
+            setValues(next);
+            consult.reset();
+          }}
+        />
+        <Box>
+          <Button
+            variant="contained"
+            size="small"
+            disabled={!complete || consult.pending}
+            onClick={() => consult.run(trimmed)}
+            data-testid="connect-pasted-submit"
+            sx={TAP_SX}
+          >
+            {copy.pasted.submit}
+          </Button>
+        </Box>
+      </Stack>
+      <PastedAnswer consult={consult} configVarsFor={configVarsFor} />
+    </Stack>
+  );
+}
+
+/** The failure line, or the answer in the same card the environments use. */
+function PastedAnswer({
+  consult,
+  configVarsFor,
+}: {
+  consult: ReturnType<typeof usePastedConsult>;
+  configVarsFor?: (environment: PaymentEnvironment) => string[];
+}): ReactNode {
+  const copy = usePlatformCopy().connect;
+  if (consult.failed) {
+    return (
+      <Alert severity="error" data-testid="connect-pasted-failed">
+        {copy.pasted.failed}
+      </Alert>
+    );
+  }
+  if (!consult.result) return null;
+  return (
+    <Stack spacing={1}>
+      <Alert severity="info" data-testid="connect-pasted-secret-not-checked">
+        {copy.pasted.secretNotChecked}
+      </Alert>
+      <ConnectEnvironmentCard
+        status={consult.result}
+        slot="PASTED"
+        configVars={configVarsFor?.(consult.result.environment)}
+        showConfigHelp={false}
+      />
+    </Stack>
+  );
+}

package/src/components/platform/copy.ts

@@ -102,6 +102,32 @@ export interface ConnectApplicationCopy {
   hideConfig: string;
   /** The heading above whatever extra keys PagBank's response carried. */
   extraKeys: string;
+  /** Each card's heading — the environment, in the operator's words. */
+  environmentLabels: Readonly<Record<'SANDBOX' | 'PRODUCTION', string>>;
+  /**
+   * The preview of the values an application was consulted with: a heading,
+   * what an unset value reads as, and each value's name when the host names no
+   * configuration variables of its own (`configVarsFor`).
+   */
+  previewHeading: string;
+  previewUnset: string;
+  /** A value read from a fallback variable (production's token from the unsuffixed name). */
+  previewInherited: string;
+  credentialNames: { clientId: string; clientSecret: string; accountToken: string };
+  /** The block that consults with PASTED credentials — rendered only when the host wires it. */
+  pasted: {
+    heading: string;
+    /** Must say the values are not stored: the operator is pasting secrets. */
+    lede: string;
+    environment: string;
+    submit: string;
+    failed: string;
+    /**
+     * The consult authenticates with the account token and looks up the client
+     * id; the secret is never sent. The answer must not read as "all three are good".
+     */
+    secretNotChecked: string;
+  };
 }
 
 /** The whole platform surface, in one object a host passes at the mount. */

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

@@ -72,7 +72,7 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     // operator compares the two strings character by character.
     redirectMatches: 'The registered redirect_uri matches the callback this deploy uses.',
     redirectDiffers:
-      'The redirect_uri registered with PagBank differs from the callback this deploy uses.',
+      'The redirect_uri registered with PagBank differs from the callback this deploy uses. The OAuth authorization flow fails silently until the registration is fixed at PagBank.',
     redirectUnreported:
       "PagBank's response carried no redirect_uri, so it could not be compared with the callback.",
     fields: {
@@ -85,9 +85,25 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     fieldEmpty: '—',
     redirectNotReported: 'not reported',
     resolvedFrom:
-      "This environment's application is resolved strictly from these variables, with no fallback between environments:",
+      "This environment's application is resolved from these variables. The client_id and client_secret are strict, with no fallback between environments; the others, such as the token, fall back to the unsuffixed variable when this environment's own is unset:",
     showConfig: 'Show environment variables',
     hideConfig: 'Hide environment variables',
-    extraKeys: 'Other fields returned',
+    extraKeys: 'Other fields returned (undocumented schema)',
+    environmentLabels: { SANDBOX: 'Sandbox', PRODUCTION: 'Production' },
+    previewHeading: 'First 5 characters of each variable',
+    previewUnset: 'not set',
+    previewInherited: 'not set — uses the unsuffixed variable:',
+    // `client_id` / `client_secret` are PagBank's own parameter names.
+    credentialNames: { clientId: 'client_id', clientSecret: 'client_secret', accountToken: 'account token' },
+    pasted: {
+      heading: 'Test other credentials',
+      lede:
+        "Paste an application's credentials to look it up at PagBank before changing the environment variables. The values are used for this lookup only and are not saved.",
+      environment: 'Environment',
+      submit: 'Look up with these credentials',
+      failed: 'The pasted credentials could not be looked up.',
+      secretNotChecked:
+        'PagBank does not check the client_secret in this lookup — only the client_id and the token. A wrong client_secret only shows at the first store authorization.',
+    },
   },
 };

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

@@ -52,7 +52,7 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     noApplication: 'Nenhuma aplicação configurada neste ambiente.',
     redirectMatches: 'O redirect_uri registrado confere com o callback que este deploy usa.',
     redirectDiffers:
-      'O redirect_uri registrado no PagBank é diferente do callback que este deploy usa.',
+      'O redirect_uri registrado no PagBank é diferente do callback que este deploy usa. O fluxo de autorização OAuth falha silenciosamente até o cadastro ser corrigido no PagBank.',
     redirectUnreported:
       'A resposta do PagBank não trouxe redirect_uri, então não foi possível comparar com o callback.',
     fields: {
@@ -65,9 +65,24 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     fieldEmpty: '—',
     redirectNotReported: 'não informado',
     resolvedFrom:
-      'A aplicação deste ambiente é resolvida estritamente a partir destas variáveis, sem fallback entre ambientes:',
+      'A aplicação deste ambiente é resolvida a partir destas variáveis. O client_id e o client_secret são estritos, sem fallback entre ambientes; as demais, como o token, caem para a variável sem sufixo quando a deste ambiente não existe:',
     showConfig: 'Mostrar variáveis de ambiente',
     hideConfig: 'Ocultar variáveis de ambiente',
-    extraKeys: 'Outros campos retornados',
+    extraKeys: 'Outros campos retornados (schema não documentado)',
+    environmentLabels: { SANDBOX: 'Sandbox', PRODUCTION: 'Produção' },
+    previewHeading: 'Primeiros 5 caracteres de cada variável',
+    previewUnset: 'não definida',
+    previewInherited: 'não definida — usa o valor da variável sem sufixo:',
+    credentialNames: { clientId: 'client_id', clientSecret: 'client_secret', accountToken: 'token da conta' },
+    pasted: {
+      heading: 'Testar outras credenciais',
+      lede:
+        'Cole as credenciais de uma aplicação para consultá-la no PagBank antes de alterar as variáveis de ambiente. Os valores são usados só nesta consulta e não são salvos.',
+      environment: 'Ambiente',
+      submit: 'Consultar com estas credenciais',
+      failed: 'Não foi possível consultar com as credenciais coladas.',
+      secretNotChecked:
+        'O PagBank não verifica o client_secret nesta consulta — só o client_id e o token. Um client_secret errado só aparece na primeira autorização de loja.',
+    },
   },
 };

package/src/components/settings-live.ts

@@ -0,0 +1,66 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * The host's realtime channel for the settings screen (FUT-648).
+ *
+ * A provider's connection moves while nobody touches this tab: the OAuth grant
+ * completes in the tab the owner sent to the provider, a colleague saves a key
+ * or reorders the chain, a webhook or a sweep settles the activation charge.
+ * The screen read its view once on mount and then sat on it, so all of that
+ * reached the owner only through a reload.
+ *
+ * Nothing here knows what the channel is — the same split as the checkout's
+ * `CheckoutLiveSignal`. A host that can hear "this store's payment settings
+ * moved" passes whether its channel is live and a way to be told when it
+ * fires; the screen re-reads its view on every hint and once each time the
+ * channel (re)opens, because a hint published while it was down reached
+ * nobody. The hint carries nothing and is never trusted as data: the re-read
+ * goes through the same client, which is the only thing that decides what the
+ * owner may see.
+ *
+ * There is no timer, live or not. The screen never polled, so a host without a
+ * channel — or one whose channel is down — keeps exactly the mount read and its
+ * own actions' re-reads, as before.
+ */
+export interface PaymentsSettingsLiveSignal {
+  /** Whether the host's channel is connected right now. */
+  live: boolean;
+  /**
+   * Be told when the channel says this store's payment settings moved.
+   * Returns the unsubscribe. Should be stable across renders: a new function
+   * re-subscribes.
+   */
+  subscribe: (onHint: () => void) => () => void;
+}
+
+/**
+ * Re-read on every hint, and once whenever the channel goes from not-live to
+ * live — the first connect after mount included, since the mount read may
+ * have been answered before the subscription existed.
+ *
+ * `reload` is read through a ref so a host re-rendering with a new function
+ * neither re-subscribes nor re-reads.
+ */
+export function useSettingsLive(
+  signal: PaymentsSettingsLiveSignal | undefined,
+  reload: () => void,
+): void {
+  const latest = useRef(reload);
+  latest.current = reload;
+  const live = signal?.live === true;
+  const wasLive = useRef(live);
+  const subscribe = signal?.subscribe;
+
+  useEffect(() => {
+    const opened = live && !wasLive.current;
+    wasLive.current = live;
+    if (opened) latest.current();
+  }, [live]);
+
+  useEffect(() => {
+    if (!subscribe) return undefined;
+    return subscribe(() => latest.current());
+  }, [subscribe]);
+}

package/src/flows/create-payments-settings.tsx

@@ -18,10 +18,11 @@
  * settings page behind.
  *
  * **`prepareConnect`, `selectedProvider` / `onProviderChange`,
- * `initialProvider`, `onChanged`.** The OAuth CSRF state is minted against
+ * `initialProvider`, `onChanged`, `live`.** The OAuth CSRF state is minted against
  * the host's admin session; which provider is open may live in the host's
  * URL. Both are the host's, per render, and a factory that froze them would
- * make the page uncontrollable.
+ * make the page uncontrollable. `live` is the host's realtime channel, whose
+ * status changes from render to render (FUT-648).
  */
 
 import type { ComponentType, JSX } from "react";
@@ -32,6 +33,9 @@ import {
 } from "../components/PaymentProviderSettings";
 import type { PaymentsSettingsClient } from "../client";
 
+/** The `live` prop's shape — the host's channel, see `../components/settings-live`. */
+export type { PaymentsSettingsLiveSignal } from "../components/settings-live";
+
 /** What a host binds ONCE: the settings port. */
 export interface PaymentsSettingsWebConfig {
   /**

package/src/index.ts

@@ -323,7 +323,7 @@ export {
   type PaymentProviderSettingsProps,
 } from './components/PaymentProviderSettings';
 export { createWebPaymentsSettings } from './flows/create-payments-settings';
-export type { BoundPaymentsSettingsProps, PaymentsSettingsSurface, PaymentsSettingsWebConfig } from './flows/create-payments-settings';
+export type { BoundPaymentsSettingsProps, PaymentsSettingsLiveSignal, PaymentsSettingsSurface, PaymentsSettingsWebConfig } from './flows/create-payments-settings';
 
 // ---------------------------------------------------------------------------
 // The PLATFORM operations screens (FUT-479 / FUT-483, packaged by FUT-573) —