@12-apps/payments-frontend 1.17.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.17.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.17.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.19.0",
-    "@12-apps/typescript-config": "^1.19.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/google-pay-button.tsx

@@ -196,6 +196,11 @@ export interface GooglePayButtonProps {
   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;
 }
 
 /**
@@ -211,13 +216,18 @@ export function GooglePayButton({
   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 });
-  current.current = { order, params, onKey, onError };
+  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;

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

@@ -167,6 +167,24 @@ export function googlePayConfig(
   return { gateway: params.gateway, gatewayMerchantId: params.gatewayMerchantId };
 }
 
+/**
+ * Whether the chain head declares Apple Pay (FUT-472) — the capability half
+ * of the button's gate; the DEVICE half (`ApplePaySession` exists and can
+ * pay) is `applePaySupported()` in `apple-pay-button.tsx`, because it is a
+ * browser fact, not a store fact.
+ *
+ * FAILS CLOSED like {@link googlePayConfig}, and read off the HEAD for the
+ * same reason: the Apple token is decrypted with the head merchant's
+ * certificate, so only the provider the walk tries first can charge it.
+ * Unlike Google there are no client parameters to publish — merchant
+ * validation runs server-side through the host's port.
+ */
+export function applePayDeclared(config: CheckoutProviderConfig | null): boolean {
+  const head = config?.chain?.[0];
+  if (!head?.methods.includes("CARD")) return false;
+  return head.wallets?.includes("APPLE_PAY") ?? false;
+}
+
 /**
  * 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/types.ts

@@ -52,6 +52,14 @@ export interface ProviderCheckoutScreenProps {
   tenantSlug?: string;
   /** The shell's polling cadence, passed through so tests can shorten it. */
   pollIntervalMs?: number;
+  /**
+   * The host's Apple Pay merchant-validation port (FUT-472): exchange the
+   * session's `validationURL` for an Apple merchant session, SERVER-SIDE —
+   * the merchant identity certificate must never reach a browser. Optional;
+   * absent, the Apple Pay sheet cannot start and the pane says so while the
+   * card form stays the way to pay.
+   */
+  validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** A terminal status — the shell moves to Confirmação. */
   onResolved: (status: OrderStatus) => void;
 }

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

@@ -39,8 +39,13 @@ export interface WalletCharge {
   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>;
+  /**
+   * Charge the wallet's key. The button calls this once the sheet resolves.
+   * Resolves `true` when the charge was ACCEPTED — paid, confirming, or
+   * handed to the provider's page — and `false` on a refusal or decline, so a
+   * sheet that must be completed with a status (Apple's) can be honest.
+   */
+  payWithKey(type: CheckoutWalletType, key: string): Promise<boolean>;
 }
 
 /**
@@ -72,7 +77,7 @@ export function useWalletCharge(
     if (status && status !== "AWAITING_PAYMENT") onResolved(status);
   }, [status, onResolved]);
 
-  const payWithKey = async (type: CheckoutWalletType, key: string): Promise<void> => {
+  const payWithKey = async (type: CheckoutWalletType, key: string): Promise<boolean> => {
     setError(null);
     setErrorCode(null);
     setPhase("charging");
@@ -92,7 +97,7 @@ export function useWalletCharge(
       // holding the money, and a live button under "não pague de novo" is what
       // the buyer's thumb reaches for.
       setPhase("idle");
-      return;
+      return false;
     }
     // 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
@@ -100,15 +105,16 @@ export function useWalletCharge(
     if (charged.data.hostedCheckoutUrl) {
       rememberHostedOrder(order);
       navigate(charged.data.hostedCheckoutUrl);
-      return;
+      return true;
     }
     // 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;
+      return charged.data.status === "PAID";
     }
     setPhase("polling");
+    return true;
   };
 
   return {

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

@@ -1,9 +1,15 @@
 import { Box, Divider } from "@mui/material";
 import { useState, type JSX } from "react";
 
+import { ApplePayButton, applePaySupported } from "./apple-pay-button";
 import { CardView } from "./card-view";
 import { GooglePayButton } from "./google-pay-button";
-import { cardChain, cardTokenization, googlePayConfig } from "./method-capability";
+import {
+  applePayDeclared,
+  cardChain,
+  cardTokenization,
+  googlePayConfig,
+} from "./method-capability";
 import type { ProviderCheckoutScreenProps } from "./providers/types";
 import { useCheckoutComponents } from "./ui";
 import { useWalletCharge, type WalletCharge } from "./use-wallet-charge";
@@ -13,9 +19,9 @@ import { useWalletCharge, type WalletCharge } from "./use-wallet-charge";
  *
  * 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.
+ * when the chain head declared the wallet capability (both gates fail closed:
+ * `googlePayConfig` / `applePayDeclared` + the device's own support). 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
@@ -23,6 +29,11 @@ import { useWalletCharge, type WalletCharge } from "./use-wallet-charge";
  * rule `card-view.tsx` applies to its own pay bar, one level up.
  */
 
