@12-apps/payments-frontend 1.0.0 → 1.2.0

package/src/card/tokenize.test.ts

@@ -0,0 +1,194 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { tokenizeForCheckout, tokenizerFor } from "./tokenize";
+import type { CardDetails } from "./types";
+
+/** A Luhn-valid Visa test PAN (the mock path validates before minting). */
+const VALID_CARD: CardDetails = {
+  number: "4111 1111 1111 1111",
+  holder: "Ana Compradora",
+  expiry: "12/39",
+  cvv: "123",
+};
+
+/** The always-declines test PAN the mock encodes as `tok_declined…`. */
+const DECLINE_CARD: CardDetails = { ...VALID_CARD, number: "4000 0000 0000 0002" };
+
+describe("tokenizeForCheckout — the mock gate (FUT-697)", () => {
+  it("NEVER mints a mock token without server-granted stub permission", async () => {
+    // The exact production shape of the bug: a Stone/Stripe store resolved to
+    // a null PagBank key, and the old fallback minted a fake `tok_…` that
+    // entered a real charge. With no `mockTokenization` grant, the answer is
+    // a clear bail BEFORE any money moves.
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: "stripe",
+      publicKey: null,
+      mockTokenization: false,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("indisponível");
+  });
+
+  it("bails clearly for a provider with no browser scheme, even WITH a key", async () => {
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: "infinitepay",
+      publicKey: "pk_live_123",
+      mockTokenization: false,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("indisponível");
+  });
+
+  it("bails clearly when the store has no provider at all", async () => {
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: null,
+      publicKey: null,
+      mockTokenization: false,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("indisponível");
+  });
+
+  it("mints the mock token under stub permission (dev / e2e path)", async () => {
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: "pagbank",
+      publicKey: null,
+      mockTokenization: true,
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.token).toMatch(/^tok/);
+      expect(result.data.token).not.toMatch(/^tok_declined/);
+      expect(result.data.last4).toBe("1111");
+    }
+  });
+
+  it("encodes the decline scenario in the mock token", async () => {
+    const result = await tokenizeForCheckout(DECLINE_CARD, {
+      provider: "pagbank",
+      publicKey: null,
+      mockTokenization: true,
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data.token).toMatch(/^tok_declined/);
+  });
+
+  it("still validates the card before minting a mock", async () => {
+    const result = await tokenizeForCheckout(
+      { ...VALID_CARD, number: "1234" },
+      { provider: "pagbank", publicKey: null, mockTokenization: true },
+    );
+    expect(result.ok).toBe(false);
+  });
+
+  it("routes a keyed PagBank store to the REAL tokenizer — a key beats stub permission", async () => {
+    // Stub the SDK so `ensurePagBankSdk` short-circuits (no script injection in
+    // the test env). The encrypted blob coming back — never a `tok_…` mock —
+    // is the proof that a present key routes to REAL tokenization even when
+    // stub permission was granted.
+    const pagSeguro = {
+      encryptCard: () => ({ hasErrors: false, encryptedCard: "enc-blob-123" }),
+    };
+    (window as typeof window & { PagSeguro?: typeof pagSeguro }).PagSeguro = pagSeguro;
+    try {
+      const result = await tokenizeForCheckout(VALID_CARD, {
+        provider: "pagbank",
+        publicKey: "PUB-KEY",
+        mockTokenization: true, // even with stub permission, a key means REAL tokenization
+      });
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.data.token).toBe("enc-blob-123");
+        expect(result.data.token).not.toMatch(/^tok/);
+      }
+    } finally {
+      delete (window as typeof window & { PagSeguro?: typeof pagSeguro }).PagSeguro;
+    }
+  });
+});
+
+describe("tokenizerFor — scheme is chosen by provider, never by capability", () => {
+  it("names each implemented provider's own scheme", () => {
+    expect(tokenizerFor("pagbank")).toBe("pagbank-sdk");
+    expect(tokenizerFor("stone")).toBe("pagarme-token");
+    expect(tokenizerFor("stripe")).toBe("stripe-pm");
+  });
+
+  it("answers null for providers with no browser card path", () => {
+    expect(tokenizerFor("infinitepay")).toBeNull();
+    expect(tokenizerFor("unknown-vendor")).toBeNull();
+  });
+});
+
+describe("tokenizeForCheckout — the stripe-pm scheme (FUT-698)", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  /** Stub fetch once and capture the single call the tokenizer makes. */
+  function stubStripe(status: number, body: unknown): { url?: string; init?: RequestInit }[] {
+    const calls: { url?: string; init?: RequestInit }[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: RequestInfo | URL, init?: RequestInit) => {
+        calls.push({ url: String(url), init });
+        return new Response(JSON.stringify(body), { status });
+      }),
+    );
+    return calls;
+  }
+
+  it("mints a PaymentMethod at Stripe with the publishable key — the PAN never reaches us", async () => {
+    const calls = stubStripe(200, { id: "pm_123", card: { brand: "visa", last4: "1111" } });
+
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: "stripe",
+      publicKey: "pk_test_1",
+      mockTokenization: false,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data.token).toBe("pm_123");
+      expect(result.data.last4).toBe("1111");
+    }
+    expect(calls[0]?.url).toBe("https://api.stripe.com/v1/payment_methods");
+    const headers = calls[0]?.init?.headers as Record<string, string>;
+    expect(headers["Authorization"]).toBe("Bearer pk_test_1");
+    const form = new URLSearchParams(String(calls[0]?.init?.body));
+    expect(form.get("type")).toBe("card");
+    expect(form.get("card[number]")).toBe("4111111111111111");
+    expect(form.get("card[exp_month]")).toBe("12");
+    expect(form.get("card[exp_year]")).toBe("2039");
+  });
+
+  it("carries Stripe's refusal verbatim — the provider's answer must reach a human", async () => {
+    stubStripe(402, { error: { message: "Your card number is incorrect." } });
+
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: "stripe",
+      publicKey: "pk_test_1",
+      mockTokenization: false,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("HTTP 402");
+      expect(result.error).toContain("Your card number is incorrect.");
+    }
+  });
+
+  it("a keyed Stripe store routes to the REAL tokenizer — a key beats stub permission", async () => {
+    stubStripe(200, { id: "pm_real" });
+
+    const result = await tokenizeForCheckout(VALID_CARD, {
+      provider: "stripe",
+      publicKey: "pk_test_1",
+      mockTokenization: true, // even with stub permission, a key means REAL tokenization
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data.token).toBe("pm_real");
+  });
+});

