@12-apps/payments-frontend 3.5.0 → 3.7.0

package/src/components/checkout/payment-status.tsx

@@ -4,6 +4,7 @@ import type { JSX, ReactNode } from "react";
 import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
 import type { OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
+import type { PaymentStatusCopy } from "./view-copy";
 
 /**
  * The last screen of checkout.
@@ -28,67 +29,38 @@ import { useCheckoutComponents } from "./ui";
  * screen says and how it is arranged has changed.
  */
 
-/** Everything the hero block needs, per outcome. */
-interface Outcome {
-  heading: string;
-  support: string;
+/**
+ * The per-outcome VISUAL grammar — icon and semantic tone. The heading and
+ * supporting line beside them come from {@link PaymentStatusCopy}: an icon is
+ * the component's own vocabulary, a sentence never is. (The FAILED support
+ * line's job — say "nothing was charged" plainly and first — and the
+ * timed-out wait's "do not pay again" now live with the host's words, where
+ * FUT-556's reasoning is documented on the copy port.)
+ */
+interface OutcomeVisual {
   icon: JSX.Element;
   /** Semantic theme token — never a raw colour. */
   tone: "success" | "danger" | "warning" | "neutral";
 }
 
-const OUTCOME: Record<OrderStatus, Outcome> = {
-  PAID: {
-    heading: "Pedido confirmado",
-    support: "Recebemos seu pagamento e já registramos o pedido.",
-    icon: <CheckCircleOutlineIcon fontSize="large" />,
-    tone: "success",
-  },
-  AWAITING_PAYMENT: {
-    heading: "Confirmando seu pagamento",
-    support: "Isso costuma levar alguns segundos. Pode deixar esta tela aberta.",
-    icon: <ScheduleIcon fontSize="large" />,
-    tone: "neutral",
-  },
-  FAILED: {
-    heading: "Pagamento não concluído",
-    // Said plainly and first: the fear on this screen is having been charged
-    // for an order that failed.
-    support: "Nenhum valor foi cobrado. Você pode tentar novamente.",
-    icon: <ErrorOutlineIcon fontSize="large" />,
-    tone: "danger",
-  },
-  EXPIRED: {
-    heading: "O código expirou",
-    support: "Nenhum valor foi cobrado. Gere um novo código para continuar.",
-    icon: <ScheduleIcon fontSize="large" />,
-    tone: "warning",
-  },
+const OUTCOME_VISUAL: Record<OrderStatus, OutcomeVisual> = {
+  PAID: { icon: <CheckCircleOutlineIcon fontSize="large" />, tone: "success" },
+  AWAITING_PAYMENT: { icon: <ScheduleIcon fontSize="large" />, tone: "neutral" },
+  FAILED: { icon: <ErrorOutlineIcon fontSize="large" />, tone: "danger" },
+  EXPIRED: { icon: <ScheduleIcon fontSize="large" />, tone: "warning" },
 };
 
-/**
- * What the screen says once it has stopped asking (FUT-556).
- *
- * NOT an `OrderStatus`: the order really is still AWAITING_PAYMENT and may yet
- * settle — the scheduled reconciliation keeps asking the provider long after
- * this tab is gone. What ran out is the WAIT, not the order, and saying
- * otherwise would be the more expensive lie: a buyer told "não concluído" who
- * has in fact paid will either pay twice or call the store.
- *
- * So it leads with what is true and unglamorous — we have not heard yet — and
- * spends its remaining words on the one instruction that matters, which is not
- * to pay again.
- */
-const AWAITING_TIMED_OUT: Outcome = {
-  heading: "Ainda não recebemos a confirmação",
-  support:
-    "Se você já pagou, o pedido é confirmado assim que a operadora avisar — " +
-    "não pague de novo. Você pode fechar esta tela.",
-  icon: <ScheduleIcon fontSize="large" />,
-  tone: "warning",
+const OUTCOME_COPY_KEY: Record<OrderStatus, keyof Pick<
+  PaymentStatusCopy,
+  "paid" | "awaiting" | "failed" | "expired"
+>> = {
+  PAID: "paid",
+  AWAITING_PAYMENT: "awaiting",
+  FAILED: "failed",
+  EXPIRED: "expired",
 };
 
-const TONE_COLOR: Record<Outcome["tone"], string> = {
+const TONE_COLOR: Record<OutcomeVisual["tone"], string> = {
   success: "success.main",
   danger: "error.main",
   warning: "warning.main",
@@ -109,14 +81,22 @@ function orderReference(orderId: string): string {
 
 /** The headline block: icon, outcome, and one supporting line. */
 function OutcomeHero({
+  copy,
   status,
   timedOut = false,
 }: {
+  copy: PaymentStatusCopy;
   status: OrderStatus;
   timedOut?: boolean;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
-  const outcome = timedOut && status === "AWAITING_PAYMENT" ? AWAITING_TIMED_OUT : OUTCOME[status];
+  const timedOutWait = timedOut && status === "AWAITING_PAYMENT";
+  // The timed-out wait keeps AWAITING's neutral clock icon but WARNING's tone:
+  // the order is not resolved, and calm-but-alert is the visual for that.
+  const visual = timedOutWait
+    ? { icon: OUTCOME_VISUAL.AWAITING_PAYMENT.icon, tone: "warning" as const }
+    : OUTCOME_VISUAL[status];
+  const outcome = timedOutWait ? copy.awaitingTimedOut : copy[OUTCOME_COPY_KEY[status]];
   return (
     <Box
       // `payment-paid` is load-bearing for the storefront journeys — it is how
@@ -133,7 +113,7 @@ function OutcomeHero({
       }
       sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
     >
-      <Box sx={{ color: TONE_COLOR[outcome.tone], display: "flex" }}>{outcome.icon}</Box>
+      <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
       <Text variant="heading" size="md" weight="bold" as="h2">
         {outcome.heading}
       </Text>
@@ -165,10 +145,12 @@ function Fact({ label, value, testId }: { label: string; value: string; testId?:
  * outcome these facts are either untrue or not yet knowable.
  */
 function PaidFacts({
+  copy,
   totalLabel,
   orderId,
   buyerEmail,
 }: {
+  copy: PaymentStatusCopy;
   totalLabel: string;
   orderId?: string;
   buyerEmail?: string;
@@ -185,22 +167,24 @@ function PaidFacts({
         bgcolor: "action.hover",
       }}
     >
-      <Fact label="Valor pago" value={totalLabel} testId="payment-amount" />
+      <Fact label={copy.amountLabel} value={totalLabel} testId="payment-amount" />
       {orderId ? (
-        <Fact label="Pedido" value={`#${orderReference(orderId)}`} testId="payment-reference" />
+        <Fact label={copy.referenceLabel} value={`#${orderReference(orderId)}`} testId="payment-reference" />
       ) : null}
-      {buyerEmail ? <Fact label="Comprovante enviado para" value={buyerEmail} /> : null}
+      {buyerEmail ? <Fact label={copy.receiptEmailLabel} value={buyerEmail} /> : null}
     </Box>
   );
 }
 
 /** The next-action row: retry / regenerate for failures, always back-to-menu. */
 function StatusActions({
+  copy,
   status,
   onRetry,
   onRegenerate,
   onBackToMenu,
 }: {
+  copy: PaymentStatusCopy;
   status: OrderStatus;
   onRetry?: () => void;
   onRegenerate?: () => void;
@@ -211,12 +195,12 @@ function StatusActions({
     <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
       {status === "FAILED" && onRetry ? (
         <Button variant="solid" color="primary" size="lg" onClick={onRetry} dataTestId="payment-retry">
-          Tentar novamente
+          {copy.retryAction}
         </Button>
       ) : null}
       {status === "EXPIRED" && onRegenerate ? (
         <Button variant="solid" color="primary" size="lg" onClick={onRegenerate} dataTestId="payment-regenerate">
-          Gerar novo código
+          {copy.regenerateAction}
         </Button>
       ) : null}
       <Button
@@ -228,13 +212,14 @@ function StatusActions({
         onClick={onBackToMenu}
         dataTestId="payment-back-to-menu"
       >
-        Voltar ao cardápio
+        {copy.backAction}
       </Button>
     </Box>
   );
 }
 
 export function PaymentStatus({
+  copy,
   status,
   totalLabel,
   orderId,
@@ -245,6 +230,8 @@ export function PaymentStatus({
   paidExtra,
   awaitingTimedOut = false,
 }: {
+  /** Every sentence and label this screen renders — the HOST's words. */
+  copy: PaymentStatusCopy;
   status: OrderStatus | null;
   totalLabel: string;
   /** The created order, when there is one — absent before the charge is raised. */
@@ -278,10 +265,10 @@ export function PaymentStatus({
       data-timed-out={awaitingTimedOut ? "true" : undefined}
       sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
     >
-      <OutcomeHero status={effective} timedOut={awaitingTimedOut} />
+      <OutcomeHero copy={copy} status={effective} timedOut={awaitingTimedOut} />
 
       {effective === "PAID" ? (
-        <PaidFacts totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />
+        <PaidFacts copy={copy} totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />
       ) : null}
 
       {effective === "PAID" ? paidExtra : null}
@@ -291,6 +278,7 @@ export function PaymentStatus({
       ) : null}
 
       <StatusActions
+        copy={copy}
         status={effective}
         onRetry={onRetry}
         onRegenerate={onRegenerate}

package/src/components/checkout/payments-unavailable.tsx

@@ -23,8 +23,16 @@ import { Box } from "@mui/material";
 import type { JSX } from "react";
 
 import { useCheckoutComponents } from "./ui";
+import type { PaymentsUnavailableCopy } from "./view-copy";
 
 interface PaymentsUnavailableProps {
+  /**
+   * Every sentence this screen can say — the HOST's words (see
+   * `./view-copy`). Until 6.0.0 the two remedies and the button were compiled
+   * in, in one application's Portuguese, and a host that dutifully passed the
+   * flows copy port still got them.
+   */
+  copy: PaymentsUnavailableCopy;
   /**
    * Whether THIS shopper can settle with a waiter — mesas on AND a mesa of
    * their own. Decides which remedy is offered.
@@ -37,6 +45,7 @@ interface PaymentsUnavailableProps {
 }
 
 export function PaymentsUnavailable({
+  copy,
   waiterAvailable,
   onCallWaiter,
   calling = false,
@@ -47,8 +56,8 @@ export function PaymentsUnavailable({
       <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }} data-testid="checkout-payments-disabled">
         <Alert
           variant="info"
-          title="Pagamento online indisponível"
-          description="Esta loja não recebe pagamentos pelo site. Combine o pagamento diretamente com a loja para concluir seu pedido."
+          title={copy.title}
+          description={copy.body}
           showIcon
         />
       </Box>
@@ -59,8 +68,8 @@ export function PaymentsUnavailable({
     <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }} data-testid="checkout-call-waiter">
       <Alert
         variant="info"
-        title="Pagamento com o garçom"
-        description="Esta loja não recebe pagamentos pelo site. Chame o garçom para fechar a conta na mesa."
+        title={copy.remedyTitle}
+        description={copy.remedyBody}
         showIcon
       />
       {onCallWaiter ? (
@@ -71,7 +80,7 @@ export function PaymentsUnavailable({
           onClick={onCallWaiter}
           dataTestId="checkout-call-waiter-button"
         >
-          {calling ? "Chamando..." : "Chamar garçom"}
+          {calling ? copy.callingAction : copy.callAction}
         </Button>
       ) : null}
     </Box>

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. */