+/** The screen props narrowed to a raised order — what this pane requires. */
+type WalletPaneProps = ProviderCheckoutScreenProps & {
+  order: NonNullable<ProviderCheckoutScreenProps["order"]>;
+};
+
 /** Post-submit confirmation, error > timeout > spinner — the card view's order. */
 function WalletProcessing({ wallet }: { wallet: WalletCharge }): JSX.Element {
   const { Alert, LoadingState } = useCheckoutComponents();
@@ -79,48 +90,63 @@ function WalletUnresolved({ message }: { message: string }): JSX.Element {
 
 /**
  * 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.
+ * none to offer. The divider renders only once SOMETHING sits above it: Apple
+ * availability is known synchronously (feature-detect), Google's arrives when
+ * `isReadyToPay` approves (`onReady`) — a bare "ou pague com cartão" with
+ * nothing above it would caption an empty space.
  */
 function WalletButtons({
   props,
   wallet,
   onSheetError,
 }: {
-  props: ProviderCheckoutScreenProps & { order: NonNullable<ProviderCheckoutScreenProps["order"]> };
+  props: WalletPaneProps;
   wallet: WalletCharge;
   onSheetError: (message: string) => void;
 }): JSX.Element | null {
   const { Text } = useCheckoutComponents();
+  const [googleReady, setGoogleReady] = useState(false);
   const googlePay = googlePayConfig(props.config);
-  if (!googlePay) return null;
+  const applePay = applePayDeclared(props.config) && applePaySupported();
+  if (!googlePay && !applePay) 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>
+      {applePay ? (
+        <ApplePayButton
+          order={props.order}
+          onAuthorized={(key) => wallet.payWithKey("APPLE_PAY", key)}
+          onError={onSheetError}
+          validateMerchant={props.validateApplePayMerchant}
+        />
+      ) : null}
+      {googlePay ? (
+        <GooglePayButton
+          order={props.order}
+          params={googlePay}
+          onKey={(key) => void wallet.payWithKey("GOOGLE_PAY", key)}
+          onError={onSheetError}
+          onReady={() => setGoogleReady(true)}
+        />
+      ) : null}
+      {applePay || googleReady ? (
+        <Divider>
+          <Text variant="caption" size="xs" color="secondary" as="span">
+            ou pague com cartão
+          </Text>
+        </Divider>
+      ) : null}
     </Box>
   );
 }
 
 /** The CARD pane: wallet fast lane above, the card form below. */
-export function WalletCardPane(
-  props: ProviderCheckoutScreenProps & {
-    order: NonNullable<ProviderCheckoutScreenProps["order"]>;
-  },
-): JSX.Element {
+export function WalletCardPane(props: WalletPaneProps): 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.
+  // refused, merchant validation unavailable, 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} />;

package/src/components/platform/ConnectApplicationPanel.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import { Box, Button, Stack, Typography } from '@mui/material';
+import type { ReactNode } from 'react';
+
+import type { ConnectApplicationReport, PaymentEnvironment } from '@12-apps/payments-backend';
+
+import { CARD_SX, ConnectEnvironmentCard } from './ConnectEnvironmentCard';
+
+/**
+ * The platform's PagBank Connect application, per environment (FUT-479,
+ * packaged by FUT-573).
+ *
+ * The application every store authorizes against is registered by hand, so
+ * nothing in the product could say what is registered, in which environment,
+ * or with which redirect URI. This panel is the consult
+ * (`GET /oauth2/application/{client_id}`) made permanent: per environment —
+ * sandbox and produção are separate applications — it shows what PagBank has
+ * on file, including the exact redirect_uri, and flags a mismatch against the
+ * callback the deployment actually uses (a mismatch is a silent OAuth
+ * failure). Read-only: creating an application stays a deliberate manual act.
+ *
+ * Dumb by design: the HOST fetches the report from its own mounted route
+ * (`consultConnectApplications` in `@12-apps/payments-backend`) and passes it
+ * here, so the host page is a thin mount — page chrome, auth and loading
+ * belong to the host; the screen itself lives in this package.
+ */
+export interface ConnectApplicationPanelProps {
+  /** The consult report, as the backend's `consultConnectApplications` answers. */
+  report: ConnectApplicationReport;
+  /** Re-run the consult. Omitted, the refresh button is not rendered. */
+  onRefresh?: () => void;
+  /**
+   * Which host-side variables feed one environment's application — the host's
+   * own configuration surface, rendered as a collapsible per-environment help
+   * when provided.
+   */
+  configVarsFor?: (environment: PaymentEnvironment) => string[];
+}
+
+export function ConnectApplicationPanel(props: ConnectApplicationPanelProps): ReactNode {
+  const { report, onRefresh, configVarsFor } = props;
+  return (
+    <Stack spacing={2} data-testid="connect-application-panel">
+      <Stack spacing={0.5} data-testid="connect-expected-redirect" sx={CARD_SX}>
+        <Typography variant="caption" color="text.secondary" fontWeight={600}>
+          Callback desta instalação (o valor que precisa estar registrado)
+        </Typography>
+        <Box
+          component="code"
+          sx={{ fontFamily: 'monospace', fontSize: 13, wordBreak: 'break-all' }}
+        >
+          {report.expectedRedirectUri}
+        </Box>
+      </Stack>
+      {report.environments.map((status) => (
+        <ConnectEnvironmentCard
+          key={status.environment}
+          status={status}
+          configVars={configVarsFor?.(status.environment)}
+        />
+      ))}
+      {onRefresh ? (
+        <Box>
+          <Button
+            variant="outlined"
+            size="small"
+            onClick={() => onRefresh()}
+            data-testid="connect-refresh"
+          >
+            Consultar novamente
+          </Button>
+        </Box>
+      ) : null}
+    </Stack>
+  );
+}

package/src/components/platform/ConnectEnvironmentCard.tsx

@@ -0,0 +1,175 @@
+'use client';
+
+import { Alert, Box, Button, Stack, Typography } from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import type { ConnectApplicationStatus, PaymentEnvironment } from '@12-apps/payments-backend';
+
+/**
+ * One environment's Connect application (FUT-479, packaged by FUT-573).
+ * Sandbox and produção are SEPARATE applications with separate id/secret
+ * pairs, so each card stands on its own: configured or not, what PagBank says
+ * is registered, and whether the registered redirect URI matches the
+ * deployment's callback.
+ */
+
+const ENV_LABEL: Record<PaymentEnvironment, string> = {
+  SANDBOX: 'Sandbox',
+  PRODUCTION: 'Produção',
+};
+
+/** The bordered-card look every block of these screens shares. */
+export const CARD_SX = {
+  border: 1,
+  borderColor: 'divider',
+  borderRadius: 2,
+  p: 2,
+} as const;
+
+function Field({ label, children }: { label: string; children: ReactNode }): ReactNode {
+  return (
+    <Box
+      sx={{ display: 'flex', flexDirection: 'column', gap: 0.25, minWidth: 180, wordBreak: 'break-all' }}
+    >
+      <Typography variant="caption" color="text.secondary" fontWeight={600}>
+        {label}
+      </Typography>
+      <Typography component="span" variant="body2">
+        {children}
+      </Typography>
+    </Box>
+  );
+}
+
+/** The verdict the screen exists for: does the registered callback match ours? */
+function MismatchAlert({ status }: { status: ConnectApplicationStatus }): ReactNode {
+  if (status.application === null) return null;
+  if (status.redirectUriMismatch === true) {
+    return (
+      <Alert severity="error" data-testid={`connect-mismatch-${status.environment}`}>
+        A redirect_uri registrada no PagBank é diferente do callback desta instalação. O fluxo
+        de autorização OAuth falha silenciosamente até o cadastro ser corrigido no PagBank.
+      </Alert>
+    );
+  }
+  if (status.redirectUriMismatch === false) {
+    return (
+      <Alert severity="success" data-testid={`connect-match-${status.environment}`}>
+        A redirect_uri registrada confere com o callback desta instalação.
+      </Alert>
+    );
+  }
+  return (
+    <Alert severity="warning" data-testid={`connect-unknown-${status.environment}`}>
+      A resposta do PagBank não informou a redirect_uri — não foi possível comparar com o
+      callback desta instalação.
+    </Alert>
+  );
+}
+
+/** What PagBank reports as registered, plus whatever extra keys came back. */
+function ApplicationFields({ status }: { status: ConnectApplicationStatus }): ReactNode {
+  const app = status.application;
+  if (app === null) return null;
+  const extraKeys = Object.keys(app.extra);
+  return (
+    <Stack spacing={1.5}>
+      <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 2.5 }}>
+        <Field label="Nome (exibido ao lojista)">{app.name ?? '—'}</Field>
+        <Field label="Site">{app.site ?? '—'}</Field>
+        <Field label="Descrição">{app.description ?? '—'}</Field>
+        <Field label="Logo">{app.logo ?? '—'}</Field>
+        <Field label="redirect_uri registrada">{app.redirectUri ?? 'não informada'}</Field>
+      </Box>
+      {extraKeys.length > 0 ? (
+        <Box data-testid={`connect-extra-${status.environment}`}>
+          <Typography variant="caption" color="text.secondary" fontWeight={600}>
+            Outros campos retornados (schema não documentado)
+          </Typography>
+          <Box component="pre" sx={{ m: 0, fontSize: 12, overflowX: 'auto' }}>
+            {JSON.stringify(app.extra, null, 2)}
+          </Box>
+        </Box>
+      ) : null}
+    </Stack>
+  );
+}
+
+/**
+ * The collapsible "what feeds this environment" help. The variable names are
+ * the HOST's own configuration surface, so they arrive via `configVars`; with
+ * none provided the toggle is omitted entirely rather than opening on nothing.
+ */
+function ConfigHelp({
+  environment,
+  configVars,
+}: {
+  environment: PaymentEnvironment;
+  configVars?: string[];
+}): ReactNode {
+  const [open, setOpen] = useState(false);
+  if (!configVars || configVars.length === 0) return null;
+  return (
+    <Stack spacing={1} alignItems="flex-start">
+      <Button
+        variant="outlined"
+        size="small"
+        onClick={() => setOpen((value) => !value)}
+        data-testid={`connect-config-toggle-${environment}`}
+      >
+        {open ? 'Ocultar variáveis de ambiente' : 'Ver variáveis de ambiente'}
+      </Button>
+      {open ? (
+        <Box data-testid={`connect-config-details-${environment}`}>
+          <Typography variant="caption" color="text.secondary" component="p">
+            A aplicação deste ambiente é resolvida estritamente por estas variáveis (sem
+            fallback entre ambientes):
+          </Typography>
+          <Box component="ul" sx={{ m: 0, pl: 2.5 }}>
+            {configVars.map((name) => (
+              <Box component="li" key={name}>
+                <Box component="code" sx={{ fontFamily: 'monospace', fontSize: 12 }}>
+                  {name}
+                </Box>
+              </Box>
+            ))}
+          </Box>
+        </Box>
+      ) : null}
+    </Stack>
+  );
+}
+
+export function ConnectEnvironmentCard({
+  status,
+  configVars,
+}: {
+  status: ConnectApplicationStatus;
+  configVars?: string[];
+}): ReactNode {
+  return (
+    <Stack spacing={1.5} data-testid={`connect-env-${status.environment}`} sx={CARD_SX}>
+      <Box sx={{ display: 'flex', alignItems: 'baseline', gap: 1.5, wordBreak: 'break-all' }}>
+        <Typography variant="body2" fontWeight={600}>
+          {ENV_LABEL[status.environment]}
+        </Typography>
+        <Typography component="span" variant="caption" color="text.secondary">
+          {status.clientId !== null ? `client_id: ${status.clientId}` : ''}
+        </Typography>
+      </Box>
+      {!status.configured ? (
+        <Typography variant="body2" color="text.secondary">
+          Nenhuma aplicação configurada neste ambiente.
+        </Typography>
+      ) : null}
+      {status.error !== null ? (
+        <Alert severity="warning" data-testid={`connect-error-${status.environment}`}>
+          {status.error}
+        </Alert>
+      ) : null}
+      <MismatchAlert status={status} />
+      <ApplicationFields status={status} />
+      <ConfigHelp environment={status.environment} configVars={configVars} />
+    </Stack>
+  );
+}

