@12-apps/payments-frontend 3.5.0 → 3.6.0

package/package.json

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

package/src/components/checkout/checkout-steps.tsx

@@ -3,12 +3,7 @@ import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import { BuyerInfoForm } from "./buyer-info-form";
 import { LockOutlinedIcon } from "./icons";
-import {
-  cardPathAvailable,
-  offeredMethods,
-  selectableMethods,
-  usePreselectSoleMethod,
-} from "./method-capability";
+import { useMethodChoice } from "./method-choice";
 import { MethodPicker } from "./method-picker";
 import { PaymentErrorPanel } from "./payment-error-panel";
 import { PayerSummary } from "./payer-summary";
@@ -42,8 +37,8 @@ function useAutoRaiseOrder(
       requestedFor.current = null;
       return;
     }
-    // No method chosen yet ⇒ show only the picker; raise the order once the
-    // buyer selects PIX or card.
+    // No method chosen yet ⇒ show only the picker (or, for a hand-off store,
+    // its "Seguir para o pagamento"); raise the order once the buyer commits.
     if (!method || creating || createError || requestedFor.current === method) return;
     requestedFor.current = method;
     onGenerate(method);
@@ -70,6 +65,8 @@ function PaymentBody({
   method,
   tenantSlug,
   onResolved,
+  onStart,
+  creating,
   pollIntervalMs,
   validateApplePayMerchant,
 }: {
@@ -79,6 +76,9 @@ function PaymentBody({
   method: PaymentMethod | null;
   tenantSlug?: string;
   onResolved: (status: OrderStatus) => void;
+  /** Set only when the shell hid its picker — see {@link PaymentStep}. */
+  onStart?: () => void;
+  creating: boolean;
   pollIntervalMs?: number;
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
 }): JSX.Element | null {
@@ -91,6 +91,8 @@ function PaymentBody({
       method={method}
       tenantSlug={tenantSlug}
       onResolved={onResolved}
+      onStart={onStart}
+      creating={creating}
       pollIntervalMs={pollIntervalMs}
       validateApplePayMerchant={validateApplePayMerchant}
     />
@@ -303,6 +305,17 @@ interface PaymentStepProps {
  * Step 2 "Pagamento" — pick PIX or card and pay on the SAME page. Selecting a
  * method auto-raises its order and reveals its UI (PIX QR / card form) with no
  * intermediate tap; switching method clears the previous order (controller).
+ *
+ * ## Unless the choice is not ours to ask
+ *
+ * A store that finishes checkout on the provider's own page gets NO picker
+ * here (`methodChosenAtProvider`). Its screen renders a single "Seguir para o
+ * pagamento" instead, and pressing it selects the store's hand-off method —
+ * which is the same event a tile press is, so the auto-raise, the error panel
+ * and the retry below all keep working unchanged. Preselection is suppressed
+ * for the same flow, and deliberately: it exists to spare a buyer a tap that
+ * buys them nothing, but here the tap is the buyer's consent to LEAVE, and
+ * taking it for them would redirect a checkout the moment it rendered.
  */
 export function PaymentStep({
   method,
@@ -323,35 +336,42 @@ export function PaymentStep({
   onResolved,
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
-  const cardUnavailable = !cardPathAvailable(providerConfig ?? null);
-  const offered = offeredMethods(providerConfig ?? null);
+  const config = providerConfig ?? null;
+  const choice = useMethodChoice(config, method, onMethodChange);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
-  usePreselectSoleMethod(selectableMethods(offered, cardUnavailable), method, onMethodChange);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
       {/* Self-hiding: renders only for a flow whose Dados step was skipped. */}
       <PayerSummary name={buyer.name} taxId={buyer.taxId} onEdit={onEditBuyer} />
 
-      <MethodPicker
-        value={method}
-        onChange={onMethodChange}
-        cardUnavailable={cardUnavailable}
-        offered={offered}
-      />
+      {choice.atProvider ? null : (
+        <MethodPicker
+          value={method}
+          onChange={onMethodChange}
+          cardUnavailable={choice.cardUnavailable}
+          offered={choice.offered}
+        />
+      )}
 
       <PaymentBody
         order={order}
         buyer={buyer}
-        providerConfig={providerConfig ?? null}
+        providerConfig={config}
         method={method}
         tenantSlug={tenantSlug}
         onResolved={onResolved}
+        onStart={choice.onStart}
+        creating={creating}
         pollIntervalMs={pollIntervalMs}
         validateApplePayMerchant={validateApplePayMerchant}
       />
 
-      {!order && creating ? (
+      {/* The shell's own busy spinner, SUPPRESSED for a hand-off screen: that
+          screen renders its own "Preparando o pagamento" while the charge is
+          raised, and two stacked spinners saying the same thing is what the
+          buyer actually saw. */}
+      {!order && creating && !choice.atProvider ? (
         <LoadingState variant="spinner" size="md" message="Gerando pagamento…" dataTestId="payment-generating" />
       ) : null}
 

package/src/components/checkout/method-capability.ts

@@ -216,6 +216,33 @@ export function selectableMethods(
   );
 }
 
+/**
+ * The method a HAND-OFF checkout raises on the buyer's behalf, when the buyer
+ * was never asked (see `providers/registry.ts`'s `methodChosenAtProvider`).
+ *
+ * A charge still has to be raised with SOME method — that is the wire's shape,
+ * and the link is minted by raising it — but for a hand-off store the value is
+ * provisional by construction: the buyer picks for real on the provider's page,
+ * and the settlement reports back which one they actually used. So the choice
+ * here is about which request the SERVER will honour, not about what the buyer
+ * gets.
+ *
+ * PIX when the chain offers it, because PIX is the one method whose first
+ * charge is always raised immediately: a CARD request at a store that can
+ * tokenize somewhere in its chain is answered with the bare order instead, and
+ * there is no hand-off link on that answer to send anyone anywhere. Otherwise
+ * the chain's first declared method, since a store that cannot PIX would have
+ * the walk refuse a PIX charge outright.
+ *
+ * `null` offered — still loading, or a fetch blip — cannot reach here: the
+ * picker is only hidden for a store whose config already said it hands over.
+ * PIX is the safe reading of it anyway, for the reason above.
+ */
+export function handOffMethod(offered: PaymentMethod[] | null): PaymentMethod {
+  if (!offered || offered.includes("PIX")) return "PIX";
+  return offered[0] ?? "PIX";
+}
+
 /**
  * A SOLE remaining method is not a choice — take it (FUT-697 review, widened by
  * FUT-741).

package/src/components/checkout/method-choice.ts

@@ -0,0 +1,64 @@
+/**
+ * WHO asks the buyer PIX-or-card, and what the Pagamento step does about it.
+ *
+ * Its own module because the answer is a set of derived facts that must move
+ * together: a picker rendered for a store that hands the buyer over, or a
+ * hand-off CTA rendered beside a picker, are both a checkout asking one
+ * question twice — which is the defect this seam exists to make impossible.
+ */
+import {
+  cardPathAvailable,
+  handOffMethod,
+  offeredMethods,
+  selectableMethods,
+  usePreselectSoleMethod,
+} from "./method-capability";
+import { methodChosenAtProvider } from "./providers/registry";
+import type { CheckoutProviderConfig, PaymentMethod } from "./types";
+
+/** What the Pagamento step needs to know about WHO asks the buyer for a method. */
+interface MethodChoice {
+  /** The store's active provider has no card path in this browser. */
+  cardUnavailable: boolean;
+  /** The methods the chain declares it can charge, or `null` while unknown. */
+  offered: PaymentMethod[] | null;
+  /** The choice is made on the provider's page ⇒ render no picker here. */
+  atProvider: boolean;
+  /**
+   * The hand-off screen's "start paying" port, or `undefined` when the picker
+   * is on the page and owns that job instead. It SELECTS the store's hand-off
+   * method, which is the same event a tile press is — so the auto-raise, the
+   * error panel and its retry all keep working with no second code path.
+   */
+  onStart?: () => void;
+}
+
+/**
+ * Resolve who asks the buyer PIX-or-card, and preselect a sole method when the
+ * question is ours to ask.
+ */
+export function useMethodChoice(
+  config: CheckoutProviderConfig | null,
+  method: PaymentMethod | null,
+  onMethodChange: (method: PaymentMethod) => void,
+): MethodChoice {
+  const cardUnavailable = !cardPathAvailable(config);
+  const offered = offeredMethods(config);
+  const atProvider = methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config);
+  // Nothing to preselect when the screen owns the choice: the whole point of
+  // its button is that the buyer presses it. Preselection exists to spare them
+  // a tap that buys them nothing, and here the tap is their consent to LEAVE —
+  // taking it for them would redirect a checkout the moment it rendered.
+  usePreselectSoleMethod(
+    atProvider ? [] : selectableMethods(offered, cardUnavailable),
+    method,
+    onMethodChange,
+  );
+  if (!atProvider) return { cardUnavailable, offered, atProvider };
+  return {
+    cardUnavailable,
+    offered,
+    atProvider,
+    onStart: () => onMethodChange(handOffMethod(offered)),
+  };
+}

package/src/components/checkout/providers/capability-default.tsx

@@ -19,45 +19,11 @@
  */
 import type { JSX } from "react";
 
-import type { CheckoutProviderConfig } from "../types";
-
+import { handsBuyerOver } from "./hands-over";
 import { HostedLinkScreen } from "./hosted-link";
 import { PixAndCardScreen } from "./pix-and-card";
 import type { ProviderCheckoutScreenProps } from "./types";
 
-/** Schemes that give the BROWSER a card form of its own. */
-const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
-
-/**
- * Whether this store hands the buyer over instead of collecting here — the
- * frontend twin of the server's `usesHostedCheckout`, deliberately written to
- * the same three rules so the pane and the walk cannot disagree.
- *
- * Note this is NOT `!cardPathAvailable(config)`. That helper answers a
- * different question — "is a card offerable at all" — and it answers TRUE for
- * a hand-off store, because typing the card on the provider's page is still a
- * card path. Inverting it therefore sends the hosted store to the on-page
- * screen and the on-page store to the hand-off, which is exactly backwards.
- *
- * The rules, in order:
- *   - Only CARD can be answered in advance. TOKENIZATION IS A CARD FACT: it
- *     says how the browser turns a PAN into an instrument, and a PIX charge
- *     has no instrument to mint. A store with no card-capable entry is not
- *     hosted — this is the FUT-747 correction, and getting it wrong routed the
- *     simplest store there is (one PIX-only provider honestly declaring
- *     `NONE`) into a hand-off it had no link for.
- *   - Hosted only when NOBODY who takes a card takes it here.
- *   - No chain served (an older host, a still-loading config) ⇒ not hosted,
- *     which is what this checkout did before there was a chain to read.
- */
-function handsBuyerOver(config: CheckoutProviderConfig | null): boolean {
-  const chain = config?.chain;
-  if (!chain || chain.length === 0) return false;
-  const cardCapable = chain.filter((link) => link.methods.includes("CARD"));
-  if (cardCapable.length === 0) return false;
-  return !cardCapable.some((link) => IN_BROWSER_TOKENIZATION.has(link.tokenization));
-}
-
 export function CapabilityDefaultScreen(props: ProviderCheckoutScreenProps): JSX.Element | null {
   return handsBuyerOver(props.config) ? (
     <HostedLinkScreen {...props} />

package/src/components/checkout/providers/hands-over.ts

@@ -0,0 +1,43 @@
+/**
+ * Whether a store finishes checkout on the PROVIDER's own page.
+ *
+ * Its own module because two callers need the same answer and must never be
+ * able to disagree about it: {@link CapabilityDefaultScreen}, which picks the
+ * pane for a provider that declared no screen, and the shell's picker gate,
+ * which decides whether the buyer is asked PIX-or-card here at all. It lived
+ * inside `capability-default.tsx` while there was one caller.
+ */
+import type { CheckoutProviderConfig } from "../types";
+
+/** Schemes that give the BROWSER a card form of its own. */
+const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
+
+/**
+ * Whether this store hands the buyer over instead of collecting here — the
+ * frontend twin of the server's `usesHostedCheckout`, deliberately written to
+ * the same three rules so the pane and the walk cannot disagree.
+ *
+ * Note this is NOT `!cardPathAvailable(config)`. That helper answers a
+ * different question — "is a card offerable at all" — and it answers TRUE for
+ * a hand-off store, because typing the card on the provider's page is still a
+ * card path. Inverting it therefore sends the hosted store to the on-page
+ * screen and the on-page store to the hand-off, which is exactly backwards.
+ *
+ * The rules, in order:
+ *   - Only CARD can be answered in advance. TOKENIZATION IS A CARD FACT: it
+ *     says how the browser turns a PAN into an instrument, and a PIX charge
+ *     has no instrument to mint. A store with no card-capable entry is not
+ *     hosted — this is the FUT-747 correction, and getting it wrong routed the
+ *     simplest store there is (one PIX-only provider honestly declaring
+ *     `NONE`) into a hand-off it had no link for.
+ *   - Hosted only when NOBODY who takes a card takes it here.
+ *   - No chain served (an older host, a still-loading config) ⇒ not hosted,
+ *     which is what this checkout did before there was a chain to read.
+ */
+export function handsBuyerOver(config: CheckoutProviderConfig | null): boolean {
+  const chain = config?.chain;
+  if (!chain || chain.length === 0) return false;
+  const cardCapable = chain.filter((link) => link.methods.includes("CARD"));
+  if (cardCapable.length === 0) return false;
+  return !cardCapable.some((link) => IN_BROWSER_TOKENIZATION.has(link.tokenization));
+}

package/src/components/checkout/providers/hosted-link.tsx

@@ -15,26 +15,112 @@
  * is leaving this page and parking the payable for the return leg matters more
  * than painting a pane they will not see. `hosted-return.ts` picks it back up.
  *
- * So the whole job here is the moment BEFORE that: the buyer has chosen a
- * method and the redirect is being prepared. Previously the pane rendered
- * `null` through that moment, which reads as a checkout that has stalled — the
- * screen tells them where they are going instead. Nothing here touches the
- * money path; the navigation and the parking are unchanged.
+ * So the whole job here is the moment BEFORE that: telling the buyer where
+ * they are about to go, and giving them the one action that takes them.
+ *
+ * ## Why the ACTION lives here and not in the shell's picker
+ *
+ * The shell hides its PIX/card picker for this screen (`methodChosenAtProvider`
+ * in `./registry.ts`), so the screen owns the affordance that starts the
+ * charge. That is the point of the whole arrangement: the method question is
+ * binding on the provider's page, not on ours — every answer mints the same
+ * link — so asking it twice tells the buyer their first answer was thrown
+ * away. One button that says where it leads is the honest version of that
+ * screen, and it also removes the moment where the pane rendered `null` under
+ * a picker, which reads as a checkout that has stalled.
  */
 import { Box } from "@mui/material";
 import type { JSX } from "react";
 
+import { offeredMethods } from "../method-capability";
+import type { CheckoutProviderConfig } from "../types";
 import { useCheckoutComponents } from "../ui";
 
 import type { ProviderCheckoutScreenProps } from "./types";
 
-export function HostedLinkScreen({ method }: ProviderCheckoutScreenProps): JSX.Element | null {
-  const { Text, LoadingState } = useCheckoutComponents();
+/**
+ * How the store's own page is named to the buyer — "à página segura da
+ * InfinitePay", or the provider-neutral phrasing when no name was published.
+ *
+ * The neutral form is not a lesser fallback to be tidied away later: a host one
+ * release behind serves no `displayName`, and the buyer of that store gets a
+ * true sentence rather than our internal id ("infinitepay") dressed up as a
+ * brand.
+ */
+function destinationLabel(config: CheckoutProviderConfig | null): string {
+  const name = config?.chain?.[0]?.displayName?.trim();
+  return name ? `à página de pagamento da ${name}` : "à página de pagamento segura do provedor";
+}
 
-  // Nothing chosen yet ⇒ the shell is still showing the picker. Same as every
-  // other screen: the pane stays out of the way until there is something to say.
-  if (!method) return null;
+/**
+ * What the buyer will be asked to choose between once they get there, so the
+ * sentence promises exactly what the provider's page offers.
+ *
+ * Read from the same declaration the picker used to render, which is what
+ * keeps this honest for a provider that takes only one of the two: a hosted
+ * PIX-only store must not promise a card.
+ */
+function methodsPhrase(config: CheckoutProviderConfig | null): string | null {
+  const offered = offeredMethods(config);
+  const pix = offered === null || offered.includes("PIX");
+  const card = offered === null || offered.includes("CARD");
+  if (pix && card) return "PIX ou cartão";
+  if (pix) return "PIX";
+  if (card) return "cartão";
+  return null;
+}
+
+/** The full "where you are going and what happens there" sentence. */
+function handoffMessage(config: CheckoutProviderConfig | null): string {
+  const methods = methodsPhrase(config);
+  const choice = methods ? `, onde você escolhe pagar com ${methods}` : "";
+  return `Você será levado ${destinationLabel(config)}${choice}.`;
+}
+
+/** The invitation: what happens next, and the one button that starts it. */
+function HandOffInvite({
+  config,
+  onStart,
+}: {
+  config: CheckoutProviderConfig | null;
+  onStart: () => void;
+}): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  return (
+    <Box
+      data-testid="checkout-handoff-invite"
+      sx={{ display: "flex", flexDirection: "column", gap: 2 }}
+    >
+      <Text variant="body" size="md" as="p">
+        {handoffMessage(config)}
+      </Text>
+      <Text variant="caption" size="sm" as="p" color="secondary">
+        Assim que o pagamento for concluído, você volta para cá e nós confirmamos o pedido.
+      </Text>
+      <Button
+        variant="solid"
+        color="primary"
+        size="lg"
+        fullWidth
+        onClick={onStart}
+        dataTestId="checkout-handoff-start"
+      >
+        Seguir para o pagamento
+      </Button>
+    </Box>
+  );
+}
 
+/**
+ * The moment after the button: the charge is being raised, then we navigate.
+ *
+ * Says the SAME sentence the invite did, from the same helper. It used to word
+ * the destination differently — "a página segura do provedor" against the
+ * invite's named one — so the screen appeared to change its mind about where
+ * the buyer was going at the exact moment they committed to going there.
+ */
+function HandOffPending({ config }: { config: CheckoutProviderConfig | null }): JSX.Element {
+  const { Text, LoadingState } = useCheckoutComponents();
   return (
     <Box
       data-testid="checkout-handoff-pending"
@@ -42,11 +128,26 @@ export function HostedLinkScreen({ method }: ProviderCheckoutScreenProps): JSX.E
     >
       <LoadingState variant="spinner" message="Preparando o pagamento" size="md" />
       <Text variant="body" size="md" as="p">
-        Você será levado à página segura do provedor para concluir o pagamento.
+        {handoffMessage(config)}
       </Text>
       <Text variant="caption" size="sm" as="p" color="secondary">
-        Assim que terminar, você volta para cá e nós confirmamos o pedido.
+        Assim que o pagamento for concluído, você volta para cá e nós confirmamos o pedido.
       </Text>
     </Box>
   );
 }
+
+export function HostedLinkScreen({
+  method,
+  config,
+  onStart,
+}: ProviderCheckoutScreenProps): JSX.Element | null {
+  // A method is only ever set here once the buyer has committed — either by
+  // pressing the CTA below, or (on a host whose shell still renders a picker)
+  // by choosing a tile. Both mean the same thing: the hand-off is underway.
+  if (method) return <HandOffPending config={config} />;
+  // No method and no CTA to offer ⇒ the shell is still showing its picker, and
+  // the pane stays out of the way exactly as every other screen does.
+  if (!onStart) return null;
+  return <HandOffInvite config={config} onStart={onStart} />;
+}

package/src/components/checkout/providers/registry.ts

@@ -26,8 +26,10 @@
  * to an empty pane.
  */
 import { CapabilityDefaultScreen } from "./capability-default";
+import { handsBuyerOver } from "./hands-over";
 import { HostedLinkScreen } from "./hosted-link";
 import { PixAndCardScreen } from "./pix-and-card";
+import type { CheckoutProviderConfig } from "../types";
 import type { ProviderCheckoutScreen } from "./types";
 
 /**
@@ -76,3 +78,31 @@ export function resolveCheckoutScreen(
 ): ProviderCheckoutScreen {
   return screenFor(chainHeadScreen) ?? CapabilityDefaultScreen;
 }
+
+/**
+ * Does the buyer choose PIX-or-card on the PROVIDER's page rather than on ours?
+ *
+ * The shell asks this before rendering its method picker, and hides the picker
+ * when the answer is yes (FUT-596 follow-up). A hand-off store asks the
+ * question twice otherwise: once here, where the answer changes nothing —
+ * every method mints the same checkout link — and again on the provider's own
+ * page, where it is finally binding. The first ask is not merely redundant, it
+ * is misleading: the buyer who picked PIX here has picked nothing, and finding
+ * the same two options waiting for them on another site reads as a checkout
+ * that lost their answer.
+ *
+ * Resolved in the SAME order as {@link resolveCheckoutScreen} — a declared id
+ * wins, and an undeclared or unknown one falls back to the capability read —
+ * so the picker and the pane can never disagree about which flow this is. That
+ * is why the test is an identity check against the hand-off screen rather than
+ * a second table of ids: a table would be the copy that drifts, and it would
+ * drift the moment a new hand-off adapter declared its own id.
+ */
+export function methodChosenAtProvider(
+  chainHeadScreen: string | null | undefined,
+  config: CheckoutProviderConfig | null,
+): boolean {
+  const declared = screenFor(chainHeadScreen);
+  if (declared) return declared === HostedLinkScreen;
+  return handsBuyerOver(config);
+}

package/src/components/checkout/providers/types.ts

@@ -46,8 +46,26 @@ export interface ProviderCheckoutScreenProps {
    * those readings call the helpers themselves.
    */
   config: CheckoutProviderConfig | null;
-  /** What the shell's picker currently has selected; `null` before a choice. */
+  /**
+   * What the shell currently has selected; `null` before a choice.
+   *
+   * `null` is also the resting state of a screen that OWNS the choice (see
+   * {@link ProviderCheckoutScreenProps.onStart}): nothing is selected until
+   * the buyer presses that screen's own CTA.
+   */
   method: PaymentMethod | null;
+  /**
+   * Present ⇒ this screen owns the "how do I start paying" affordance, because
+   * the shell has hidden its method picker for it (FUT-596 follow-up). Calling
+   * it commits the buyer to the store's hand-off method and raises the charge,
+   * exactly as choosing a tile in the picker does.
+   *
+   * Absent for every screen where the picker is still on the page — those
+   * screens must not grow a second way to start the same charge.
+   */
+  onStart?: () => void;
+  /** A charge is being raised right now — the shell's own busy flag. */
+  creating?: boolean;
   /** Scopes the saved-card list to the store being paid. */
   tenantSlug?: string;
   /** The shell's polling cadence, passed through so tests can shorten it. */

package/src/components/checkout/types.ts

@@ -250,6 +250,17 @@ export interface CheckoutCustomerField {
  */
 export interface CheckoutChainLink {
   provider: string;
+  /**
+   * The provider's own name as a BUYER should read it ("InfinitePay"), which
+   * `GET /api/checkout/config` publishes per entry.
+   *
+   * Optional, and the DEGRADE DIRECTION IS "SAY NOTHING": an older host serves
+   * no name, and a hand-off screen then describes where the buyer is going
+   * without naming it, rather than printing the internal `provider` id — a
+   * buyer shown "infinitepay" learns less than one shown nothing, and learns
+   * it in a vocabulary that is ours rather than theirs.
+   */
+  displayName?: string | null;
   tokenization: "NONE" | "PUBLIC_KEY" | "SDK" | "REDIRECT";
   publicKey: string | null;
   mockTokenization: boolean;