@12-apps/payments-frontend 1.16.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.16.0",
+  "version": "1.17.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.17.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.19.0",
+    "@12-apps/typescript-config": "^1.19.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",

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,253 @@
+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;
+}
+
+/**
+ * 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,
+}: 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 });
+  current.current = { order, params, onKey, onError };
+
+  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%" } }}
+    />
+  );
+}

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

@@ -140,6 +140,33 @@ function toCardLink(link: CheckoutChainLink): CardChainLink {
   };
 }
 
+/**
+ * Everything the Google Pay button needs to mint a token (FUT-471), or `null`
+ * when the button must not render.
+ *
+ * Read off the chain HEAD only, like the checkout screen: the wallet token is
+ * minted against ONE gateway's `gatewayMerchantId`, so only the provider the
+ * walk tries first can charge it — a tail entry's declaration cannot be
+ * honoured from this browser.
+ *
+ * FAILS CLOSED, deliberately the opposite of `offeredMethods`' fail-open: a
+ * missing config only costs the buyer a button they still have the card form
+ * without, while rendering one on a store that cannot charge wallets sends a
+ * buyer through the wallet sheet into a guaranteed refusal. Every clause
+ * narrows toward NOT rendering: no config, no chain, a head that cannot CARD,
+ * no `GOOGLE_PAY` declaration, no gateway parameters, no merchant id.
+ */
+export function googlePayConfig(
+  config: CheckoutProviderConfig | null,
+): { gateway: string; gatewayMerchantId: string } | null {
+  const head = config?.chain?.[0];
+  if (!head?.methods.includes("CARD")) return null;
+  if (!head.wallets?.includes("GOOGLE_PAY")) return null;
+  const params = head.googlePay;
+  if (!params?.gatewayMerchantId) return null;
+  return { gateway: params.gateway, gatewayMerchantId: params.gatewayMerchantId };
+}
+
 /**
  * The methods the picker may offer, from the chain's declared capabilities
  * (FUT-698). `null` config — still loading, or a fetch blip — fails OPEN like

package/src/components/checkout/providers/pix-and-card.tsx

@@ -12,37 +12,22 @@
  */
 import type { JSX } from "react";
 
-import { CardView } from "../card-view";
-import { cardChain, cardTokenization } from "../method-capability";
 import { PixView } from "../pix-view";
+import { WalletCardPane } from "../wallet-pane";
 
 import type { ProviderCheckoutScreenProps } from "./types";
 
-export function PixAndCardScreen({
-  order,
-  buyer,
-  config,
-  tenantSlug,
-  onResolved,
-  pollIntervalMs,
-}: ProviderCheckoutScreenProps): JSX.Element | null {
+export function PixAndCardScreen(props: ProviderCheckoutScreenProps): JSX.Element | null {
+  const { order, onResolved, pollIntervalMs } = props;
   if (order?.method === "PIX") {
     return <PixView order={order} onResolved={onResolved} pollIntervalMs={pollIntervalMs} />;
   }
   if (order?.method === "CARD") {
-    return (
-      <CardView
-        order={order}
-        buyer={buyer}
-        providerConfig={cardTokenization(config)}
-        // The whole chain (FUT-563): one instrument is minted per provider so
-        // the charge survives the first one failing, with nothing re-typed.
-        providerChain={cardChain(config)}
-        tenantSlug={tenantSlug}
-        onResolved={onResolved}
-        pollIntervalMs={pollIntervalMs}
-      />
-    );
+    // The card pane, with its wallet fast lane above the form (FUT-471/472).
+    // The pane reads the chain itself (FUT-563: one instrument per provider,
+    // so the charge survives the first one failing with nothing re-typed) and
+    // renders exactly the old CardView for a store with no wallet.
+    return <WalletCardPane {...props} order={order} />;
   }
   // No order yet — the shell is still showing the picker, and raises one as
   // soon as a method is chosen.

package/src/components/checkout/transport.ts

@@ -21,6 +21,7 @@ import { err, ok, type Result } from "../../result";
 import type {
   ChargeCardInput,
   ChargeOutcome,
+  ChargeWalletInput,
   CheckoutProviderConfig,
   OrderStatus,
 } from "./types";
@@ -45,11 +46,13 @@ export interface CheckoutTransport {
   headers?: () => HeadersInit | Promise<HeadersInit>;
 }
 
-/** The five calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
+/** The six calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
 export interface CheckoutClient {
   getConfig(tenantSlug: string): Promise<Result<CheckoutProviderConfig>>;
   getStatus(ref: string): Promise<Result<OrderStatus>>;
   charge(input: ChargeCardInput): Promise<Result<ChargeOutcome>>;
+  /** A wallet instrument against the same `/charge` route (FUT-471/472). */
+  chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>>;
   listInstruments(tenantSlug?: string): Promise<SavedCard[]>;
   refreshBrowserKey(input: { orderId: string }): Promise<Result<{ publicKey: string | null }>>;
 }
@@ -112,6 +115,36 @@ function ambientFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Res
   return globalThis.fetch(input, init);
 }
 
