@12-apps/payments-frontend 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.16.0",
+  "version": "1.18.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": "^1.16.0",
+    "@12-apps/payments-backend": "^1.18.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -28,8 +28,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.18.0",
-    "@12-apps/typescript-config": "^1.18.0",
+    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/typescript-config": "^1.20.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",

package/src/components/ProviderConnection.tsx

@@ -16,6 +16,7 @@ import {
 import { useState } from 'react';
 
 import type {
+  ConnectedOAuthAccount,
   MaskedProviderConfig,
   PaymentEnvironment,
   ProviderDescriptor,
@@ -85,6 +86,54 @@ function connectLabel(displayName: string, connected: boolean, busy: string | nu
   return connected ? 'Reconectar' : `Conectar com ${displayName}`;
 }
 
+/**
+ * pt-BR labels for the scopes a store owner actually sees. Unknown scopes fall
+ * back to the provider's own spelling — wrong words are worse than raw ones.
+ */
+const SCOPE_LABELS: Record<string, string> = {
+  'payments.read': 'Consultar pagamentos',
+  'payments.create': 'Criar cobranças',
+  'payments.refund': 'Estornar pagamentos',
+  'accounts.read': 'Consultar dados da conta',
+};
+
+/**
+ * WHICH account is connected (FUT-300): identity, granted scopes and the
+ * connect date — the difference between "conectado" and "conectado como".
+ * Without it, the only way an owner could tell which PagBank account a store
+ * charges into was to disconnect and connect again.
+ */
+function ConnectedAccountDetails(props: { account: ConnectedOAuthAccount }) {
+  const { account } = props;
+  const identity = account.accountLabel ?? account.accountId;
+  return (
+    <Stack spacing={0.5} data-testid="payments-connected-account">
+      {identity ? (
+        <Typography variant="body2">
+          Conta conectada: <strong>{identity}</strong>
+        </Typography>
+      ) : null}
+      {account.connectedAt ? (
+        <Typography variant="caption" color="text.secondary">
+          {`Conectada em ${new Date(account.connectedAt).toLocaleString('pt-BR')}`}
+        </Typography>
+      ) : null}
+      {account.grantedScopes.length > 0 ? (
+        <Stack direction="row" spacing={0.5} useFlexGap flexWrap="wrap">
+          {account.grantedScopes.map((scope) => (
+            <Chip
+              key={scope}
+              size="small"
+              variant="outlined"
+              label={SCOPE_LABELS[scope] ?? scope}
+            />
+          ))}
+        </Stack>
+      ) : null}
+    </Stack>
+  );
+}
+
 /** Header + explanatory copy + any warning banner for the connection. */
 function ConnectionSummary(props: {
   displayName: string;
@@ -92,6 +141,7 @@ function ConnectionSummary(props: {
   connected: boolean;
   expiresAt: string | null;
   environment: PaymentEnvironment;
+  connectedAccount: ConnectedOAuthAccount | null;
 }) {
   return (
     <>
@@ -118,6 +168,9 @@ function ConnectionSummary(props: {
           ? 'Sua conta está conectada. O Future Pay cria as cobranças em seu nome — nenhuma chave precisa ser copiada.'
           : `Conecte sua conta ${props.displayName} autorizando o acesso no site do provedor. Nenhuma chave precisa ser copiada.`}
       </Typography>
+      {props.connected && props.connectedAccount ? (
+        <ConnectedAccountDetails account={props.connectedAccount} />
+      ) : null}
       {props.status === 'RECONNECT_REQUIRED' ? (
         <Alert severity="warning">
           A autorização expirou ou foi revogada. Reconecte para voltar a receber pagamentos.
@@ -243,6 +296,7 @@ export function ProviderConnection(props: ProviderConnectionProps) {
         connected={connected}
         expiresAt={config?.expiresAt ?? null}
         environment={environment}
+        connectedAccount={config?.connectedAccount ?? null}
       />
 
       {error ? <Alert severity="error">{error}</Alert> : null}

package/src/components/checkout/apple-pay-button.tsx

@@ -0,0 +1,189 @@
+import { Box } from "@mui/material";
+import { useRef, type JSX } from "react";
+
+import type { CheckoutOrder } from "./types";
+
+/**
+ * The Apple-owned pay button (FUT-472), on `ApplePaySession` — the API Safari
+ * ships natively; there is no script to load. This component owns token
+ * ACQUISITION: feature-detect, render Apple's button, run the session, and
+ * turn an authorized payment into the wallet key (Apple's `token.paymentData`,
+ * serialized verbatim). The charge itself belongs to the pane above
+ * (`wallet-pane.tsx`), which reports back so the sheet can be completed with
+ * the honest status.
+ *
+ * ## Visa and Mastercard ONLY — a money rule, not a default
+ *
+ * PagBank currently processes Apple Pay for Visa and Mastercard alone. The
+ * sheet's `supportedNetworks` is the one gate that keeps every other card
+ * from being OFFERED: a shopper whose wallet holds only an Elo card sees the
+ * sheet refuse selection instead of authorizing a payment PagBank then
+ * declines. Widening this list is a provider fact change, not a UI choice.
+ *
+ * ## The fallback is the card form
+ *
+ * A device without Apple Pay, a store that never declared the wallet, or a
+ * merchant validation that cannot run all degrade the same way: no button,
+ * and the card form the pane always renders stays. The buyer loses a
+ * shortcut, never the ability to pay.
+ */
+
+/** PagBank processes Apple Pay for these networks ONLY. See module comment. */
+export const APPLE_PAY_SUPPORTED_NETWORKS = ["visa", "masterCard"] as const;
+
+/** ApplePaySession API version 3 — the floor for the fields this sheet uses. */
+const APPLE_PAY_VERSION = 3;
+
+/** The payment-request slice this checkout builds. */
+export interface ApplePayPaymentRequest {
+  countryCode: string;
+  currencyCode: string;
+  supportedNetworks: readonly string[];
+  merchantCapabilities: readonly string[];
+  total: { label: string; amount: string };
+}
+
+/** The session events/methods this button drives. */
+export interface ApplePaySessionLike {
+  onvalidatemerchant: ((event: { validationURL: string }) => void) | null;
+  onpaymentauthorized: ((event: { payment: { token: { paymentData: unknown } } }) => void) | null;
+  oncancel: (() => void) | null;
+  begin(): void;
+  abort(): void;
+  completeMerchantValidation(merchantSession: unknown): void;
+  completePayment(result: { status: number }): void;
+}
+
+/** The `window.ApplePaySession` constructor, as far as this button needs it. */
+export interface ApplePaySessionClass {
+  new (version: number, request: ApplePayPaymentRequest): ApplePaySessionLike;
+  canMakePayments(): boolean;
+  STATUS_SUCCESS: number;
+  STATUS_FAILURE: number;
+}
+
+/** The native constructor, where Safari (or a harness) provides one. */
+function applePaySessionClass(): ApplePaySessionClass | null {
+  if (typeof window === "undefined") return null;
+  const scope = window as unknown as { ApplePaySession?: ApplePaySessionClass };
+  return scope.ApplePaySession ?? null;
+}
+
+/**
+ * Whether THIS device can show the sheet at all — the synchronous half of the
+ * gate (the capability half is `applePayDeclared`). Exported so the pane can
+ * decide whether any wallet chrome (the divider) is worth rendering.
+ */
+export function applePaySupported(): boolean {
+  const Session = applePaySessionClass();
+  if (!Session) return false;
+  try {
+    return Session.canMakePayments();
+  } catch {
+    return false;
+  }
+}
+
+/** The sheet's payment request, from the server-authoritative order total. */
+function paymentRequest(order: CheckoutOrder): ApplePayPaymentRequest {
+  return {
+    countryCode: "BR",
+    currencyCode: "BRL",
+    supportedNetworks: APPLE_PAY_SUPPORTED_NETWORKS,
+    merchantCapabilities: ["supports3DS"],
+    total: { label: "Total do pedido", amount: (order.totalCents / 100).toFixed(2) },
+  };
+}
+
+export interface ApplePayButtonProps {
+  order: CheckoutOrder;
+  /**
+   * The payment authorized on the sheet — charge this key. Resolves `true`
+   * when the charge was accepted (paid, or confirming), `false` on a refusal,
+   * so the sheet can be completed with the honest status.
+   */
+  onAuthorized: (key: string) => Promise<boolean>;
+  /** A session failure worth telling the buyer about (not a dismissal). */
+  onError: (message: string) => void;
+  /**
+   * The host's merchant-validation port: exchange `validationURL` for an
+   * Apple merchant session, SERVER-SIDE (the merchant identity certificate
+   * must never reach a browser). Absent — the external prerequisites are not
+   * done, or the host has not wired it — the session aborts with a pt-BR
+   * message and the card form remains the way to pay.
+   */
+  validateMerchant?: (validationURL: string) => Promise<unknown>;
+}
+
+/** Wire one session run. Split from the component for the size gate. */
+function runSession(
+  Session: ApplePaySessionClass,
+  order: CheckoutOrder,
+  handlers: ApplePayButtonProps,
+): void {
+  const session = new Session(APPLE_PAY_VERSION, paymentRequest(order));
+  session.onvalidatemerchant = (event) => {
+    const validate = handlers.validateMerchant;
+    if (!validate) {
+      session.abort();
+      handlers.onError("Não foi possível iniciar o Apple Pay nesta loja. Pague com cartão.");
+      return;
+    }
+    validate(event.validationURL)
+      .then((merchantSession) => session.completeMerchantValidation(merchantSession))
+      .catch(() => {
+        session.abort();
+        handlers.onError("Não foi possível iniciar o Apple Pay. Tente novamente ou pague com cartão.");
+      });
+  };
+  session.onpaymentauthorized = (event) => {
+    // Apple's `token.paymentData`, serialized VERBATIM — PagBank's `key`.
+    const key = JSON.stringify(event.payment.token.paymentData);
+    void handlers.onAuthorized(key).then((accepted) => {
+      session.completePayment({
+        status: accepted ? Session.STATUS_SUCCESS : Session.STATUS_FAILURE,
+      });
+    });
+  };
+  // Closing the sheet is a choice, not a failure to report.
+  session.oncancel = () => undefined;
+  session.begin();
+}
+
+/**
+ * Renders NOTHING unless this device can pay — the sheet's own
+ * `supportedNetworks` then keeps unsupported cards from being offered on a
+ * device that can. The pixels are Apple's (`-apple-pay-button` appearance, as
+ * their Human Interface Guidelines require); only Safari ever renders this,
+ * because only Safari passes the feature-detect.
+ */
+export function ApplePayButton(props: ApplePayButtonProps): JSX.Element | null {
+  // The latest handlers/order, so a session opened from a click never closes
+  // over a stale charge target.
+  const current = useRef(props);
+  current.current = props;
+  const Session = applePaySessionClass();
+  if (!Session || !applePaySupported()) return null;
+  return (
+    <Box
+      component="button"
+      type="button"
+      aria-label="Pagar com Apple Pay"
+      data-testid="apple-pay-button"
+      onClick={() => runSession(Session, current.current.order, current.current)}
+      sx={{
+        WebkitAppearance: "-apple-pay-button",
+        // Apple draws the button; these only give it room. The fallback
+        // colors are unreachable in practice (only Safari gets here) but keep
+        // the element visible if the appearance ever fails to apply.
+        height: 40,
+        width: "100%",
+        border: 0,
+        borderRadius: 2,
+        cursor: "pointer",
+        bgcolor: "common.black",
+        color: "common.white",
+      }}
+    />
+  );
+}

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

@@ -46,6 +46,13 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   providerConfig?: CheckoutProviderConfig | null;
   /** Scopes the saved-card list to the store being paid. */
   tenantSlug?: string;
+  /**
+   * The host's Apple Pay merchant-validation port (FUT-472): exchange the
+   * session's `validationURL` for an Apple merchant session, SERVER-SIDE.
+   * Optional — without it the Apple Pay sheet cannot start, and the card form
+   * remains the way to pay.
+   */
+  validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** Host content shown on the paid confirmation (the storefront's install invite). */
   confirmationExtra?: ReactNode;
   /** Design-system slots; unfilled slots render the raw-MUI defaults. */
@@ -118,7 +125,7 @@ function ProgressHeader({ step, completed }: { step: string; completed: Set<stri
  * card public key are loaded lazily by the card path (order-scoped REST).
  */
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { cart, defaultBuyer, comanda, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, ...ports } = props;
+  const { cart, defaultBuyer, comanda, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, ...ports } = props;
   // Resolved for NO method on purpose (FUT-595): the Dados step opens before
   // the picker, and the form is filled once — so it asks for the union of what
   // any chain member may need rather than re-opening after the choice. A chain
@@ -176,6 +183,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
           onEditBuyer={c.editBuyer}
           providerConfig={providerConfig}
           tenantSlug={tenantSlug}
+          validateApplePayMerchant={validateApplePayMerchant}
           onResolved={c.handleResolved}
         />
       ) : null}

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

@@ -71,6 +71,7 @@ function PaymentBody({
   tenantSlug,
   onResolved,
   pollIntervalMs,
+  validateApplePayMerchant,
 }: {
   order: CheckoutOrder | null;
   buyer: BuyerInfo;
@@ -79,6 +80,7 @@ function PaymentBody({
   tenantSlug?: string;
   onResolved: (status: OrderStatus) => void;
   pollIntervalMs?: number;
+  validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
 }): JSX.Element | null {
   const Screen = resolveCheckoutScreen(providerConfig?.chain?.[0]?.checkoutScreen);
   return (
@@ -90,6 +92,7 @@ function PaymentBody({
       tenantSlug={tenantSlug}
       onResolved={onResolved}
       pollIntervalMs={pollIntervalMs}
+      validateApplePayMerchant={validateApplePayMerchant}
     />
   );
 }
@@ -291,6 +294,8 @@ interface PaymentStepProps {
   /** Scopes the saved-card list to the store being paid (host routing owns it). */
   tenantSlug?: string;
   pollIntervalMs?: number;
+  /** The host's Apple Pay merchant-validation port (FUT-472) — see the screen contract. */
+  validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   onResolved: (status: OrderStatus) => void;
 }
 
@@ -314,6 +319,7 @@ export function PaymentStep({
   providerConfig,
   tenantSlug,
   pollIntervalMs,
+  validateApplePayMerchant,
   onResolved,
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
@@ -342,6 +348,7 @@ export function PaymentStep({
         tenantSlug={tenantSlug}
         onResolved={onResolved}
         pollIntervalMs={pollIntervalMs}
+        validateApplePayMerchant={validateApplePayMerchant}
       />
 
       {!order && creating ? (

package/src/components/checkout/client-context.tsx

@@ -20,6 +20,7 @@ import { createContext, useContext, type JSX, type ReactNode } from "react";
 
 import {
   chargeCard,
+  chargeWallet,
   fetchCheckoutConfig,
   listSavedCards,
   pollOrderStatus,
@@ -32,6 +33,7 @@ const DEFAULT_CLIENT: CheckoutClient = {
   getConfig: (tenantSlug) => fetchCheckoutConfig(tenantSlug),
   getStatus: (ref) => pollOrderStatus(ref),
   charge: (input) => chargeCard(input),
+  chargeWallet: (input) => chargeWallet(input),
   listInstruments: (tenantSlug) => listSavedCards(tenantSlug),
   refreshBrowserKey: (input) => refreshCardPublicKey(input),
 };

package/src/components/checkout/client.ts

@@ -28,6 +28,7 @@ import { createCheckoutClient } from "./transport";
 import type {
   ChargeCardInput,
   ChargeOutcome,
+  ChargeWalletInput,
   CheckoutProviderConfig,
   OrderStatus,
 } from "./types";
@@ -77,6 +78,15 @@ export async function chargeCard(input: ChargeCardInput): Promise<Result<ChargeO
   return defaultClient.charge(input);
 }
 
+/**
+ * Charge a wallet-minted instrument against an order (FUT-471/472) — the same
+ * `/charge` route as {@link chargeCard}, carrying `wallet: { type, key }` in
+ * place of a card token.
+ */
+export async function chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>> {
+  return defaultClient.chargeWallet(input);
+}
+
 /** List saved cards available for reuse (empty on any error — non-blocking). */
 export async function listSavedCards(tenantSlug?: string): Promise<SavedCard[]> {
   return defaultClient.listInstruments(tenantSlug);

package/src/components/checkout/google-pay-button.tsx

@@ -0,0 +1,263 @@
+import { Box } from "@mui/material";
+import { useEffect, useRef, useState, type JSX } from "react";
+
+import type { CheckoutOrder } from "./types";
+
+/**
+ * The Google-branded pay button (FUT-471), per Google's four-step web guide —
+ * and ONLY the four steps. This component owns token ACQUISITION: load
+ * `pay.js`, construct a `PaymentsClient`, gate rendering on `isReadyToPay`,
+ * render the button Google's brand rules require via `createButton`, and turn
+ * `loadPaymentData` into the wallet key
+ * (`paymentData.paymentMethodData.tokenizationData.token`). What happens to
+ * the key — the charge, the polling, the outcome — belongs to the pane above
+ * (`wallet-pane.tsx`), so this file never talks to the wire.
+ *
+ * The `tokenizationSpecification` is `{ type: 'PAYMENT_GATEWAY', gateway,
+ * gatewayMerchantId }`, both parameters published by the store's chain head
+ * (`googlePayConfig`) — no vendor name is spelled here.
+ */
+
+/** The slice of Google's `PaymentsClient` this button drives. */
+export interface GooglePaymentsClient {
+  isReadyToPay(request: Record<string, unknown>): Promise<{ result: boolean }>;
+  createButton(options: {
+    onClick: () => void;
+    buttonSizeMode?: string;
+    buttonLocale?: string;
+  }): HTMLElement;
+  loadPaymentData(request: Record<string, unknown>): Promise<GooglePaymentData>;
+}
+
+/** The one path of the payment data this checkout reads. */
+export interface GooglePaymentData {
+  paymentMethodData: { tokenizationData: { token: string } };
+}
+
+/** The `google.payments.api` namespace, as far as this button needs it. */
+export interface GooglePayApi {
+  PaymentsClient: new (options: { environment: "TEST" | "PRODUCTION" }) => GooglePaymentsClient;
+}
+
+/** What the store's chain head published for the tokenizationSpecification. */
+export interface GooglePayGatewayParams {
+  gateway: string;
+  gatewayMerchantId: string;
+}
+
+/** Google's script, loaded once per page. */
+const PAY_JS_URL = "https://pay.google.com/gp/p/js/pay.js";
+
+/**
+ * Card networks offered to Google: the intersection of Google's
+ * `allowedCardNetworks` enum and what PagBank's card acquiring processes.
+ * A network the gateway would refuse must not be offered on the sheet.
+ */
+const ALLOWED_CARD_NETWORKS = ["AMEX", "ELO", "MASTERCARD", "VISA"];
+
+/** Both auth methods of Google's guide: tokenized device cards and PAN_ONLY. */
+const ALLOWED_AUTH_METHODS = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
+
+/** The `google.payments.api` global, when a script (or a harness) installed it. */
+function installedApi(): GooglePayApi | null {
+  if (typeof window === "undefined") return null;
+  const scope = window as unknown as { google?: { payments?: { api?: GooglePayApi } } };
+  return scope.google?.payments?.api ?? null;
+}
+
+/** The in-flight (or settled) pay.js load — one script tag per page, ever. */
+const loader: { pending: Promise<GooglePayApi | null> | null } = { pending: null };
+
+/**
+ * Step 1 of the guide: load `pay.js` and hand back the API namespace. Answers
+ * `null` — never throws — when the script cannot load: an offline CDN must
+ * degrade to "no button", not to a crashed checkout. A pre-installed global
+ * (another button on the page, or an e2e harness) is used without a network
+ * request.
+ */
+function loadGooglePayApi(): Promise<GooglePayApi | null> {
+  const installed = installedApi();
+  if (installed) return Promise.resolve(installed);
+  if (typeof document === "undefined") return Promise.resolve(null);
+  loader.pending ??= new Promise((resolve) => {
+    const script = document.createElement("script");
+    script.src = PAY_JS_URL;
+    script.async = true;
+    script.onload = () => resolve(installedApi());
+    script.onerror = () => resolve(null);
+    document.head.appendChild(script);
+  });
+  return loader.pending;
+}
+
+/** Step 2's probe: may this browser/device pay at all? */
+function isReadyToPayRequest(): Record<string, unknown> {
+  return {
+    apiVersion: 2,
+    apiVersionMinor: 0,
+    allowedPaymentMethods: [
+      {
+        type: "CARD",
+        parameters: {
+          allowedAuthMethods: ALLOWED_AUTH_METHODS,
+          allowedCardNetworks: ALLOWED_CARD_NETWORKS,
+        },
+      },
+    ],
+  };
+}
+
+/** Step 4's request: the same card method, now carrying gateway + price. */
+function paymentDataRequest(
+  params: GooglePayGatewayParams,
+  order: CheckoutOrder,
+): Record<string, unknown> {
+  return {
+    apiVersion: 2,
+    apiVersionMinor: 0,
+    allowedPaymentMethods: [
+      {
+        type: "CARD",
+        parameters: {
+          allowedAuthMethods: ALLOWED_AUTH_METHODS,
+          allowedCardNetworks: ALLOWED_CARD_NETWORKS,
+        },
+        tokenizationSpecification: {
+          type: "PAYMENT_GATEWAY",
+          parameters: {
+            gateway: params.gateway,
+            gatewayMerchantId: params.gatewayMerchantId,
+          },
+        },
+      },
+    ],
+    transactionInfo: {
+      totalPriceStatus: "FINAL",
+      // Integer cents to Google's decimal string — the one money conversion
+      // in this file, from the server-authoritative order total.
+      totalPrice: (order.totalCents / 100).toFixed(2),
+      currencyCode: "BRL",
+      countryCode: "BR",
+    },
+  };
+}
+
+/** The buyer closed the sheet — a choice, not a failure to report. */
+function sheetDismissed(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { statusCode?: unknown }).statusCode === "CANCELED"
+  );
+}
+
+/**
+ * Resolve the client and ask `isReadyToPay` — the gate that decides whether
+ * the button exists at all. `api` is injectable for tests and harnesses;
+ * `undefined` means "load pay.js".
+ */
+function useGooglePayClient(
+  api: GooglePayApi | null | undefined,
+  environment: "TEST" | "PRODUCTION",
+): GooglePaymentsClient | null {
+  const [client, setClient] = useState<GooglePaymentsClient | null>(null);
+  useEffect(() => {
+    const alive = { current: true };
+    void (api === undefined ? loadGooglePayApi() : Promise.resolve(api)).then((resolved) => {
+      if (!alive.current || !resolved) return;
+      const paymentsClient = new resolved.PaymentsClient({ environment });
+      paymentsClient
+        .isReadyToPay(isReadyToPayRequest())
+        .then((answer) => {
+          if (alive.current && answer.result) setClient(paymentsClient);
+        })
+        .catch(() => undefined);
+    });
+    return () => {
+      alive.current = false;
+    };
+  }, [api, environment]);
+  return client;
+}
+
+export interface GooglePayButtonProps {
+  order: CheckoutOrder;
+  /** The chain head's published gateway parameters (`googlePayConfig`). */
+  params: GooglePayGatewayParams;
+  /** The sheet resolved — charge this key. */
+  onKey: (key: string) => void;
+  /** The sheet failed for a reason worth telling the buyer (not a dismissal). */
+  onError: (message: string) => void;
+  /**
+   * Google's environment. Defaults to TEST — production requires the external
+   * Google Pay registration (see the ticket), and TEST tokens exercise the
+   * whole path against PagBank's sandbox with fictitious instruments.
+   */
+  environment?: "TEST" | "PRODUCTION";
+  /** Injectable API namespace for tests/harnesses; omit to load pay.js. */
+  api?: GooglePayApi | null;
+  /**
+   * Fired once `isReadyToPay` approved and the button will render — how the
+   * pane knows its wallet chrome (the divider) has something to sit above.
+   */
+  onReady?: () => void;
+}
+
+/**
+ * Renders NOTHING until `isReadyToPay` says this browser can pay — per the
+ * guide, the buyer must never see a Google Pay button that cannot work. The
+ * button element itself comes from `createButton` (brand rules); this
+ * component only gives it a mount point.
+ */
+export function GooglePayButton({
+  order,
+  params,
+  onKey,
+  onError,
+  environment = "TEST",
+  api,
+  onReady,
+}: GooglePayButtonProps): JSX.Element | null {
+  const client = useGooglePayClient(api, environment);
+  const container = useRef<HTMLDivElement | null>(null);
+  // The latest handlers/order, so the Google-rendered button — mounted once —
+  // never closes over a stale charge target.
+  const current = useRef({ order, params, onKey, onError, onReady });
+  current.current = { order, params, onKey, onError, onReady };
+
+  useEffect(() => {
+    if (client) current.current.onReady?.();
+  }, [client]);
+
+  useEffect(() => {
+    const mount = container.current;
+    if (!client || !mount) return undefined;
+    const button = client.createButton({
+      onClick: () => {
+        const { order: forOrder, params: forParams, onKey: emit, onError: fail } = current.current;
+        client
+          .loadPaymentData(paymentDataRequest(forParams, forOrder))
+          .then((data) => emit(data.paymentMethodData.tokenizationData.token))
+          .catch((error: unknown) => {
+            if (sheetDismissed(error)) return;
+            fail("Não foi possível concluir o pagamento com o Google Pay. Tente novamente ou pague com cartão.");
+          });
+      },
+      buttonSizeMode: "fill",
+      buttonLocale: "pt",
+    });
+    mount.replaceChildren(button);
+    return () => {
+      mount.replaceChildren();
+    };
+  }, [client]);
+
+  if (!client) return null;
+  return (
+    <Box
+      ref={container}
+      data-testid="google-pay-button"
+      sx={{ minHeight: 40, "& > *": { width: "100%" } }}
+    />
+  );
+}