package/src/components/platform/HomologacaoGuideCard.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { Box, Link, Stack, Typography } from '@mui/material';
+import type { ReactNode } from 'react';
+
+import type { HomologacaoGuide } from '@12-apps/payments-backend';
+
+import { CARD_SX } from './ConnectEnvironmentCard';
+
+/**
+ * The paste-ready homologação answers (FUT-483, packaged by FUT-573) — the
+ * Pipefy form with every deployment-specific value already computed, and the
+ * services list naming BOTH Order and Connect.
+ */
+
+/** One paste-ready value, in a copyable code block. */
+function Answer({ label, children }: { label: string; children: ReactNode }): ReactNode {
+  return (
+    <Stack spacing={0.25}>
+      <Typography variant="caption" color="text.secondary" fontWeight={600}>
+        {label}
+      </Typography>
+      <Box
+        component="code"
+        sx={{
+          fontFamily: 'monospace',
+          fontSize: 12,
+          p: 1,
+          borderRadius: 1,
+          bgcolor: 'action.hover',
+          wordBreak: 'break-word',
+          whiteSpace: 'pre-wrap',
+        }}
+      >
+        {children}
+      </Box>
+    </Stack>
+  );
+}
+
+export function HomologacaoGuideCard({ guide }: { guide: HomologacaoGuide }): ReactNode {
+  return (
+    <Stack spacing={1.5} data-testid="homologacao-guide-card" sx={CARD_SX}>
+      <Typography variant="body2" fontWeight={600}>
+        Formulário de homologação — respostas prontas
+      </Typography>
+      <Typography variant="body2" color="text.secondary" component="p">
+        Abra o{' '}
+        <Link
+          href={guide.formUrl}
+          target="_blank"
+          rel="noreferrer"
+          data-testid="homologacao-form-link"
+        >
+          formulário oficial de homologação
+        </Link>{' '}
+        e preencha com os valores abaixo. Em paralelo, abra um chamado no{' '}
+        <Link href={guide.supportFormUrl} target="_blank" rel="noreferrer">
+          SIP — Suporte Integração PagBank
+        </Link>{' '}
+        citando o 403 ACCESS_DENIED — o que responder primeiro resolve a dúvida de o
+        formulário cobrir ou não o Connect. Documentação:{' '}
+        <Link href={guide.docsUrl} target="_blank" rel="noreferrer">
+          solicitar homologação
+        </Link>
+        .
+      </Typography>
+      <Answer label="Selecione o tipo de integração">{guide.integrationType}</Answer>
+      <Box data-testid="homologacao-services">
+        <Answer label="Selecione qual serviço você integrou (marque OS DOIS)">
+          {guide.services.join('\n')}
+        </Answer>
+      </Box>
+      <Answer label="Instruções de acesso ao seu ambiente (limite de 255 caracteres)">
+        {guide.accessInstructions}
+      </Answer>
+      <Answer label="URL do site">{guide.siteUrl}</Answer>
+      <Answer label="Detalhe quais produtos/serviços serão comercializados">
+        {guide.productsDescription}
+      </Answer>
+      <Typography variant="caption" color="text.secondary" component="p">
+        {guide.slaText}
+      </Typography>
+    </Stack>
+  );
+}

