@12-apps/payments-frontend 3.3.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "type": "module",
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",
   "exports": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.12.0",
+    "@12-apps/payments-backend": "^4.13.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -28,7 +28,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/eslint-config": "^1.21.0",
     "@12-apps/typescript-config": "^1.20.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",

package/src/activation/copy.ts

@@ -0,0 +1,36 @@
+/**
+ * The four sentences the redirect activation protocol has to put on screen
+ * itself (FUT-763).
+ *
+ * It renders nothing — the host owns the screen — but four states are reached
+ * INSIDE the protocol and carry a reason the host never sees the raw form of:
+ * the provider answered with no message, the poll gave up, the link expired.
+ * Something has to be shown, and a fallback string compiled into the package is
+ * how one product's voice reaches every adopter (`DEFAULT_CHECKOUT_COPY_FE`,
+ * removed for exactly that in FUT-760).
+ *
+ * So there are no defaults and the field is required. A host that has not
+ * written these sentences finds out at the type level rather than by reading
+ * another company's tone of voice on its own settings screen.
+ */
+export interface RedirectActivationCopy {
+  /**
+   * The activation link's window elapsed with nothing paid.
+   *
+   * Distinct from a refusal on purpose: nothing was charged, so the only
+   * useful offer is another link.
+   */
+  chargeExpired: string;
+  /** The provider answered "not paid" definitively, with no message of its own. */
+  confirmFailed: string;
+  /** The provider would not mint the link at all. */
+  createFailed: string;
+  /**
+   * The bounded poll elapsed while the charge was still live.
+   *
+   * The wording is the part that matters and the part only a host can own: the
+   * charge IS still payable, and telling an owner who has genuinely paid that
+   * their payment did not arrive in time is worse than saying nothing.
+   */
+  confirmTimedOut: string;
+}

package/src/activation/mint-charge.ts

@@ -0,0 +1,77 @@
+import {
+  creationFailure,
+  postActivation,
+  refusedByProvider,
+  type ActivationClock,
+  type RedirectActivationState,
+} from './redirect-state';
+import type { RedirectActivationCopy } from './copy';
+
+/**
+ * Getting the owner onto the provider's payment page, in one press (FUT-763).
+ *
+ * Its own file because the ORDER of what happens inside that click is the whole
+ * content of it, and it is easy to lose in a hook full of effects.
+ */
+
+/** A tab claimed for the payment page, before its address is known. */
+interface PendingTab {
+  send: (url: string) => void;
+  discard: () => void;
+}
+
+/**
+ * Claim a tab SYNCHRONOUSLY, to be pointed somewhere once the link exists.
+ *
+ * Pressing the pay button should land the owner on the payment page — that is
+ * the whole action, and making them find a second button afterwards is the
+ * extra step this flow exists to remove. But the URL does not exist yet: it is
+ * minted by a request, and a `window.open` issued after that `await` has lost
+ * the user's gesture, so every popup blocker eats it.
+ *
+ * Deliberately without `noopener`: that flag makes `window.open` return null,
+ * leaving no handle to navigate. `opener` is cleared by hand instead.
+ */
+function claimTab(): PendingTab {
+  const tab = window.open('', '_blank');
+  if (tab) tab.opener = null;
+  return {
+    // `replace`, so the blank entry does not become a Back destination.
+    send: (target) => tab?.location.replace(target),
+    discard: () => tab?.close(),
+  };
+}
+
+/**
+ * Mint the link and point the claimed tab at it.
+ *
+ * The ORDER here is load-bearing: the tab is claimed inside the click (see
+ * {@link claimTab}), discarded rather than stranded on a refusal, and the poll
+ * clock is only started once a link actually exists.
+ */
+export async function mintCharge(io: {
+  url: string;
+  live: ActivationClock;
+  setState: (next: RedirectActivationState) => void;
+  copy: RedirectActivationCopy;
+  onCreateFailed?: () => void;
+}): Promise<void> {
+  const tab = claimTab();
+
+  io.setState({ kind: 'creating' });
+  const body = await postActivation(io.url, 'start');
+  if (!body?.ok || !body.checkoutUrl) {
+    // Never strand a blank tab on a failure the owner is about to read here.
+    tab.discard();
+    io.setState(creationFailure(body, io.copy));
+    // A dropped request means the provider refused NOTHING, so nothing the
+    // owner told us is called into question. Only an actual refusal withdraws
+    // their confirmation of the provider-side step.
+    if (refusedByProvider(body)) io.onCreateFailed?.();
+    return;
+  }
+  tab.send(body.checkoutUrl);
+  io.live.current.polling = true;
+  io.live.current.startedAt = Date.now();
+  io.setState({ kind: 'awaiting', checkoutUrl: body.checkoutUrl });
+}

package/src/activation/redirect-state.ts