+/**
+ * The FLAT card-charge body the shipped client has always sent. Pinned from
+ * both ends by `charge-wire.contract.test.ts`; nothing here may re-nest it.
+ */
+function flatChargeBody(input: ChargeCardInput): string {
+  return JSON.stringify({
+    orderId: input.orderId,
+    token: input.token,
+    // One instrument per provider (FUT-563) — the server hands each provider
+    // in the chain its own, which is what lets a card charge fail over.
+    ...(input.tokensByProvider ? { tokensByProvider: input.tokensByProvider } : {}),
+    saveCard: input.saveCard,
+    cardMeta: input.cardMeta,
+    taxId: input.taxId,
+  });
+}
+
+/**
+ * The same flat wire with `wallet` in place of `token` (FUT-471): the mount's
+ * draft reader takes either, and a body naming both would carry two
+ * instruments for one charge. Pinned by `wallet-wire.contract.test.ts`.
+ */
+function flatWalletBody(input: ChargeWalletInput): string {
+  return JSON.stringify({
+    orderId: input.orderId,
+    wallet: input.wallet,
+    taxId: input.taxId,
+  });
+}
+
 /**
  * The five checkout calls, bound to one transport.
  *
@@ -156,22 +189,10 @@ export function createCheckoutClient(transport: CheckoutTransport = {}): Checkou
       ),
 
     charge: (input) =>
-      call<ChargeOutcome>("/charge", {
-        method: "POST",
-        // The FLAT body the shipped client has always sent. Pinned from both
-        // ends by `charge-wire.contract.test.ts`; nothing here may re-nest it.
-        body: JSON.stringify({
-          orderId: input.orderId,
-          token: input.token,
-          // One instrument per provider (FUT-563) — the server hands each
-          // provider in the chain its own, which is what lets a card charge
-          // fail over.
-          ...(input.tokensByProvider ? { tokensByProvider: input.tokensByProvider } : {}),
-          saveCard: input.saveCard,
-          cardMeta: input.cardMeta,
-          taxId: input.taxId,
-        }),
-      }),
+      call<ChargeOutcome>("/charge", { method: "POST", body: flatChargeBody(input) }),
+
+    chargeWallet: (input) =>
+      call<ChargeOutcome>("/charge", { method: "POST", body: flatWalletBody(input) }),
 
     listInstruments: async (tenantSlug) => {
       // Scoped to the store when known (FUT-697): only cards the store's ACTIVE

package/src/components/checkout/types.ts

@@ -12,6 +12,14 @@
 /** Payment methods offered at checkout. Mirrors `Payment.method` (FUT-42). */
 export type PaymentMethod = "PIX" | "CARD";
 