package/src/card/tokenize.ts

@@ -0,0 +1,327 @@
+/**
+ * Browser-side card tokenization — the PCI boundary.
+ *
+ * The PAN is validated locally, then encrypted **in the browser** by the
+ * PagBank SDK with the store's public key, so the raw {@link CardDetails} never
+ * leaves the page; only the encrypted blob is sent to the server. The SDK
+ * script is injected lazily the first time a real key is used.
+ *
+ * Two doors, and the naming is the safety mechanism:
+ *
+ *   - {@link tokenizeCard} REQUIRES a real public key and fails without one.
+ *   - {@link tokenizeForCheckout} may fall back to a fake token, but ONLY when
+ *     the server granted stub mode (`mockTokenization`, FUT-697) — a dev/e2e
+ *     affordance, and one that must never be reached by anything deciding
+ *     whether a store is allowed to take money.
+ *
+ * That distinction is the whole reason this moved out of the storefront: the
+ * provider-activation check (FUT-463) proves a store can charge by charging it.
+ * Handed the mock, a store with no public key would "pass" without a single
+ * request reaching PagBank and be switched live — the exact false positive the
+ * check exists to catch.
+ */
+
+import { err, ok, type Result } from "../result";
+
+import { detectBrand, onlyDigits } from "./format";
+import { tokenizeWithStripe } from "./stripe-token";
+import type { CardDetails, CardToken } from "./types";
+
+/** Test PAN that always declines (mirrors common sandbox decline cards). */
+const DECLINE_PAN = "4000000000000002";
+
+/** PagBank browser SDK — encrypts the card with the public key, client-side. */
+const PAGBANK_SDK_URL =
+  "https://assets.pagseguro.com.br/checkout-sdk-js/rc/dist/browser/pagseguro.min.js";
+
+/**
+ * PagBank browser SDK surface. It encrypts the card with the RSA public key
+ * entirely client-side, so the PAN never leaves the browser — only the
+ * resulting blob is sent to our server.
+ */
+interface PagBankEncryptResult {
+  encryptedCard?: string;
+  hasErrors: boolean;
+  errors?: unknown[];
+}
+declare global {
+  interface Window {
+    PagSeguro?: {
+      encryptCard(params: {
+        publicKey: string;
+        holder: string;
+        number: string;
+        expMonth: string;
+        expYear: string;
+        securityCode: string;
+      }): PagBankEncryptResult;
+    };
+  }
+}
+
+/**
+ * Inject the PagBank SDK script once and resolve when it is usable. Resolves
+ * `false` (never rejects) when the script fails or times out — the caller
+ * surfaces a friendly retry message.
+ */
+let sdkLoad: Promise<boolean> | null = null;
+function ensurePagBankSdk(): Promise<boolean> {
+  if (typeof window === "undefined") return Promise.resolve(false);
+  if (window.PagSeguro?.encryptCard) return Promise.resolve(true);
+  sdkLoad ??= new Promise<boolean>((resolve) => {
+    const script = document.createElement("script");
+    script.src = PAGBANK_SDK_URL;
+    script.async = true;
+    script.onload = () => resolve(Boolean(window.PagSeguro?.encryptCard));
+    script.onerror = () => resolve(false);
+    document.head.appendChild(script);
+  });
+  return sdkLoad;
+}
+
+/** Local card-field validation. Returns an error message, or `null` when valid. */
+function validateCardInput(card: CardDetails): string | null {
+  if (!passesLuhn(onlyDigits(card.number))) return "Número de cartão inválido.";
+  if (card.holder.trim().length < 2) return "Informe o nome impresso no cartão.";
+  if (!expiryIsFuture(card.expiry)) return "Validade inválida ou expirada.";
+  if (!/^\d{3,4}$/.test(card.cvv.trim())) return "CVV inválido.";
+  return null;
+}
+
+/**
+ * Encrypt the (already-validated) card with the PagBank browser SDK, so the raw
+ * PAN never leaves the page — only the resulting token is returned.
+ */
+function encryptWithSdk(
+  card: CardDetails,
+  pan: string,
+  publicKey: string,
+  brand: string,
+  last4: string,
+): Result<CardToken> {
+  if (typeof window === "undefined" || !window.PagSeguro?.encryptCard) {
+    return err("Não foi possível carregar o meio de pagamento. Recarregue a página.");
+  }
+  const match = /^(\d{2})\/(\d{2})$/.exec(card.expiry.trim());
+  if (!match) return err("Validade inválida ou expirada.");
+  const encrypted = window.PagSeguro.encryptCard({
+    publicKey,
+    holder: card.holder.trim(),
+    number: pan,
+    expMonth: match[1]!,
+    expYear: `20${match[2]!}`,
+    securityCode: card.cvv.trim(),
+  });
+  if (encrypted.hasErrors || !encrypted.encryptedCard) {
+    return err("Não foi possível processar o cartão. Verifique os dados e tente novamente.");
+  }
+  return ok({ token: encrypted.encryptedCard, brand, last4 });
+}
+
+/**
+ * Which browser-side scheme mints the token.
+ *
+ * `tokenization: 'PUBLIC_KEY'` does NOT disambiguate this — PagBank and Stone
+ * both report it while speaking entirely different protocols: PagBank encrypts
+ * locally with an injected SDK, Pagar.me (Stone's payments technology) posts
+ * the card to its own tokens endpoint and hands back an id, and Stripe mints a
+ * PaymentMethod at its own endpoint with the publishable key (FUT-698). Keyed
+ * by provider because the protocol is the provider's, not the capability's.
+ */
+export type CardTokenizer = "pagbank-sdk" | "pagarme-token" | "stripe-pm";
+
+export function tokenizerFor(provider: string): CardTokenizer | null {
+  if (provider === "pagbank") return "pagbank-sdk";
+  if (provider === "stone") return "pagarme-token";
+  if (provider === "stripe") return "stripe-pm";
+  // InfinitePay (REDIRECT) has no in-browser card path — its own page takes
+  // the card. Null so the caller can SAY so, rather than mint a token with the
+  // wrong scheme and report the provider's rejection as if the card were bad.
+  return null;
+}
+
+/** Pagar.me v5 tokens endpoint — the public key rides as `appId`. */
+const PAGARME_TOKENS_URL = "https://api.pagar.me/core/v5/tokens";
+
+/**
+ * Mint a Pagar.me card token, for Stone.
+ *
+ * The PAN is posted straight to Pagar.me from the browser and never touches our
+ * server — the same PCI boundary the PagBank SDK gives us by encrypting
+ * locally, reached a different way. Only the returned id comes back to us, and
+ * that id is what `stone-orders.ts` sends as `card_token`.
+ */
+async function tokenizeWithPagarme(
+  card: CardDetails,
+  pan: string,
+  publicKey: string,
+  brand: string,
+  last4: string,
+): Promise<Result<CardToken>> {
+  const match = /^(\d{2})\/(\d{2})$/.exec(card.expiry.trim());
+  if (!match) return err("Validade inválida ou expirada.");
+
+  let response: Response;
+  try {
+    response = await fetch(`${PAGARME_TOKENS_URL}?appId=${encodeURIComponent(publicKey)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "card",
+        card: {
+          number: pan,
+          holder_name: card.holder.trim(),
+          exp_month: Number(match[1]),
+          exp_year: Number(`20${match[2]}`),
+          cvv: card.cvv.trim(),
+        },
+      }),
+    });
+  } catch {
+    return err("Não foi possível contatar o provedor do cartão. Verifique sua conexão.");
+  }
+
+  const body = (await response.json().catch(() => null)) as { id?: unknown } | null;
+  if (!response.ok || typeof body?.id !== "string") {
+    // Carried verbatim: a rejected tokenization is the provider's answer, and
+    // the whole point of the activation screen is that it reaches a human.
+    return err(
+      `O provedor recusou os dados do cartão (HTTP ${response.status}). ` +
+        `Resposta: ${JSON.stringify(body).slice(0, 300)}`,
+    );
+  }
+  return ok({ token: body.id, brand, last4 });
+}
+
+/**
+ * Tokenize a card with the store's PagBank public key.
+ *
+ * A missing key is an ERROR here, never a fallback: without one there is no
+ * encryption, so there is nothing a provider could accept or refuse.
+ */
+export async function tokenizeCard(
+  card: CardDetails,
+  publicKey: string | null | undefined,
+  tokenizer: CardTokenizer = "pagbank-sdk",
+): Promise<Result<CardToken>> {
+  const validationError = validateCardInput(card);
+  if (validationError) return err(validationError);
+
+  if (!publicKey) {
+    return err(
+      "A chave pública do cartão não está disponível para esta loja. " +
+        "Reconecte o provedor e tente novamente.",
+    );
+  }
+
+  const pan = onlyDigits(card.number);
+  const brand = detectBrand(pan);
+  const last4 = pan.slice(-4);
+
+  if (tokenizer === "pagarme-token") {
+    return tokenizeWithPagarme(card, pan, publicKey, brand, last4);
+  }
+  if (tokenizer === "stripe-pm") {
+    return tokenizeWithStripe(card, pan, publicKey, brand, last4);
+  }
+
+  if (!(await ensurePagBankSdk())) {
+    return err("Não foi possível carregar o meio de pagamento. Recarregue a página.");
+  }
+  return encryptWithSdk(card, pan, publicKey, brand, last4);
+}
+
+/**
+ * What the buyer checkout knows about the store's active provider — the
+ * buyer-safe triple `GET /api/checkout/config` answers (FUT-697), which is the
+ * ONLY sanctioned source for `mockTokenization`.
+ */
+export interface CardTokenizationConfig {
+  /** Active provider's name, or `null` when the store has none connected. */
+  provider: string | null;
+  /** The provider's PUBLIC browser key, when it has one. */
+  publicKey: string | null;
+  /**
+   * Server-granted stub-mode permission. `true` only when the store's
+   * connection runs the deterministic stub (local dev / e2e / demo tenants).
+   * A mock token may be minted under NO other condition — minting one against
+   * a real provider was the FUT-697 bug: a fake `tok_…` entered a real charge
+   * and the provider's rejection read as though the buyer's card were bad.
+   */
+  mockTokenization: boolean;
+}
+
+/** The clear bail (FUT-697): said BEFORE any charge, naming the remedy. */
+const CARD_PATH_UNAVAILABLE =
+  "O pagamento com cartão está indisponível nesta loja no momento. Recarregue a página e tente de novo, escolha outro método de pagamento ou combine diretamente com a loja.";
+
+/**
+ * Tokenize for the buyer checkout, speaking the ACTIVE provider's protocol.
+ *
+ * - Provider with a browser scheme and a key ⇒ real tokenization, with the
+ *   scheme {@link tokenizerFor} names (PagBank encrypts via SDK, Stone posts
+ *   to Pagar.me, Stripe mints a PaymentMethod with the publishable key —
+ *   PagBank and Stone advertise the same `PUBLIC_KEY` while speaking different
+ *   protocols, so the choice is by provider, never by capability).
+ * - Stub-mode store ⇒ a mock token that encodes the decline scenario, so the
+ *   full order→charge→confirm path runs with no credentials (dev / e2e).
+ * - Anything else ⇒ a clear bail. Never a fake token into a real charge.
+ *
+ * Only the buyer checkout may use this. Anything that GRANTS something on a
+ * successful charge must call {@link tokenizeCard} instead — a mock token
+ * cannot prove a real account works.
+ */
+export async function tokenizeForCheckout(
+  card: CardDetails,
+  config: CardTokenizationConfig,
+): Promise<Result<CardToken>> {
+  const scheme = config.provider ? tokenizerFor(config.provider) : null;
+  if (scheme && config.publicKey) return tokenizeCard(card, config.publicKey, scheme);
+
+  if (!config.mockTokenization) return err(CARD_PATH_UNAVAILABLE);
+
+  const validationError = validateCardInput(card);
+  if (validationError) return err(validationError);
+
+  const pan = onlyDigits(card.number);
+  const token = pan === DECLINE_PAN ? mintToken("tok_declined") : mintToken("tok");
+  return ok({ token, brand: detectBrand(pan), last4: pan.slice(-4) });
+}
+
+// ---------------------------------------------------------------------------
+// Local card helpers (used only by tokenization — the PAN stays in this file)
+// ---------------------------------------------------------------------------
+
+/** Luhn checksum — rejects obviously invalid card numbers before tokenizing. */
+function passesLuhn(pan: string): boolean {
+  let sum = 0;
+  let double = false;
+  for (let i = pan.length - 1; i >= 0; i -= 1) {
+    let digit = Number(pan[i]);
+    if (double) {
+      digit *= 2;
+      if (digit > 9) digit -= 9;
+    }
+    sum += digit;
+    double = !double;
+  }
+  return pan.length >= 13 && sum % 10 === 0;
+}
+
+function expiryIsFuture(expiry: string): boolean {
+  const match = /^(\d{2})\/(\d{2})$/.exec(expiry.trim());
+  if (!match) return false;
+  const month = Number(match[1]);
+  const year = 2000 + Number(match[2]);
+  if (month < 1 || month > 12) return false;
+  const now = new Date();
+  const endOfMonth = new Date(year, month, 0, 23, 59, 59);
+  return endOfMonth.getTime() >= now.getTime();
+}
+
+let tokenCounter = 0;
+/** Opaque client-side token id (stands in for the SDK's encrypted card token). */
+function mintToken(prefix: string): string {
+  tokenCounter += 1;
+  return `${prefix}_${Date.now().toString(36)}${tokenCounter.toString(36)}`;
+}

package/src/card/types.ts

@@ -0,0 +1,54 @@
+/**
+ * The card-entry vocabulary, shared by every surface that takes a card.
+ *
+ * These lived in the storefront checkout until the admin needed the SAME form:
+ * activating a payment provider is now earned by a real R$0,01 charge on the
+ * owner's own card (FUT-463), and that has to exercise the shopper's exact
+ * path — same fields, same validation, same tokenization — or it proves
+ * nothing about what a shopper will hit.
+ */
+
+/**
+ * Raw card details entered in the form. These NEVER leave the browser — they
+ * are handed to `tokenizeCard` (the PagBank JS SDK in production) and only the
+ * resulting {@link CardToken} is sent to the server, so the PAN stays out of
+ * PCI scope.
+ */
+export interface CardDetails {
+  number: string;
+  holder: string;
+  /** `MM/YY`. */
+  expiry: string;
+  cvv: string;
+}
+
+/** A client-side card token — the only card data that reaches the server. */
+export interface CardToken {
+  token: string;
+  brand: string;
+  last4: string;
+}
+
+/**
+ * A previously-saved card available for reuse. Only display metadata is kept
+ * client-side — the reusable token lives server-side keyed by {@link id}.
+ */
+export interface SavedCard {
+  id: string;
+  brand: string;
+  last4: string;
+  expMonth: number;
+  expYear: number;
+  holder: string;
+}
+
+/** Per-field validation messages; `undefined` means the field is fine. */
+export interface CardFieldErrors {
+  number?: string;
+  holder?: string;
+  expiry?: string;
+  cvv?: string;
+}
+
+/** Sentinel selection value meaning "enter a new card". */
+export const NEW_CARD = "new";

package/src/components/PaymentProviderSettings.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { Alert, Box, Button, CircularProgress } from '@mui/material';
-import type { ReactNode } from 'react';
+import { useCallback, type ReactNode } from 'react';
 
 import type { MaskedProviderConfig } from '@12-apps/payments-backend';
 
@@ -12,11 +12,13 @@ import { ActivePanel, type ActivePanelProps, type PrepareConnect } from './Provi
 import {
   guideAwaitsConfirmation,
   progressKeyOf,
+  useCanonicalProviderSegment,
   useOpenProvider,
   useSelectedProvider,
   useSettingsState,
   useSetupConfirmation,
   useSetupGuide,
+  type ProviderChangeHandler,
 } from './settings-state';
 import { openSection, SetupGuideSection } from './SetupGuideSection';
 
@@ -66,6 +68,12 @@ export interface PaymentProviderSettingsProps {
    * because the host's value is now the single source of truth. Leave it
    * `undefined` and nothing changes: selection stays internal, as every
    * existing caller expects.
+   *
+   * The value may be the provider's NAME or its `urlSlug` — a host that keeps
+   * the selection in a path segment passes the segment verbatim, and the raw
+   * name stays a working alias so old links do not 404. Which spelling each
+   * provider uses is the adapter's own declaration, carried in the catalog;
+   * the host holds no map.
    */
   selectedProvider?: string | null;
   /**
@@ -74,8 +82,15 @@ export interface PaymentProviderSettingsProps {
    * Independent of `selectedProvider`: an uncontrolled host can use this purely
    * to observe, while a controlled host uses it to write the new selection
    * wherever it keeps it.
+   *
+   * Reports the provider's `urlSlug` — its name, unless the adapter re-spells
+   * it — so a controlled host writes the value straight into its URL. It is
+   * also how a segment gets CORRECTED: handed an alias (the OAuth callback's
+   * `?connected=` carries the raw name), this fires once with the canonical
+   * slug and `{ replace: true }`, asking the host to rewrite — not extend —
+   * its history ({@link ProviderChangeHandler}).
    */
-  onProviderChange?: (provider: string | null) => void;
+  onProviderChange?: ProviderChangeHandler;
   /**
    * The activation step, rendered under the connection card.
    *
@@ -216,8 +231,19 @@ export function PaymentProviderSettings({
     selectedProvider,
     onProviderChange,
   );
+  // What leaves this component (and what it stores) is the adapter's URL
+  // spelling, so a controlled host writes it into its path segment verbatim —
+  // `useOpenProvider` resolves names and slugs alike, so either survives.
+  const openProvider = useCallback(
+    (name: string | null) =>
+      setSelected(name ? (view?.providers.find((p) => p.name === name)?.urlSlug ?? name) : null),
+    [view, setSelected],
+  );
   // Resolved above the early returns, because the guide hook depends on both.
   const { active, activeConfig } = useOpenProvider(view, selected);
+  // A controlled segment that resolved through the alias gets respelled to the
+  // adapter's canonical slug — the address bar is part of the contract.
+  useCanonicalProviderSegment(selectedProvider, active, onProviderChange);
   const { guide, loaded } = useSetupGuide(client, active?.name ?? null, progressKeyOf(activeConfig));
   const ack = useSetupConfirmation(client, active, activeConfig);
 
@@ -225,7 +251,7 @@ export function PaymentProviderSettings({
   if (!view) return <CircularProgress data-testid="payments-settings-loading" />;
 
   if (!active) {
-    return <ProviderList view={view} client={client} reload={reload} onSelect={setSelected} />;
+    return <ProviderList view={view} client={client} reload={reload} onSelect={openProvider} />;
   }
 
   return (
@@ -236,7 +262,7 @@ export function PaymentProviderSettings({
       onChanged={onChanged}
       reload={() => void reload()}
       prepareConnect={prepareConnect}
-      onBack={() => setSelected(null)}
+      onBack={() => openProvider(null)}
       // A new credential may name a DIFFERENT InfinitePay account, and the
       // owner's "Checkout Integrado is on" was said about the old one. The
       // server already drops its own verdict and its proof on any credential