@12-apps/payments-frontend 3.4.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.4.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": {
@@ -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-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/index.ts

@@ -252,6 +252,39 @@ 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