@@ -0,0 +1,184 @@
+import type React from 'react';
+import type { MutableRefObject } from 'react';
+
+import type { RedirectActivationCopy } from './copy';
+
+/**
+ * What the redirect activation step can BE, and how one answer from the
+ * provider moves it — with no React and no requests anywhere near (FUT-763).
+ *
+ * Split from the hook because these are the decisions and the hook is the
+ * wiring: timers, mount effects, a claimed tab, a memoized callback. Together
+ * they were one file nobody could read the rules out of, and the rules are the
+ * part that costs money when it is wrong.
+ */
+
+export type RedirectActivationState =
+  | { kind: 'idle' }
+  | { kind: 'creating' }
+  /** Link live (URL present) or confirming a return trip (URL null). */
+  | {
+      kind: 'awaiting';
+      checkoutUrl: string | null;
+      /**
+       * A payment ATTEMPT was refused, on a charge that is still payable.
+       *
+       * It stays `awaiting` rather than becoming a failure because nothing
+       * about the link changed: the card said no, and the next move is another
+       * card or another method on this same link. Settling it would clear the
+       * outstanding charge and put a button offering to mint a SECOND real one
+       * on screen, while the first sits live at the provider.
+       */
+      declined?: string;
+    }
+  /** The link's window elapsed unpaid. Nothing was charged; offer another. */
+  | { kind: 'expired'; reason: string }
+  | { kind: 'passed' }
+  | {
+      kind: 'failed';
+      reason: string;
+      providerMessage?: string;
+      /**
+       * The provider refused to CREATE the link, rather than refusing the
+       * payment. A different failure with a different owner: no money moved and
+       * nothing is outstanding, and the overwhelmingly likely cause is a
+       * provider-side switch still being off — which is a step, not an error.
+       */
+      atCreation?: boolean;
+      /**
+       * …unless the provider was never reached at all, in which case it refused
+       * nothing and the step the owner already completed must survive untouched.
+       */
+      transport?: boolean;
+    };
+
+/** One answer from the host's verify-charge endpoint. */
+export interface ActivationPollBody {
+  ok?: boolean;
+  pending?: boolean;
+  reason?: string;
+  providerMessage?: string;
+  checkoutUrl?: string;
+  /** Which settled-and-negative answer this was. */
+  outcome?: 'expired' | 'declined' | 'refused';
+  /** The charge is still payable; the server deliberately kept it outstanding. */
+  retryable?: boolean;
+  /** `start` only: the provider was never reached, so it refused nothing. */
+  transport?: boolean;
+}
+
+/** The outstanding charge, as the server remembers it. */
+export interface ActivationPendingBody {
+  reference: string;
+  checkoutUrl: string;
+  slug?: string;
+  startedAt: string;
+}
+
+/**
+ * Ask the host's endpoint to start, poll, or discard the activation charge.
+ *
+ * A thrown fetch and an unparsable body both answer `null`, which is the same
+ * fact one layer out: nothing came back. {@link refusedByProvider} is what
+ * turns that into a decision.
+ */
+export async function postActivation(
+  url: string,
+  action: 'start' | 'poll' | 'discard',
+  extra: Record<string, string> = {},
+): Promise<ActivationPollBody | null> {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action, ...extra }),
+    });
+    return (await response.json().catch(() => null)) as ActivationPollBody | null;
+  } catch {
+    return null;
+  }
+}
+
+/** Live poll bookkeeping, mutated in place so a timer never reads a stale copy. */
+export type ActivationClock = MutableRefObject<{ polling: boolean; startedAt: number }>;
+
+/** What {@link settleActivationPoll} needs besides the answer itself. */
+export interface SettlePollIo {
+  live: ActivationClock;
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>;
+  onVerified: () => void;
+  /** Drop the parked return-trip ids — the charge is done with them. */
+  clearSettlement: () => void;
+  copy: RedirectActivationCopy;
+}
+
+/**
+ * Turn one poll answer into the screen's state, and say whether it SETTLED.
+ *
+ * Four outcomes, and the two in the middle are the ones worth naming. A
+ * `retryable` refusal is a payment ATTEMPT that failed on a charge still
+ * sitting live at the provider — so it stays `awaiting`, keeps the link on
+ * screen (paying it with another method is the entire fix) and does not stop
+ * the timer. An `expired` charge is the opposite: nobody can pay it now, so the
+ * only useful offer is another one.
+ */
+export function settleActivationPoll(body: ActivationPollBody | null, io: SettlePollIo): boolean {
+  if (!body) return false;
+  if (body.ok) {
+    io.live.current.polling = false;
+    io.clearSettlement();
+    io.setState({ kind: 'passed' });
+    io.onVerified();
+    return true;
+  }
+  if (body.pending) return false;
+  if (body.retryable) {
+    const declined = body.reason ?? '';
+    io.setState((current) =>
+      current.kind === 'awaiting'
+        ? { ...current, declined }
+        : { kind: 'awaiting', checkoutUrl: null, declined },
+    );
+    return false;
+  }
+  io.live.current.polling = false;
+  io.clearSettlement();
+  if (body.outcome === 'expired') {
+    io.setState({ kind: 'expired', reason: body.reason ?? io.copy.chargeExpired });
+    return true;
+  }
+  io.setState({
+    kind: 'failed',
+    reason: body.reason ?? io.copy.confirmFailed,
+    providerMessage: body.providerMessage,
+  });
+  return true;
+}
+
+/**
+ * Did the PROVIDER refuse, or was it simply never reached?
+ *
+ * `transport` says the request produced no response; a null body says the
+ * browser's own fetch threw, which is the same thing one layer out. Either way
+ * nothing was refused — and the distinction matters because a refusal, and only
+ * a refusal, is evidence that a step the owner ticked off is not in fact done.
+ * Treating an outage as one sends someone whose network blinked back to redo a
+ * finished step, to change a setting that was already correct.
+ */
+export function refusedByProvider(body: ActivationPollBody | null): boolean {
+  return Boolean(body) && !body?.transport;
+}
+
+/** The failed state a refused (or unreachable) `start` leaves behind. */
+export function creationFailure(
+  body: ActivationPollBody | null,
+  copy: RedirectActivationCopy,
+): RedirectActivationState {
+  return {
+    kind: 'failed',
+    reason: body?.reason ?? copy.createFailed,
+    providerMessage: body?.providerMessage,
+    atCreation: true,
+    ...(refusedByProvider(body) ? {} : { transport: true }),
+  };
+}

package/src/activation/returned-settlement.ts