+/**
+ * The digital wallets a chain entry can charge (FUT-471/472). Mirrors the
+ * backend's `WalletType` — a wallet is not a fourth method: it is another way
+ * of producing the CARD instrument, so it rides the CARD tile and the CARD
+ * charge.
+ */
+export type CheckoutWalletType = "GOOGLE_PAY" | "APPLE_PAY";
+
 /**
  * Order lifecycle, aligned with the FUT-43 backend:
  * - `AWAITING_PAYMENT` — order created, charge raised, not yet reconciled (the
@@ -198,6 +206,20 @@ export interface ChargeCardInput {
   taxId?: string;
 }
 
+/**
+ * Input to charge a WALLET instrument against an order (FUT-471/472) —
+ * `ChargeCardInput`'s wallet sibling, posted to the same `/charge` route. One
+ * shape for both wallets because the wire is one shape: `key` is whatever the
+ * wallet handed the browser (Google's `tokenizationData.token`, Apple's
+ * serialized `token.paymentData`), forwarded verbatim and never persisted.
+ */
+export interface ChargeWalletInput {
+  orderId: string;
+  wallet: { type: CheckoutWalletType; key: string };
+  /** Buyer CPF for the provider charge (`customer.tax_id`); never persisted. */
+  taxId?: string;
+}
+
 /** A buyer field a provider asks for, as `/config` publishes it (FUT-595). */
 export interface CheckoutCustomerField {
   key: "name" | "email" | "taxId" | "phone";
@@ -236,6 +258,25 @@ export interface CheckoutChainLink {
    * never shown a field for.
    */
   customerSchema?: CheckoutCustomerField[];
+  /**
+   * The digital wallets THIS entry's card charge accepts (FUT-471/472).
+   *
+   * Optional, and the DEGRADE DIRECTION IS CLOSED — the opposite of
+   * `customerSchema`'s above, because the stakes invert: a chain that asks for
+   * nothing produces a refused charge, but a wallet button on a store whose
+   * server cannot charge wallets produces a buyer who authorized a payment on
+   * the wallet sheet and was then refused. Absent (an older host) means NO
+   * wallet buttons, which is exactly what that host's charge route supports.
+   */
+  wallets?: CheckoutWalletType[];
+  /**
+   * Google Pay's `PAYMENT_GATEWAY` tokenizationSpecification parameters for
+   * THIS entry (FUT-471), or absent/`null` when it cannot run Google Pay.
+   * `gatewayMerchantId: null` means the connection carries no merchant id yet
+   * — the button must not render, because a token minted against a missing id
+   * charges nobody.
+   */
+  googlePay?: { gateway: string; gatewayMerchantId: string | null } | null;
   /**
    * The buyer screen THIS provider's flow needs (FUT-596) — an opaque id the
    * adapter declares and `providers/registry.ts` resolves to a component.

package/src/components/checkout/use-wallet-charge.ts

@@ -0,0 +1,123 @@
+import { useEffect, useState } from "react";
+
+import { useCheckoutClientApi } from "./client-context";
+import { UNRESOLVED_CODE } from "./failure-codes";
+import { rememberHostedOrder } from "./hosted-return";
+import { useCheckoutNavigate } from "./navigate-context";
+import type { BuyerInfo, CheckoutOrder, CheckoutWalletType, OrderStatus } from "./types";
+import { usePaymentPolling } from "./use-payment-polling";
+
+/**
+ * The submit half of a WALLET payment (FUT-471/472) — `useCardSubmit`'s
+ * sibling, minus everything a wallet does not have: no form to validate, no
+ * instrument to mint per provider (the wallet key is chain-head-bound, see the
+ * backend's `core/card-instrument.ts`), no vault opt-in. What remains is the
+ * same money path: charge → classify the outcome → poll for the async
+ * confirmation → bubble the terminal status up.
+ *
+ * One hook for BOTH wallets, because the wire is one shape — the buttons only
+ * differ in how they acquire the key.
+ */
+
+/**
+ * Where the wallet payment stands. `idle` renders the buttons and the card
+ * form; anything else replaces them — a live "pay" control under a charge that
+ * may already be holding the buyer's money is the double-payment invitation
+ * the card view already refuses to render.
+ */
+export type WalletPhase = "idle" | "charging" | "polling";
+
+/** Everything a wallet pane renders — state plus the one submit entry point. */
+export interface WalletCharge {
+  phase: WalletPhase;
+  /** The refusal to show above the form, when the charge came back refused. */
+  error: string | null;
+  /** The refusal's machine code — an UNRESOLVED charge is not a decline. */
+  errorCode: string | null;
+  /** The charge is unresolved: no pay control may render (FUT-563). */
+  unresolved: boolean;
+  pollError: string | null;
+  /** The healthy-poll cap elapsed while still AWAITING (FUT-191). */
+  pollTimedOut: boolean;
+  /** Charge the wallet's key. The button calls this once the sheet resolves. */
+  payWithKey(type: CheckoutWalletType, key: string): Promise<void>;
+}
+
+/**
+ * Healthy-poll cap for the wallet AWAITING wait — the card path's own cap
+ * (FUT-191): 36 polls ≈ 90 s at the 2500 ms default interval.
+ */
+const WALLET_AWAITING_POLL_CAP = 36;
+
+/** The wallet charge state machine. See the module comment. */
+export function useWalletCharge(
+  order: CheckoutOrder,
+  buyer: BuyerInfo,
+  onResolved: (status: OrderStatus) => void,
+  pollIntervalMs = 2500,
+): WalletCharge {
+  const [phase, setPhase] = useState<WalletPhase>("idle");
+  const [error, setError] = useState<string | null>(null);
+  const [errorCode, setErrorCode] = useState<string | null>(null);
+  const client = useCheckoutClientApi();
+  const navigate = useCheckoutNavigate();
+
+  const { status, error: pollError, timedOut: pollTimedOut } = usePaymentPolling(order.orderId, {
+    enabled: phase === "polling",
+    intervalMs: pollIntervalMs,
+    maxHealthyPolls: WALLET_AWAITING_POLL_CAP,
+  });
+
+  useEffect(() => {
+    if (status && status !== "AWAITING_PAYMENT") onResolved(status);
+  }, [status, onResolved]);
+
+  const payWithKey = async (type: CheckoutWalletType, key: string): Promise<void> => {
+    setError(null);
+    setErrorCode(null);
+    setPhase("charging");
+
+    const charged = await client.chargeWallet({
+      orderId: order.orderId,
+      wallet: { type, key },
+      // The CPF the Dados step collected — the provider's required-field gate
+      // reads it from the charge, the payable row has nowhere to keep it.
+      taxId: buyer.taxId,
+    });
+    if (!charged.ok) {
+      setError(charged.error);
+      setErrorCode(charged.code ?? null);
+      // Back to idle — but an UNRESOLVED code sets `unresolved`, and the pane
+      // reads that as "render NO pay control" (FUT-563): some provider may be
+      // holding the money, and a live button under "não pague de novo" is what
+      // the buyer's thumb reaches for.
+      setPhase("idle");
+      return;
+    }
+    // A provider that demands its own page to finish (redirect 3-D Secure,
+    // FUT-698): park the order and hand the buyer over, exactly as the card
+    // path does. `phase` stays as-is — the tab is navigating away.
+    if (charged.data.hostedCheckoutUrl) {
+      rememberHostedOrder(order);
+      navigate(charged.data.hostedCheckoutUrl);
+      return;
+    }
+    // A business outcome (declined → FAILED) shows the status screen; an
+    // accepted charge begins polling for the async confirmation.
+    if (charged.data.status !== "AWAITING_PAYMENT") {
+      onResolved(charged.data.status);
+      return;
+    }
+    setPhase("polling");
+  };
+
+  return {
+    phase,
+    error,
+    errorCode,
+    unresolved: errorCode === UNRESOLVED_CODE,
+    pollError,
+    pollTimedOut,
+    payWithKey,
+  };
+}

package/src/components/checkout/wallet-pane.tsx

@@ -0,0 +1,161 @@
+import { Box, Divider } from "@mui/material";
+import { useState, type JSX } from "react";
+
+import { CardView } from "./card-view";
+import { GooglePayButton } from "./google-pay-button";
+import { cardChain, cardTokenization, googlePayConfig } from "./method-capability";
+import type { ProviderCheckoutScreenProps } from "./providers/types";
+import { useCheckoutComponents } from "./ui";
+import { useWalletCharge, type WalletCharge } from "./use-wallet-charge";
+
+/**
+ * The CARD pane with its wallet fast lane (FUT-471/472).
+ *
+ * A wallet is not a fourth method — it is another way of producing the CARD
+ * instrument — so it renders INSIDE the card pane, above the form, and only
+ * when the chain head both declared the wallet capability and published the
+ * parameters the browser needs (`googlePayConfig`, fail-closed). A store with
+ * no wallet renders exactly the card view it always did.
+ *
+ * One pane owns BOTH submit paths' visibility so they cannot invite a double
+ * payment: while a wallet charge is in flight or being confirmed, the card
+ * form and every wallet button are REPLACED by the processing state — the same
+ * rule `card-view.tsx` applies to its own pay bar, one level up.
+ */
+
+/** Post-submit confirmation, error > timeout > spinner — the card view's order. */
+function WalletProcessing({ wallet }: { wallet: WalletCharge }): JSX.Element {
+  const { Alert, LoadingState } = useCheckoutComponents();
+  if (wallet.pollError) {
+    return (
+      <Alert
+        variant="danger"
+        title="Não foi possível confirmar o pagamento"
+        description={wallet.pollError}
+        showIcon
+        data-testid="wallet-poll-error"
+      />
+    );
+  }
+  if (wallet.pollTimedOut) {
+    return (
+      <Alert
+        variant="warning"
+        title="O pagamento está demorando mais que o esperado"
+        description="Você pode aguardar ou verificar seu pedido em instantes — não realize um novo pagamento."
+        showIcon
+        data-testid="wallet-poll-timeout"
+      />
+    );
+  }
+  return (
+    <LoadingState
+      variant="spinner"
+      size="md"
+      message="Processando pagamento…"
+      dataTestId="wallet-processing"
+    />
+  );
+}
+
+/**
+ * An UNRESOLVED wallet charge (FUT-563): some provider may be holding the
+ * buyer's money, so the pane shows the warning and NO pay control of any kind
+ * — no wallet button, no card form. Same presentation rule as the card view's
+ * own unresolved state.
+ */
+function WalletUnresolved({ message }: { message: string }): JSX.Element {
+  const { Alert } = useCheckoutComponents();
+  return (
+    <Alert
+      variant="warning"
+      title="Estamos confirmando seu pagamento"
+      description={message}
+      showIcon
+      data-testid="wallet-unresolved"
+    />
+  );
+}
+
+/**
+ * The wallet buttons the store's chain head supports, or null when there are
+ * none. Split out so the pane below stays under the function-size gate.
+ */
+function WalletButtons({
+  props,
+  wallet,
+  onSheetError,
+}: {
+  props: ProviderCheckoutScreenProps & { order: NonNullable<ProviderCheckoutScreenProps["order"]> };
+  wallet: WalletCharge;
+  onSheetError: (message: string) => void;
+}): JSX.Element | null {
+  const { Text } = useCheckoutComponents();
+  const googlePay = googlePayConfig(props.config);
+  if (!googlePay) return null;
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      <GooglePayButton
+        order={props.order}
+        params={googlePay}
+        onKey={(key) => void wallet.payWithKey("GOOGLE_PAY", key)}
+        onError={onSheetError}
+      />
+      <Divider>
+        <Text variant="caption" size="xs" color="secondary" as="span">
+          ou pague com cartão
+        </Text>
+      </Divider>
+    </Box>
+  );
+}
+
+/** The CARD pane: wallet fast lane above, the card form below. */
+export function WalletCardPane(
+  props: ProviderCheckoutScreenProps & {
+    order: NonNullable<ProviderCheckoutScreenProps["order"]>;
+  },
+): JSX.Element {
+  const { Alert } = useCheckoutComponents();
+  const { order, buyer, config, tenantSlug, onResolved, pollIntervalMs } = props;
+  const wallet = useWalletCharge(order, buyer, onResolved, pollIntervalMs);
+  // A sheet failure the wallet reported before any charge existed (pay.js
+  // refused, the sheet errored) — shown beside the form, which stays usable.
+  const [sheetError, setSheetError] = useState<string | null>(null);
+
+  if (wallet.phase !== "idle") return <WalletProcessing wallet={wallet} />;
+  if (wallet.unresolved) return <WalletUnresolved message={wallet.error ?? ""} />;
+
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <WalletButtons props={props} wallet={wallet} onSheetError={setSheetError} />
+      {wallet.error ? (
+        <Alert
+          variant="danger"
+          title="Não foi possível pagar"
+          description={wallet.error}
+          showIcon
+          data-testid="wallet-error"
+        />
+      ) : null}
+      {sheetError && !wallet.error ? (
+        <Alert
+          variant="danger"
+          title="Não foi possível pagar"
+          description={sheetError}
+          showIcon
+          data-testid="wallet-sheet-error"
+        />
+      ) : null}
+      <CardView
+        order={order}
+        buyer={buyer}
+        providerConfig={cardTokenization(config)}
+        providerChain={cardChain(config)}
+        tenantSlug={tenantSlug}
+        onResolved={onResolved}
+        pollIntervalMs={pollIntervalMs}
+      />
+    </Box>
+  );
+}

