@12-apps/payments-frontend 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.17.0",
+  "version": "1.19.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.22.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/client-context.tsx

@@ -26,7 +26,7 @@ import {
   pollOrderStatus,
   refreshCardPublicKey,
 } from "./client";
-import type { CheckoutClient } from "./transport";
+import { createCheckoutClient, type CheckoutClient } from "./transport";
 
 /** The unbound client: `/api/checkout` on the ambient `fetch`. */
 const DEFAULT_CLIENT: CheckoutClient = {
@@ -35,6 +35,11 @@ const DEFAULT_CLIENT: CheckoutClient = {
   charge: (input) => chargeCard(input),
   chargeWallet: (input) => chargeWallet(input),
   listInstruments: (tenantSlug) => listSavedCards(tenantSlug),
+  // The vault pair (FUT-183) has no `client.ts` free function to bind — it is
+  // newer than that module. Built lazily from the default transport instead,
+  // which is the same wire: `/api/checkout`, ambient `fetch` resolved per call.
+  beginVault: () => createCheckoutClient().beginVault(),
+  completeVault: (input) => createCheckoutClient().completeVault(input),
   refreshBrowserKey: (input) => refreshCardPublicKey(input),
 };
 

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/transport.ts

@@ -2,7 +2,7 @@
  * The checkout's HTTP transport, as a bound client (FUT-741).
  *
  * Everything `client.ts` used to do with a hard-coded prefix and the ambient
- * `fetch` now lives here behind {@link createCheckoutClient}, so the same five
+ * `fetch` now lives here behind {@link createCheckoutClient}, so the same
  * calls can be pointed at a different mount, carry a host's auth headers, or —
  * the reason this exists — be driven through an injected `fetch` that routes
  * straight into a real `createPaymentFlowsBE` mount. A story or a harness page
@@ -15,6 +15,8 @@
  * shipped contract in the same release that introduces the factory.
  */
 
+import type { BuyerVaultSession, VaultedCardDisplay } from "@12-apps/payments-backend";
+
 import type { SavedCard } from "../../card";
 import { err, ok, type Result } from "../../result";
 
@@ -26,6 +28,28 @@ import type {
   OrderStatus,
 } from "./types";
 
+/**
+ * The two buyer-vault answer shapes (FUT-478/FUT-183), imported as TYPES from
+ * the backend package rather than mirrored: `/cards/begin` and `/cards/complete`
+ * are new rows with no older-host degrade story to encode, so a mirror here
+ * would only be a copy that can drift from the wire it names. Re-exported for
+ * the same reason `PaymentEnvironment` is on the barrel — a host typing its
+ * own callback must not need a direct backend dependency.
+ */
+export type { BuyerVaultSession, VaultedCardDisplay };
+
+/**
+ * The browser's two legitimate contributions to `POST /cards/complete`: the
+ * session it confirmed, and — for a sessionless PUBLIC_KEY provider — the
+ * encrypted card blob. The ownership facts (`reference`, `customerRef`) are
+ * answered server-side by the host's vault port and are NOT here on purpose:
+ * a body naming them is ignored by the mount.
+ */
+export interface CompleteVaultInput {
+  sessionId?: string;
+  token?: string;
+}
+
 /**
  * The prefix every shipped buyer checkout posts to today. Exported so a host
  * (or a test) can state it rather than re-type it, and so a change to it is a
@@ -35,7 +59,10 @@ export const DEFAULT_CHECKOUT_BASE_URL = "/api/checkout";
 
 /** Where the `createPaymentFlowsBE` mount lives, and how to reach it. */
 export interface CheckoutTransport {
-  /** Prefix for `/config`, `/status`, `/charge`, `/cards`, `/refresh-key`. */
+  /**
+   * Prefix for `/config`, `/status`, `/charge`, `/cards`, `/cards/begin`,
+   * `/cards/complete`, `/refresh-key`.
+   */
   baseUrl?: string;
   /**
    * The `fetch` to call. Omitted ⇒ the ambient one, resolved PER CALL so a
@@ -46,7 +73,7 @@ export interface CheckoutTransport {
   headers?: () => HeadersInit | Promise<HeadersInit>;
 }
 
-/** The six calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
+/** The eight 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>>;
@@ -54,6 +81,18 @@ export interface CheckoutClient {
   /** A wallet instrument against the same `/charge` route (FUT-471/472). */
   chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>>;
   listInstruments(tenantSlug?: string): Promise<SavedCard[]>;
+  /**
+   * `POST /cards/begin` (FUT-478): equip the browser to mint an instrument
+   * OUTSIDE a purchase. The answer names the tokenization scheme, the public
+   * key when the provider has one, and the session to echo to `completeVault`.
+   */
+  beginVault(): Promise<Result<BuyerVaultSession>>;
+  /**
+   * `POST /cards/complete`: the provider accepted the card — the server stores
+   * the vault token against the caller and answers DISPLAY metadata only. The
+   * token that can charge never reaches the browser.
+   */
+  completeVault(input: CompleteVaultInput): Promise<Result<VaultedCardDisplay>>;
   refreshBrowserKey(input: { orderId: string }): Promise<Result<{ publicKey: string | null }>>;
 }
 
@@ -146,7 +185,20 @@ function flatWalletBody(input: ChargeWalletInput): string {
 }
 
 /**
- * The five checkout calls, bound to one transport.
+ * The wire body of `POST /cards/complete` — ONLY the browser's two facts, and
+ * each present only when it exists. `flows-vault.ts` reads exactly these two
+ * string fields (`browserVaultFacts`) and ignores everything else, so a field
+ * added here without a backend reader would be silently dropped.
+ */
+function completeVaultBody(input: CompleteVaultInput): string {
+  return JSON.stringify({
+    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+    ...(input.token ? { token: input.token } : {}),
+  });
+}
+
+/**
+ * The checkout calls, bound to one transport.
  *
  * Passing no transport reproduces exactly what the free functions in
  * `client.ts` have always done: `/api/checkout/**` on the ambient `fetch`.
@@ -203,6 +255,14 @@ export function createCheckoutClient(transport: CheckoutTransport = {}): Checkou
       return result.ok ? result.data : [];
     },
 
+    beginVault: () => call<BuyerVaultSession>("/cards/begin", { method: "POST" }),
+
+    completeVault: (input) =>
+      call<VaultedCardDisplay>("/cards/complete", {
+        method: "POST",
+        body: completeVaultBody(input),
+      }),
+
     refreshBrowserKey: (input) =>
       call<{ publicKey: string | null }>("/refresh-key", {
         method: "POST",

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 {