@@ -0,0 +1,117 @@
+/**
+ * The settlement a redirect provider hands back on the return trip, made
+ * durable (FUT-763).
+ *
+ * The activation charge is paid on the PROVIDER'S site, so "left this page and
+ * came back" is the normal path. The provider appends the ids that prove the
+ * payment to the return URL, and those ids exist nowhere before the payment
+ * and — without care — nowhere after the first render: reading and scrubbing
+ * them in one call destroys them on a re-render, and a reload (the natural
+ * reaction to a screen that looks stuck) destroys an in-memory copy too.
+ *
+ * So they are parked in `sessionStorage` BEFORE the URL is scrubbed, survive
+ * both, and are cleared only when the charge settles.
+ *
+ * This is protocol, not presentation, which is why it moved: every host that
+ * mounts a redirect provider gets the same return trip, and the ordering above
+ * is not something a host should have to rediscover — it was rediscovered once
+ * already, by a payment that was confirmed, thrown away, and never asked about
+ * again.
+ */
+
+/**
+ * The default parking slot.
+ *
+ * Namespaced by the package rather than by an app, and overridable, so two
+ * surfaces of the same host can run the flow without reading each other's
+ * parked ids.
+ */
+export const RETURNED_SETTLEMENT_KEY = 'payments:activation-settlement';
+
+/**
+ * The ids a redirect provider appends, and the aliases it may use for them.
+ *
+ * Both matter, and this was measured against the live API rather than read off
+ * a doc page:
+ *
+ *   handle + order id + transaction id + slug → paid
+ *   the same call minus the slug              → not paid
+ *   the same call minus the transaction id    → not paid
+ *
+ * Neither is optional and neither exists before the payment. Asking with only
+ * the transaction id — while expecting the slug from link creation, where the
+ * provider does not put it — is a question that always answers no.
+ */
+const TRANSACTION_PARAMS = ['transaction_nsu', 'transaction_id'] as const;
+const SLUG_PARAM = 'slug';
+
+/**
+ * Everything the return trip may carry, scrubbed together.
+ *
+ * Wider than what is READ: a receipt link and a capture method identify a
+ * payment just as well, and have no business persisting in a URL somebody
+ * might copy or a history entry a reload might replay.
+ */
+const SETTLEMENT_PARAMS = [
+  ...TRANSACTION_PARAMS,
+  'order_nsu',
+  SLUG_PARAM,
+  'receipt_url',
+  'capture_method',
+];
+
+function parked(storageKey: string): Record<string, string> {
+  try {
+    const raw = window.sessionStorage.getItem(storageKey);
+    return raw ? (JSON.parse(raw) as Record<string, string>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The charge settled — either way — so the parked ids have done their job. */
+export function clearReturnedSettlement(storageKey = RETURNED_SETTLEMENT_KEY): void {
+  try {
+    window.sessionStorage.removeItem(storageKey);
+  } catch {
+    // Best-effort: a stale parked value is re-sent once and ignored server-side.
+  }
+}
+
+/**
+ * Read the return trip's ids, park them, and take them out of the address bar.
+ *
+ * Safe to call on every render and every poll — which it is. With nothing in
+ * the URL it answers with whatever is already parked, so the fifth ask carries
+ * the same proof as the first.
+ */
+export function takeReturnedSettlement(
+  storageKey = RETURNED_SETTLEMENT_KEY,
+): Record<string, string> {
+  if (typeof window === 'undefined') return {};
+
+  const params = new URLSearchParams(window.location.search);
+  const transactionNsu = TRANSACTION_PARAMS.map((key) => params.get(key)).find(Boolean) ?? '';
+  const slug = params.get(SLUG_PARAM) ?? '';
+  if (!transactionNsu && !slug) return parked(storageKey);
+
+  const captured = {
+    ...(transactionNsu ? { transactionNsu } : {}),
+    ...(slug ? { slug } : {}),
+  };
+  try {
+    window.sessionStorage.setItem(storageKey, JSON.stringify(captured));
+  } catch {
+    // Storage refused (private-mode quirks): the in-URL copy still exists for
+    // this page-load, and the server persists the slug after one good poll.
+  }
+  scrubSettlementParams(params);
+  return captured;
+}
+
+/** Take the settlement params back out of the address bar, read once. */
+function scrubSettlementParams(params: URLSearchParams): void {
+  for (const key of SETTLEMENT_PARAMS) params.delete(key);
+  const query = params.toString();
+  window.history.replaceState({}, '', `${window.location.pathname}${query ? `?${query}` : ''}`);
+}

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

@@ -30,9 +30,9 @@ import type { ActivationChargeCopy } from './charge-copy';
  * been homologated.
  *
  * So the owner puts their own card through the SAME path a shopper takes — same
- * fields, same validation, same browser-side encryption — for one cent,
- * refunded immediately. Whatever would break for a buyer breaks here, in front
- * of the person who can fix it.
+ * fields, same validation, same browser-side encryption — for the smallest
+ * amount that provider will actually accept, refunded immediately. Whatever
+ * would break for a buyer breaks here, in front of the person who can fix it.
  *
  * The sibling of `useRedirectActivation`, for the other half of the same step:
  * that one is for a provider whose payer leaves for its own page. Both prove
@@ -86,6 +86,20 @@ export interface ActivationCharge {
   cpf: string;
   setCpf: (value: string) => void;
   cpfError: string | undefined;
+  /**
+   * What this charge will COST, in cents — `null` until the endpoint answers.
+   *
+   * Not always one cent, which is the whole reason it is asked for rather than
+   * assumed: at least one provider refuses a one-cent total outright, so its
+   * verification charge is worth more, and the minimum is a fact about that
+   * provider's API rather than a number this package may pick.
+   *
+   * `null` rather than a fallback for the same reason the copy has no
+   * defaults: what to put on a button before the truth arrives is the host's
+   * sentence to write, and a package guessing here would have the screen
+   * promise one amount and charge another.
+   */
+  amountCents: number | null;
   state: ActivationChargeState;
   submit: () => Promise<void>;
   /** Back to the form from a settled state, to try another card. */
@@ -93,20 +107,54 @@ export interface ActivationCharge {
 }
 
 /**
- * The store's own card public key, fetched through the VERIFICATION endpoint.
+ * What the verification endpoint says about the charge BEFORE it is made.
  *
- * Not the checkout one: that reads credentials through the enabled gate, and a
- * provider being verified is by definition still disabled.
+ * Two facts, one request, because the endpoint answers both in one body and
+ * they are needed on the same screen at the same moment. They were two asks
+ * for the same URL — the key read here, the amount read by the host — which is
+ * one request per render pass more than the truth costs, and two places for
+ * the answer to be interpreted differently.
+ *
+ * The endpoint is the VERIFICATION one, not checkout's: that reads credentials
+ * through the enabled gate, and a provider being verified is by definition
+ * still disabled.
  */
-function usePublicKey(verifyChargeUrl: string): string | null {
-  const [publicKey, setPublicKey] = useState<string | null>(null);
+interface ActivationProbe {
+  publicKey: string | null;
+  amountCents: number | null;
+}
+
+/** Before the endpoint has answered, both facts are simply unknown. */
+const UNKNOWN_PROBE: ActivationProbe = { publicKey: null, amountCents: null };
+
+/** The endpoint's `GET` body — every field optional; a host may answer neither. */
+interface ProbeBody {
+  publicKey?: string | null;
+  amountCents?: number | null;
+}
+
+function readProbe(body: ProbeBody | null): ActivationProbe {
+  return {
+    publicKey: body?.publicKey ? body.publicKey : null,
+    amountCents: typeof body?.amountCents === 'number' ? body.amountCents : null,
+  };
+}
+
+function useActivationProbe(verifyChargeUrl: string): ActivationProbe {
+  const [probe, setProbe] = useState<ActivationProbe>(UNKNOWN_PROBE);
 
   useEffect(() => {
     const alive = { current: true };
+    // Forgotten FIRST, before the new answer is asked for. A screen that moves
+    // between providers keeps this hook mounted, and holding the previous
+    // provider's key across the gap would tokenize the card with one vendor's
+    // key and send the blob to another — which arrives as that second
+    // provider's refusal, reading exactly like a bad card.
+    setProbe(UNKNOWN_PROBE);
     void fetch(verifyChargeUrl)
-      .then((res) => (res.ok ? (res.json() as Promise<{ publicKey?: string | null }>) : null))
+      .then((res) => (res.ok ? (res.json() as Promise<ProbeBody>) : null))
       .then((body) => {
-        if (alive.current && body?.publicKey) setPublicKey(body.publicKey);
+        if (alive.current) setProbe(readProbe(body));
       })
       .catch(() => undefined);
     return () => {
@@ -114,7 +162,7 @@ function usePublicKey(verifyChargeUrl: string): string | null {
     };
   }, [verifyChargeUrl]);
 
-  return publicKey;
+  return probe;
 }
 
 /** Local validation — nothing reaches the provider until the card is well-formed. */
@@ -205,7 +253,7 @@ function useCardForm() {
 
 export function useActivationCharge(options: ActivationChargeOptions): ActivationCharge {
   const { verifyChargeUrl, provider, email, onVerified, copy } = options;
-  const publicKey = usePublicKey(verifyChargeUrl);
+  const probe = useActivationProbe(verifyChargeUrl);
   const form = useCardForm();
   const [state, setState] = useState<ActivationChargeState>({ kind: 'idle' });
   const { card, cpf, setFieldErrors, setCpfError, clear } = form;
@@ -222,7 +270,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
       provider,
       card,
       cpf,
-      publicKey,
+      publicKey: probe.publicKey,
       email,
       copy,
     });
@@ -235,7 +283,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
   }, [
     card,
     cpf,
-    publicKey,
+    probe.publicKey,
     verifyChargeUrl,
     provider,
     email,
@@ -260,6 +308,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
     cpf: form.cpf,
     setCpf: form.setCpf,
     cpfError: form.cpfError,
+    amountCents: probe.amountCents,
     state,
     submit,
     reset,

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

@@ -0,0 +1,341 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type React from 'react';
+
+import type { RedirectActivationCopy } from './copy';
+import { mintCharge } from './mint-charge';
+import {
+  postActivation,
+  settleActivationPoll,
+  type ActivationClock,
+  type ActivationPendingBody,
+  type ActivationPollBody,
+  type RedirectActivationState,
+} from './redirect-state';
+import { clearReturnedSettlement, takeReturnedSettlement } from './returned-settlement';
+
+/**
+ * The activation step for a provider whose payer pays on ITS page (FUT-463,
+ * moved here by FUT-763).
+ *
+ * Same proof as a card form, different protocol: a REAL link is minted through
+ * this store's own connection, the owner pays it on the provider's site, and
+ * the provider is then ASKED whether it arrived. Only that answer activates the
+ * store. The alternative — telling an owner to "make a real low-value order and
+ * confirm the money arrives" — is the dead-end instruction the step exists to
+ * abolish.
+ *
+ * ## What is the package's here, and what is not
+ *
+ * `renderVerification` on `PaymentProviderSettings` says the package decides
+ * only WHERE the step appears, never how it works. That still holds for the
+ * SCREEN: the panels, the states an owner reads, the sentences — all of that is
+ * the host's, and none of it is here.
+ *
+ * What is here is the PROTOCOL, which is not a matter of taste and is not
+ * something a second host should get to rediscover: pick the outstanding charge
+ * back up on mount, ask with the return trip's ids on every tick, keep a
+ * refused ATTEMPT distinct from an expired charge, keep an unreachable provider
+ * distinct from a refusing one, stop asking eventually. Every one of those was
+ * learned from a payment that went wrong, and three of them cost a real charge.
+ *
+ * ## Why the attempt is the SERVER's
+ *
+ * It used to live in React state, and that was wrong in a way that costs money.
+ * The flow deliberately sends the owner to another site to pay, so "left this
+ * page and came back" is the NORMAL path, not an edge case — and it erased the
+ * attempt every time. The screen then offered to generate a charge, because as
+ * far as it knew none existed: a second real charge on the owner's own card,
+ * while the first, already paid, was never asked about again.
+ *
+ * So the outstanding charge is loaded from the server on mount, and the only
+ * things that clear it are settlement and an explicit "give up".
+ */
+
+/** How often to ask the provider whether the payment landed. */
+const DEFAULT_POLL_MS = 4000;
+
+/** Give up asking after this long, rather than polling a tab forever. */
+const DEFAULT_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+
+export interface RedirectActivationOptions {
+  /**
+   * The host's verify-charge endpoint for this provider.
+   *
+   * A whole URL, not the parts of one: the route shape belongs to the host and
+   * the package has no business assembling it. `GET` answers the outstanding
+   * charge; `POST` takes `{ action: 'start' | 'poll' | 'discard' }`.
+   */
+  verifyChargeUrl: string;
+  /** A passing charge — the caller refreshes so the provider shows as active. */
+  onVerified: () => void;
+  /**
+   * The provider would not mint a link. Called instead of, not as well as,
+   * settling anything: no charge exists, so there is nothing to confirm — the
+   * caller uses it to reopen the setup step this failure implicates.
+   */
+  onCreateFailed?: () => void;
+  copy: RedirectActivationCopy;
+  /** Where the return trip's ids are parked. Defaults per the package. */
+  storageKey?: string;
+  pollMs?: number;
+  pollTimeoutMs?: number;
+}
+
+export interface RedirectActivation {
+  state: RedirectActivationState;
+  /**
+   * When the provider last answered, as epoch ms (0 before the first ask).
+   *
+   * Shown as "last checked Ns ago". A spinner alone says "something is
+   * happening"; this says the screen is still asking, which is the reassurance
+   * someone who has just paid on another site actually wants — and it is what
+   * stops them pressing a pay button again to be sure.
+   */
+  lastCheckedAt: number;
+  /** Mint the link and begin asking. */
+  start: () => Promise<void>;
+  /** Ask right now, instead of waiting for the next tick. */
+  checkNow: () => Promise<void>;
+  /** Abandon the outstanding charge and offer a fresh one. */
+  reset: () => void;
+}
+
+/**
+ * What the effects call, read through a ref rather than through their deps.
+ *
+ * NOT a style preference — it is what makes the hook safe to hand to a host.
+ * Every callback here changes identity when the caller re-renders without
+ * memoizing, and both effects below would then re-run on it: the resume effect
+ * would re-mount the whole sequence (and, since it sets state, re-render, and
+ * loop), and the poll timer would be cleared and restarted before it ever
+ * ticked — a screen that asks the provider nothing, for ever, while looking
+ * exactly like one that is asking.
+ *
+ * The host that wrote this flow happened to memoize, so neither ever fired
+ * there. A package cannot rely on that: `useRedirectActivation({ onVerified:
+ * () => reload() })` is the obvious way to call it.
+ */
+interface ActivationCallbacks {
+  applyPoll: (body: ActivationPollBody | null) => boolean;
+  returned: () => Record<string, string>;
+  timedOut: string;
+}
+
+/**
+ * Ask the provider every few seconds, and stop asking eventually.
+ *
+ * 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.
+ */
+function usePollTimer(
+  active: boolean,
+  url: string,
+  live: ActivationClock,
+  latest: React.MutableRefObject<ActivationCallbacks>,
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>,
+  pollMs: number,
+  pollTimeoutMs: number,
+): void {
+  useEffect(() => {
+    if (!active) return;
+    const timer = setInterval(() => {
+      if (!live.current.polling) return;
+      if (Date.now() - live.current.startedAt > pollTimeoutMs) {
+        live.current.polling = false;
+        setState({ kind: 'failed', reason: latest.current.timedOut });
+        return;
+      }
+      // WITH the ids, every tick. A hint-less poll is measured to answer "not
+      // paid" for payments that happened — one hinted ask on resume made a
+      // single dropped request fatal.
+      void postActivation(url, 'poll', latest.current.returned()).then((body) =>
+        latest.current.applyPoll(body),
+      );
+    }, pollMs);
+    return () => clearInterval(timer);
+  }, [active, url, live, latest, setState, pollMs, pollTimeoutMs]);
+}
+
+/**
+ * Pick the outstanding charge back up on mount.
+ *
+ * This is what makes the return trip work at all. The owner is sent to the
+ * provider's site to pay and comes back here holding the ids that let the
+ * payment be confirmed — so the very first thing this does on load is ask
+ * whether a charge is outstanding and, if so, check it immediately with
+ * whatever the redirect brought back.
+ */
+function useResumeOutstanding(
+  url: string,
+  live: ActivationClock,
+  latest: React.MutableRefObject<ActivationCallbacks>,
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>,
+): void {
+  useEffect(() => {
+    const alive = { current: true };
+    const carried = latest.current.returned();
+
+    // An owner who came back holding a settlement has DEMONSTRABLY paid, so the
+    // screen must be confirming from the first frame — never showing the pay
+    // button, whatever the pending row says and whatever any single request
+    // does. `checkoutUrl: null` renders the confirming panel without an
+    // open-link button. This also arms the timer, so one dropped request costs
+    // four seconds rather than the payment.
+    if (Object.keys(carried).length > 0) {
+      live.current.polling = true;
+      live.current.startedAt = Date.now();
+      setState({ kind: 'awaiting', checkoutUrl: null });
+    }
+
+    void resumeSequence({ url, live, latest, setState }, carried, alive);
+
+    return () => {
+      alive.current = false;
+    };
+  }, [url, live, latest, setState]);
+}
+
+/** Everything the resume sequence reaches for, gathered once. */
+interface ResumeIo {
+  url: string;
+  live: ActivationClock;
+  latest: React.MutableRefObject<ActivationCallbacks>;
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>;
+}
+
+/** The resume sequence, in the order that keeps a paid return confirmable. */
+async function resumeSequence(
+  io: ResumeIo,
+  carried: Record<string, string>,
+  alive: { current: boolean },
+): Promise<void> {
+  const cameBack = Object.keys(carried).length > 0;
+  // Fired FIRST, and not gated on the pending GET below: this ask depends on
+  // nothing but the returned ids, and chaining it behind another request's
+  // success is how a mid-refresh session cookie once turned a confirmed payment
+  // into a pay button.
+  if (cameBack) {
+    const polled = await postActivation(io.url, 'poll', carried);
+    if (alive.current) io.latest.current.applyPoll(polled);
+  }
+  await restoreOutstanding(io, carried, alive, cameBack);
+}
+
+/**
+ * The GET's answer: the outstanding charge, and whether the server settled it
+ * during this very read (its own heal path).
+ */
+interface OutstandingBody {
+  pending?: ActivationPendingBody;
+  proven?: boolean;
+}
+
+async function readOutstanding(url: string): Promise<OutstandingBody | null> {
+  const response = await fetch(url).catch(() => null);
+  if (!response?.ok) return null;
+  return (await response.json().catch(() => null)) as OutstandingBody | null;
+}
+
+/** Restore the server's pending row into the screen, and ask once if idle. */
+async function restoreOutstanding(
+  io: ResumeIo,
+  carried: Record<string, string>,
+  alive: { current: boolean },
+  cameBack: boolean,
+): Promise<void> {
+  const body = await readOutstanding(io.url);
+  if (!body || !alive.current) return;
+  // Settled server-side while we were reading — the charge is done, and the one
+  // thing this must not do now is resume a pay flow for it.
+  if (body.proven) {
+    io.latest.current.applyPoll({ ok: true });
+    return;
+  }
+  const pending = body.pending;
+  if (!pending) return;
+
+  io.live.current.polling = true;
+  io.live.current.startedAt = Date.parse(pending.startedAt) || Date.now();
+  io.setState((current) =>
+    current.kind === 'passed' || current.kind === 'failed'
+      ? current
+      : { kind: 'awaiting', checkoutUrl: pending.checkoutUrl },
+  );
+  if (!cameBack) {
+    const polled = await postActivation(io.url, 'poll', carried);
+    if (alive.current) io.latest.current.applyPoll(polled);
+  }
+}
+
+export function useRedirectActivation(options: RedirectActivationOptions): RedirectActivation {
+  const {
+    verifyChargeUrl: url,
+    onVerified,
+    onCreateFailed,
+    copy,
+    storageKey,
+    pollMs = DEFAULT_POLL_MS,
+    pollTimeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+  } = options;
+
+  const [state, setState] = useState<RedirectActivationState>({ kind: 'idle' });
+  const [lastCheckedAt, setLastCheckedAt] = useState(0);
+  // Read inside the interval callback so the timer never closes over a stale
+  // state — mutating a ref's property rather than reassigning a captured
+  // binding, which the flakiness lint rightly rejects.
+  const live = useRef({ polling: false, startedAt: 0 });
+
+  const returned = useCallback(() => takeReturnedSettlement(storageKey), [storageKey]);
+
+  const applyPoll = useCallback(
+    (body: ActivationPollBody | null): boolean => {
+      // Stamped even on a dropped request: the counter reports when we last
+      // ASKED, and freezing it on a network blip would read as a stalled screen.
+      setLastCheckedAt(Date.now());
+      return settleActivationPoll(body, {
+        live,
+        setState,
+        onVerified,
+        clearSettlement: () => clearReturnedSettlement(storageKey),
+        copy,
+      });
+    },
+    [onVerified, storageKey, copy],
+  );
+
+  const latest = useRef<ActivationCallbacks>({
+    applyPoll,
+    returned,
+    timedOut: copy.confirmTimedOut,
+  });
+  latest.current = { applyPoll, returned, timedOut: copy.confirmTimedOut };
+
+  useResumeOutstanding(url, live, latest, setState);
+  usePollTimer(state.kind === 'awaiting', url, live, latest, setState, pollMs, pollTimeoutMs);
+
+  const start = useCallback(
+    () => mintCharge({ url, live, setState, copy, onCreateFailed }),
+    [url, copy, onCreateFailed],
+  );
+
+  const checkNow = useCallback(async () => {
+    applyPoll(await postActivation(url, 'poll', returned()));
+  }, [applyPoll, url, returned]);
+
+  /**
+   * Give up on the outstanding charge — and tell the SERVER so.
+   *
+   * Clearing only the local state would leave the charge on record, so the very
+   * next load would resume the attempt the owner just abandoned.
+   */
+  const reset = useCallback(() => {
+    live.current.polling = false;
+    setState({ kind: 'idle' });
+    void postActivation(url, 'discard');
+  }, [url]);
+
+  return { state, lastCheckedAt, start, checkNow, reset };
+}

package/src/components/connect-preparer.ts

@@ -0,0 +1,97 @@
+import type { PaymentEnvironment } from '@12-apps/payments-backend';
+
+import type { PrepareConnect } from './ProviderPanel';
+
+/**
+ * The START of the connect round trip (FUT-763) — the sibling of
+ * `takeConnectReturn`, which owns its end.
+ *
+ * Before an owner is sent to the provider's site, a CSRF state is minted on
+ * the host's server, pinned to an httpOnly cookie there and compared on the
+ * way back. The browser only relays it, so a forged connect cannot start here
+ * — and the environment travels sealed into that same cookie, so a SANDBOX
+ * choice cannot come back as a PRODUCTION grant.
+ *
+ * The ROUTE that mints it is the host's; everything else about the exchange is
+ * this package's, and was being restated by every host that implemented
+ * `prepareConnect` by hand: the method, the content type, what a failure is,
+ * and the shape of the answer. That last one is the reason this exists rather
+ * than a copied snippet — see below.
+ */
+
+/** What the host's prepare endpoint answers. */
+interface PreparedConnect {
+  state: string;
+  redirectUri: string;
+  environment?: PaymentEnvironment;
+}
+
+export interface ConnectPreparerOptions {
+  /**
+   * The host's OAuth-prepare endpoint for one provider and environment.
+   *
+   * A builder rather than a whole URL because the provider is not fixed for
+   * this screen the way it is for a verification charge — the owner picks one,
+   * and the route shape still belongs to the host.
+   */
+  prepareUrl: (provider: string, environment: PaymentEnvironment) => string;
+  /**
+   * What the owner is told when no connect could be started.
+   *
+   * Required and with no default, like every other sentence this package
+   * needs: a fallback compiled in here is how one product's voice reaches
+   * every adopter.
+   */
+  mintFailed: string;
+}
+
+/** The two environments, for checking what came back is one of them. */
+const ENVIRONMENTS: readonly PaymentEnvironment[] = ['SANDBOX', 'PRODUCTION'];
+
+/**
+ * Refuse an answer that cannot start a connect.
+ *
+ * A hand-written preparer casts the body and hands it straight on, so a `200`
+ * carrying the wrong shape sends the owner to the provider with
+ * `state=undefined` in the URL. That does not fail here — it fails on the way
+ * BACK, as `state_mismatch`, two steps and one provider site later, and reads
+ * as "the connection expired" to someone whose connection never started.
+ *
+ * The mint either produced a usable state and a place to send them, or it
+ * failed. There is no third answer worth acting on.
+ */
+function usable(body: unknown): body is PreparedConnect {
+  if (typeof body !== 'object' || body === null) return false;
+  const candidate = body as Partial<PreparedConnect>;
+  return typeof candidate.state === 'string' && candidate.state.length > 0
+    && typeof candidate.redirectUri === 'string' && candidate.redirectUri.length > 0;
+}
+
+/**
+ * Build the `prepareConnect` a host hands to `PaymentProviderSettings`.
+ *
+ * The environment is echoed back only when the answer names one this package
+ * knows. The SERVER is the authority on it — it is what sealed the cookie — so
+ * an unrecognised value is dropped rather than argued with, and the caller
+ * keeps the environment it asked for.
+ */
+export function createConnectPreparer(options: ConnectPreparerOptions): PrepareConnect {
+  return async (provider, environment) => {
+    const response = await fetch(options.prepareUrl(provider, environment), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+    });
+    if (!response.ok) throw new Error(options.mintFailed);
+
+    const body: unknown = await response.json().catch(() => null);
+    if (!usable(body)) throw new Error(options.mintFailed);
+
+    return {
+      state: body.state,
+      redirectUri: body.redirectUri,
+      environment: ENVIRONMENTS.includes(body.environment as PaymentEnvironment)
+        ? body.environment
+        : undefined,
+    };
+  };
+}

package/src/components/connect-return.ts

@@ -0,0 +1,113 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * What the OAuth connect callback redirected back with — read once, then
+ * erased from the address bar (FUT-763).
+ *
+ * The owner leaves for the provider's site to authorize us and comes back to a
+ * URL carrying the verdict. That round trip is the package's: `OAuthPanel`
+ * starts it, `PaymentProviderSettings` already reads `?connected=` as the raw
+ * provider name to reopen the right panel, and the codes below are the ones a
+ * connect can fail with. A host re-deriving any of it is re-deriving this
+ * package's own contract from the outside.
+ *
+ * What is NOT here is the sentence. `errorCode` comes back as a CODE precisely
+ * so the words stay the host's, which is the same rule the activation copy
+ * follows — a fallback string compiled in here is how one product's voice
+ * reaches every adopter.
+ */
+
+/**
+ * How a connect can fail, as the callback spells it.
+ *
+ * A union rather than a loose string because these five are shared between a
+ * host's callback ROUTE, which emits them, and its copy map, which renders
+ * them — two files that today agree by luck. Typed, a host's
+ * `Record<ConnectErrorCode, string>` is checked for exhaustiveness, and a
+ * provider failure mode nobody wrote a sentence for stops compiling.
+ */
+export type ConnectErrorCode =
+  /** The owner declined on the provider's site. Nothing changed. */
+  | 'access_denied'
+  /** The CSRF state did not match — expired, or started in another tab. */
+  | 'state_mismatch'
+  /** The provider came back without an authorization code. */
+  | 'missing_code'
+  /** The callback did not say which provider it was for. */
+  | 'missing_provider'
+  /** The code could not be exchanged for a grant. */
+  | 'exchange_failed';
+
+export interface ConnectReturn {
+  /**
+   * The provider that was just connected, as the callback spells it — which is
+   * the RAW name, not the URL slug. `PaymentProviderSettings` resolves either.
+   */
+  connected: string | null;
+  /**
+   * Why it failed, as a code — `null` when nothing failed.
+   *
+   * Deliberately widened to `string`: a code outside {@link ConnectErrorCode}
+   * is passed through rather than dropped, because a host that has taught its
+   * own callback a new failure is not wrong — it just has a sentence this
+   * package does not know about. The union is what its copy map is keyed by;
+   * this is what its callback actually said.
+   */
+  errorCode: string | null;
+}
+
+const NOTHING: ConnectReturn = { connected: null, errorCode: null };
+
+/**
+ * The params the connect callback owns. Erased together, and ONLY these — a
+ * host's own query string survives the scrub.
+ */
+const CONNECT_PARAMS = ['connected', 'connectError', 'provider'] as const;
+
+/**
+ * Take the callback's verdict out of the address bar.
+ *
+ * Erasing is the point, not tidiness: the query string is the only place this
+ * state lives, so leaving it there means a reload re-announces a connection
+ * that already happened — and, worse, re-announces a FAILURE the owner has
+ * since fixed.
+ *
+ * Take-once by construction: the second call finds nothing, because the first
+ * removed it. Callers hold the result.
+ */
+export function takeConnectReturn(): ConnectReturn {
+  // Server-rendered, or a test with no DOM: there is no address bar to read.
+  if (typeof window === 'undefined') return NOTHING;
+
+  const params = new URLSearchParams(window.location.search);
+  const connected = params.get('connected');
+  const errorCode = params.get('connectError');
+  if (!connected && !errorCode) return NOTHING;
+
+  for (const key of CONNECT_PARAMS) params.delete(key);
+  const query = params.toString();
+  window.history.replaceState({}, '', `${window.location.pathname}${query ? `?${query}` : ''}`);
+
+  return { connected, errorCode };
+}
+
+/**
+ * {@link takeConnectReturn} for a screen: taken after mount, held across every
+ * later render.
+ *
+ * Only ever SETS when something was found, which is what keeps it correct
+ * under a StrictMode double-mount: the second run finds an already-scrubbed
+ * URL, and must not overwrite the verdict the first one caught.
+ */
+export function useConnectReturn(): ConnectReturn {
+  const [taken, setTaken] = useState<ConnectReturn>(NOTHING);
+
+  useEffect(() => {
+    const outcome = takeConnectReturn();
+    if (outcome.connected || outcome.errorCode) setTaken(outcome);
+  }, []);
+
+  return taken;
+}

package/src/index.ts

@@ -209,6 +209,15 @@ export {
   type SetupGuideSectionProps,
 } from './components/SetupGuideSection';
 export { ProviderStatusBar, statusBadge } from './components/ProviderStatusBar';
+// The START of the connect round trip (FUT-763): the `prepareConnect` a host
+// hands to the settings screen, built from its own prepare route. The route is
+// the host's; the exchange — method, shape, and what counts as a failure — is
+// this package's, and a hand-written one casts the answer instead of checking
+// it.
+export {
+  createConnectPreparer,
+  type ConnectPreparerOptions,
+} from './components/connect-preparer';
 export {
   PaymentProviderSettings,
   type PaymentProviderSettingsProps,
@@ -243,6 +252,52 @@ export {
  */
 export type { PaymentEnvironment } from '@12-apps/payments-backend';
 
+// ---------------------------------------------------------------------------
+// The REDIRECT ACTIVATION protocol (FUT-463, packaged by FUT-763) — proving a
+// connection can charge, for a provider whose payer pays on its own page.
+//
+// `renderVerification` above stays what it was: the package decides where the
+// step appears and the host owns the screen. What moved is the protocol behind
+// it — resume-on-mount, the return trip's ids, the refusal/expiry/transport
+// distinctions, the bounded wait. Every one of those was learned from a payment
+// that went wrong, and no second host should have to learn them again.
+// ---------------------------------------------------------------------------
+export {
+  useRedirectActivation,
+  type RedirectActivation,
+  type RedirectActivationOptions,
+} from './activation/use-redirect-activation';
+export { type RedirectActivationCopy } from './activation/copy';
+export {
+  creationFailure,
+  postActivation,
+  refusedByProvider,
+  settleActivationPoll,
+  type ActivationClock,
+  type ActivationPendingBody,
+  type ActivationPollBody,
+  type RedirectActivationState,
+  type SettlePollIo,
+} from './activation/redirect-state';
+export {
+  clearReturnedSettlement,
+  takeReturnedSettlement,
+  RETURNED_SETTLEMENT_KEY,
+} from './activation/returned-settlement';
+
+// ---------------------------------------------------------------------------
+// The connect ROUND TRIP's other end (FUT-763): what the OAuth callback
+// redirected back with, taken out of the address bar once. The codes are a
+// union so a host's copy map is exhaustiveness-checked; the sentences stay the
+// host's, as everywhere else in this package.
+// ---------------------------------------------------------------------------
+export {
+  takeConnectReturn,
+  useConnectReturn,
+  type ConnectErrorCode,
+  type ConnectReturn,
+} from './components/connect-return';
+
 // ---------------------------------------------------------------------------
 // The ACTIVATION CHARGE (FUT-463, packaged by FUT-763) — proving a connection
 // can charge, for a provider whose payer pays HERE.