package/src/components/platform/HomologacaoOutcomeCard.tsx

@@ -0,0 +1,170 @@
+'use client';
+
+import { Alert, Box, Button, Chip, Stack, TextField, Typography } from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import type { PlatformHomologationStatus } from '@12-apps/payments-backend';
+
+import { CARD_SX } from './ConnectEnvironmentCard';
+
+/**
+ * The homologação outcome record (FUT-483, packaged by FUT-573) — the durable
+ * answer to "is the platform homologated?". Absence of the record is the
+ * honest fourth state ("não solicitada"), which is why it is displayed but
+ * never offered as a choice.
+ */
+
+/**
+ * One provider's recorded outcome as the wire carries it — the backend's
+ * `PlatformHomologationRecord` after JSON serialization (dates as ISO
+ * strings).
+ */
+export interface PlatformHomologationRecordView {
+  provider: string;
+  status: PlatformHomologationStatus;
+  protocol: string | null;
+  notes: string | null;
+  submittedAt: string | null;
+  decidedAt: string | null;
+  updatedBy: string | null;
+  updatedAt: string;
+}
+
+/** What the outcome form submits — the whole record, replaced deliberately. */
+export interface HomologacaoSaveInput {
+  status: PlatformHomologationStatus;
+  protocol: string;
+  notes: string;
+}
+
+/** The host's save-mutation state, whatever machinery produces it. */
+export interface HomologacaoSaveState {
+  pending: boolean;
+  error: string | null;
+  success: boolean;
+}
+
+const STATUS_LABEL: Record<PlatformHomologationStatus, string> = {
+  SUBMITTED: 'Solicitada',
+  APPROVED: 'Aprovada',
+  REJECTED: 'Recusada',
+};
+
+const STATUS_COLOR: Record<PlatformHomologationStatus, 'warning' | 'success' | 'error'> = {
+  SUBMITTED: 'warning',
+  APPROVED: 'success',
+  REJECTED: 'error',
+};
+
+function StatusChip({ record }: { record: PlatformHomologationRecordView | null }): ReactNode {
+  if (record === null) {
+    return (
+      <Chip
+        label="Não solicitada"
+        size="small"
+        variant="outlined"
+        data-testid="homologacao-status-chip"
+      />
+    );
+  }
+  return (
+    <Chip
+      label={STATUS_LABEL[record.status]}
+      size="small"
+      color={STATUS_COLOR[record.status]}
+      data-testid="homologacao-status-chip"
+    />
+  );
+}
+
+const formatDateTime = (iso: string): string => new Date(iso).toLocaleString('pt-BR');
+
+function RecordTrail({ record }: { record: PlatformHomologationRecordView }): ReactNode {
+  return (
+    <Typography variant="caption" color="text.secondary" component="p">
+      {record.submittedAt ? `Solicitada em ${formatDateTime(record.submittedAt)}. ` : ''}
+      {record.decidedAt ? `Decidida em ${formatDateTime(record.decidedAt)}. ` : ''}
+      {record.updatedBy ? `Registrado por ${record.updatedBy}.` : ''}
+    </Typography>
+  );
+}
+
+interface HomologacaoOutcomeCardProps {
+  record: PlatformHomologationRecordView | null;
+  /** Record the outcome — the host PUTs it and refreshes `record`. */
+  onSave: (input: HomologacaoSaveInput) => void;
+  save: HomologacaoSaveState;
+}
+
+export function HomologacaoOutcomeCard(props: HomologacaoOutcomeCardProps): ReactNode {
+  const { record, onSave, save } = props;
+  const [status, setStatus] = useState<PlatformHomologationStatus>(record?.status ?? 'SUBMITTED');
+  const [protocol, setProtocol] = useState(record?.protocol ?? '');
+  const [notes, setNotes] = useState(record?.notes ?? '');
+
+  return (
+    <Stack spacing={1.5} data-testid="homologacao-outcome-card" sx={CARD_SX}>
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 1.5 }}>
+        <Typography variant="body2" fontWeight={600}>
+          Situação da homologação
+        </Typography>
+        <StatusChip record={record} />
+      </Box>
+      {record ? <RecordTrail record={record} /> : null}
+      <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 1.5, alignItems: 'flex-start' }}>
+        <TextField
+          select
+          size="small"
+          label="Situação"
+          value={status}
+          onChange={(event) => setStatus(event.target.value as PlatformHomologationStatus)}
+          slotProps={{
+            select: { native: true },
+            htmlInput: { 'data-testid': 'homologacao-status-select' },
+          }}
+        >
+          {(Object.keys(STATUS_LABEL) as PlatformHomologationStatus[]).map((key) => (
+            <option key={key} value={key}>
+              {STATUS_LABEL[key]}
+            </option>
+          ))}
+        </TextField>
+        <TextField
+          size="small"
+          aria-label="Protocolo"
+          placeholder="Protocolo (cartão do Pipefy / chamado)"
+          value={protocol}
+          onChange={(event) => setProtocol(event.target.value)}
+          slotProps={{ htmlInput: { 'data-testid': 'homologacao-protocol' } }}
+        />
+        <TextField
+          size="small"
+          aria-label="Observações"
+          placeholder="Observações (resposta do PagBank, contexto…)"
+          value={notes}
+          onChange={(event) => setNotes(event.target.value)}
+          slotProps={{ htmlInput: { 'data-testid': 'homologacao-notes' } }}
+        />
+        <Button
+          variant="contained"
+          size="small"
+          disabled={save.pending}
+          onClick={() => onSave({ status, protocol, notes })}
+          data-testid="homologacao-save"
+        >
+          Registrar
+        </Button>
+      </Box>
+      {save.error !== null ? (
+        <Alert severity="error" data-testid="homologacao-save-error">
+          {save.error}
+        </Alert>
+      ) : null}
+      {save.success ? (
+        <Alert severity="success" data-testid="homologacao-save-ok">
+          Registro atualizado.
+        </Alert>
+      ) : null}
+    </Stack>
+  );
+}