package/src/index.ts

@@ -84,6 +84,20 @@ export {
 export { type CheckoutHostPorts } from './components/checkout/use-checkout-controller';
 export { PaymentsUnavailable } from './components/checkout/payments-unavailable';
 export { fetchCheckoutConfig } from './components/checkout/client';
+// ---------------------------------------------------------------------------
+// Digital wallets (FUT-471/472) — the Google-branded button and the capability
+// read it is gated on. `CheckoutFlow` wires these automatically; they are
+// exported for hosts composing their own pixels.
+// ---------------------------------------------------------------------------
+export {
+  GooglePayButton,
+  type GooglePayApi,
+  type GooglePayButtonProps,
+  type GooglePaymentData,
+  type GooglePaymentsClient,
+  type GooglePayGatewayParams,
+} from './components/checkout/google-pay-button';
+export { googlePayConfig } from './components/checkout/method-capability';
 export {
   CheckoutComponentsProvider,
   type CheckoutActionBarProps,
@@ -103,11 +117,13 @@ export {
   type BuyerContact,
   type BuyerField,
   type BuyerInfo,
+  type ChargeWalletInput,
   type CheckoutChainLink,
   type CheckoutCustomerField,
   type CheckoutError,
   type CheckoutOrder,
   type CheckoutProviderConfig,
+  type CheckoutWalletType,
   type ComandaCheckout,
   type CreateOrderRequest,
   type CreateOrderResult,