package/src/components/platform/PlatformHomologacao.tsx

@@ -0,0 +1,107 @@
+'use client';
+
+import { Alert, Box, Button, Stack, Typography } from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import type { HomologacaoGuide } from '@12-apps/payments-backend';
+
+import { CARD_SX } from './ConnectEnvironmentCard';
+import { HomologacaoGuideCard } from './HomologacaoGuideCard';
+import {
+  HomologacaoOutcomeCard,
+  type HomologacaoSaveInput,
+  type HomologacaoSaveState,
+  type PlatformHomologationRecordView,
+} from './HomologacaoOutcomeCard';
+
+/**
+ * The PLATFORM's PagBank homologação screen (FUT-483, packaged by FUT-573).
+ *
+ * The platform is the direct integrator, so the homologação is the
+ * platform's, once — store owners are platform users and are exempt. The
+ * screen carries the three halves: the recorded outcome (so "is the platform
+ * homologated?" stops being a question for a person), the Pipefy form with
+ * paste-ready answers (BOTH services — Order and Connect), and the evidence
+ * generator running on the platform's own sandbox credentials.
+ *
+ * Dumb by design: data and mutations arrive via props from the host's own
+ * mounted routes (`platformHomologacaoGuide`, `createHomologationRecordService`
+ * and `buildPlatformHomologacaoAnexo` in `@12-apps/payments-backend`), so the
+ * host page is a thin mount.
+ */
+export interface PlatformHomologacaoProps {
+  /** The recorded outcome; null renders the honest "não solicitada". */
+  record: PlatformHomologationRecordView | null;
+  /** The paste-ready answers, computed by the host's backend. */
+  guide: HomologacaoGuide;
+  /** Record the outcome — the host PUTs it and refreshes `record`. */
+  onSaveRecord: (input: HomologacaoSaveInput) => void;
+  /** The host's save-mutation state. */
+  save: HomologacaoSaveState;
+  /**
+   * Generate AND deliver the evidence file (the host downloads what its anexo
+   * route answers). Reject with an Error whose message names the reason —
+   * e.g. the missing platform sandbox token and where to fix it — and the
+   * card shows it verbatim.
+   */
+  onGenerateAnexo: () => Promise<void>;
+}
+
+/** The evidence-file half: real sandbox calls, downloaded as a text file. */
+function AnexoCard({ onGenerate }: { onGenerate: () => Promise<void> }): ReactNode {
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  const generate = async (): Promise<void> => {
+    setBusy(true);
+    setError(null);
+    try {
+      await onGenerate();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : 'Não foi possível gerar o anexo.');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Stack spacing={1.5} data-testid="homologacao-anexo-card" sx={CARD_SX}>
+      <Typography variant="body2" fontWeight={600}>
+        Anexo de evidências
+      </Typography>
+      <Typography variant="body2" color="text.secondary" component="p">
+        O formulário exige os requests e responses das requisições enviadas às APIs do
+        PagBank. O botão abaixo faz as chamadas reais no ambiente de testes (Sandbox) com o
+        token da própria plataforma — nada é cobrado de verdade — e baixa o arquivo pronto
+        para anexar, com o token redigido.
+      </Typography>
+      <Box>
+        <Button
+          variant="outlined"
+          size="small"
+          disabled={busy}
+          onClick={() => void generate()}
+          data-testid="homologacao-anexo-button"
+        >
+          Gerar anexo
+        </Button>
+      </Box>
+      {error !== null ? (
+        <Alert severity="error" data-testid="homologacao-anexo-error">
+          {error}
+        </Alert>
+      ) : null}
+    </Stack>
+  );
+}
+
+export function PlatformHomologacao(props: PlatformHomologacaoProps): ReactNode {
+  const { record, guide, onSaveRecord, save, onGenerateAnexo } = props;
+  return (
+    <Stack spacing={2} data-testid="platform-homologacao">
+      <HomologacaoOutcomeCard record={record} onSave={onSaveRecord} save={save} />
+      <HomologacaoGuideCard guide={guide} />
+      <AnexoCard onGenerate={onGenerateAnexo} />
+    </Stack>
+  );
+}

package/src/flows/create-payment-flows.tsx

@@ -96,6 +96,7 @@ function buildCheckout(
         providerConfig={config}
         tenantSlug={tenantSlug}
         confirmationExtra={runtime.config.confirmation?.extra}
+        validateApplePayMerchant={ports.validateApplePayMerchant}
       />
     );
   }

package/src/flows/types.ts

@@ -74,6 +74,13 @@ export interface CheckoutPorts {
    * some hosts must log or confirm the departure.
    */
   navigate?(url: string): void;
+  /**
+   * Apple Pay merchant validation (FUT-472): exchange the session's
+   * `validationURL` for an Apple merchant session, SERVER-SIDE — the merchant
+   * identity certificate must never reach a browser. Optional; without it the
+   * Apple Pay sheet cannot start and the card form remains the way to pay.
+   */
+  validateApplePayMerchant?(validationURL: string): Promise<unknown>;
   /** The remedy shown on the no-provider screen, AND the host's veto. */
   useAvailability?(): CheckoutAvailability;
 }

package/src/index.ts

@@ -97,7 +97,16 @@ export {
   type GooglePaymentsClient,
   type GooglePayGatewayParams,
 } from './components/checkout/google-pay-button';
-export { googlePayConfig } from './components/checkout/method-capability';
+export {
+  ApplePayButton,
+  applePaySupported,
+  APPLE_PAY_SUPPORTED_NETWORKS,
+  type ApplePayButtonProps,
+  type ApplePayPaymentRequest,
+  type ApplePaySessionClass,
+  type ApplePaySessionLike,
+} from './components/checkout/apple-pay-button';
+export { applePayDeclared, googlePayConfig } from './components/checkout/method-capability';
 export {
   CheckoutComponentsProvider,
   type CheckoutActionBarProps,
@@ -185,6 +194,28 @@ export {
   type PaymentProviderSettingsProps,
 } from './components/PaymentProviderSettings';
 
+// ---------------------------------------------------------------------------
+// The PLATFORM operations screens (FUT-479 / FUT-483, packaged by FUT-573) —
+// the Connect-application consult and the homologação, as dumb components a
+// host page mounts with data + callbacks from its own routes. Their backend
+// halves live in `@12-apps/payments-backend` (`consultConnectApplications`,
+// `platformHomologacaoGuide`, `createHomologationRecordService`,
+// `buildPlatformHomologacaoAnexo`).
+// ---------------------------------------------------------------------------
+export {
+  ConnectApplicationPanel,
+  type ConnectApplicationPanelProps,
+} from './components/platform/ConnectApplicationPanel';
+export {
+  PlatformHomologacao,
+  type PlatformHomologacaoProps,
+} from './components/platform/PlatformHomologacao';
+export {
+  type HomologacaoSaveInput,
+  type HomologacaoSaveState,
+  type PlatformHomologationRecordView,
+} from './components/platform/HomologacaoOutcomeCard';
+
 /**
  * Re-exported because it appears in the `prepareConnect` prop a host must
  * implement: without it the host could not type its own callback without