@12-apps/payments-frontend 1.3.0 → 1.4.0

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

@@ -12,19 +12,37 @@ import { tokenizerFor, type CardTokenizationConfig } from "../../card";
 import type { CheckoutProviderConfig, PaymentMethod } from "./types";
 
 /**
- * Whether the ACTIVE provider gives this browser a card path (FUT-697):
- * a scheme {@link tokenizerFor} knows, with a key (or PagBank's on-demand
- * refresh); a hosted page (`REDIRECT` — the provider's own site takes the
- * card); or server-granted stub mode. `null` config (still loading / fetch
- * blip) fails OPEN for the UI — the tokenizer itself still fails CLOSED.
+ * Whether the store's CHAIN gives this browser a card path (FUT-697/563).
+ *
+ * Asked of the whole chain, for the same reason the server's
+ * `usesHostedCheckout` is: the head no longer decides which surface the buyer
+ * gets. A store where nobody tokenizes in the browser hands the buyer over at
+ * order creation and the card is typed on the provider's own page — a card
+ * path, so CARD stays offered. A store where somebody DOES tokenize gets our
+ * form instead, and then the question is whether this browser can actually
+ * mint for one of those entries: a scheme {@link tokenizerFor} knows, with a
+ * key (or PagBank's on-demand refresh), or server-granted stub mode.
+ *
+ * Answering "yes, it is REDIRECT" off the head alone is what let the picker
+ * offer a card the submit could never tokenize.
+ *
+ * `null` config (still loading / fetch blip) fails OPEN for the UI — the
+ * tokenizer itself still fails CLOSED.
  */
 export function cardPathAvailable(config: CheckoutProviderConfig | null): boolean {
   if (!config) return true;
-  if (config.mockTokenization) return true;
-  if (config.tokenization === "REDIRECT") return true;
-  const scheme = config.provider ? tokenizerFor(config.provider) : null;
+  const chain = cardChain(config);
+  if (!chain.some((link) => link.mintable)) return true;
+  return chain.some(canMintFor);
+}
+
+/** Whether this browser can really produce an instrument for ONE chain entry. */
+function canMintFor(link: CardChainLink): boolean {
+  if (!link.mintable) return false;
+  if (link.mockTokenization) return true;
+  const scheme = link.provider ? tokenizerFor(link.provider) : null;
   if (!scheme) return false;
-  return config.publicKey !== null || scheme === "pagbank-sdk";
+  return link.publicKey !== null || scheme === "pagbank-sdk";
 }
 
 /**
@@ -38,6 +56,62 @@ export function cardTokenization(config: CheckoutProviderConfig | null): CardTok
   return { provider: "pagbank", publicKey: null, mockTokenization: false };
 }
 
+/**
+ * Tokenization schemes that give the BROWSER something to mint (FUT-563).
+ * A `REDIRECT` provider's own page takes the card and a `NONE` one asks for no
+ * instrument at all — asking either for a token would produce a fake one under
+ * stub mode and an error everywhere else.
+ */
+const MINTABLE: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
+
+/**
+ * ONE entry of the store's chain as the card path sees it (FUT-563): how to
+ * mint an instrument for it, plus whether this browser is asked to mint at all.
+ */
+export interface CardChainLink extends CardTokenizationConfig {
+  /**
+   * The entry declares an in-browser scheme (`PUBLIC_KEY` / `SDK`).
+   *
+   * `false` entries are NOT dropped from the list, and that is the point: the
+   * charge still WALKS them, and how many providers the walk may reach is what
+   * decides whether the card charge has to carry `tokensByProvider` at all. A
+   * chain counted by "how many instruments the browser happened to mint" hides
+   * a hosted-page provider from the server, which then reads the bare token as
+   * the head's and skips the one entry that needed no instrument.
+   */
+  mintable: boolean;
+}
+
+/**
+ * The store's chain as one tokenization config per entry, in the merchant's
+ * order (FUT-563) — what the card path mints `tokensByProvider` from.
+ *
+ * A card instrument is bound to whoever minted it, so a charge can only fail
+ * over onto a provider the browser also tokenized for. Entries with no
+ * in-browser scheme are carried but marked {@link CardChainLink.mintable}
+ * false rather than mocked: they need no instrument, and the gateway passes an
+ * unattributed charge straight to them.
+ *
+ * Falls back to the HEAD triple when the host served no chain, which is exactly
+ * the pre-FUT-563 behaviour — one instrument, for the active provider.
+ */
+export function cardChain(config: CheckoutProviderConfig | null): CardChainLink[] {
+  if (!config) return [];
+  const chain = config.chain;
+  if (!chain || chain.length === 0) {
+    // No `tokenization` served either (an older host) ⇒ assume the head mints,
+    // which is what this checkout did before there was a chain to read.
+    const mintable = config.tokenization === null || MINTABLE.has(config.tokenization);
+    return [{ ...cardTokenization(config), mintable }];
+  }
+  return chain.map((link) => ({
+    provider: link.provider,
+    publicKey: link.publicKey,
+    mockTokenization: link.mockTokenization,
+    mintable: MINTABLE.has(link.tokenization),
+  }));
+}
+
 /**
  * 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/payment-error-panel.tsx

@@ -0,0 +1,97 @@
+import { Box } from "@mui/material";
+import { useState, type JSX } from "react";
+
+import { UNRESOLVED_CODE } from "./failure-codes";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * Order-creation failure shown inline on Pagamento — the buyer never leaves the
+ * step. Split out of `checkout-steps.tsx` when it grew a second presentation.
+ *
+ * Three shapes, and which one renders is decided by the failure's CODE, never
+ * by its prose:
+ *
+ *  - the buyer e-mail was rejected (the owner testing with the store's own
+ *    address) — offer a different e-mail to pay with;
+ *  - the charge is UNRESOLVED — a warning, and NO retry. Some provider may be
+ *    holding the buyer's money, so "Tentar novamente" mints a second order at
+ *    a new reference, outside the walk's re-probe of the old one: precisely
+ *    the double payment the message forbids, offered as the panel's most
+ *    prominent affordance;
+ *  - anything else — the ordinary danger Alert with a retry.
+ */
+export function PaymentErrorPanel({
+  message,
+  emailFlagged,
+  code,
+  onUseEmail,
+  onRetry,
+}: {
+  message: string;
+  emailFlagged: boolean;
+  /** The refusal's machine code, when the server sent one. */
+  code?: string | null;
+  onUseEmail: (email: string) => void;
+  onRetry: () => void;
+}): JSX.Element {
+  const { Alert } = useCheckoutComponents();
+  const unresolved = code === UNRESOLVED_CODE;
+
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      <Alert
+        variant={unresolved ? "warning" : "danger"}
+        title={unresolved ? "Estamos confirmando seu pagamento" : "Não foi possível continuar"}
+        description={message}
+        showIcon
+        data-testid={unresolved ? "checkout-unresolved" : "checkout-error"}
+      />
+      {unresolved ? null : <RetryAffordance {...{ emailFlagged, onUseEmail, onRetry }} />}
+    </Box>
+  );
+}
+
+/** What the buyer can do about a failure that IS safe to retry. */
+function RetryAffordance({
+  emailFlagged,
+  onUseEmail,
+  onRetry,
+}: {
+  emailFlagged: boolean;
+  onUseEmail: (email: string) => void;
+  onRetry: () => void;
+}): JSX.Element {
+  const { Button, Input } = useCheckoutComponents();
+  const [altEmail, setAltEmail] = useState("");
+
+  if (!emailFlagged) {
+    return (
+      <Box>
+        <Button variant="solid" color="primary" size="md" onClick={onRetry} dataTestId="checkout-retry-payment">
+          Tentar novamente
+        </Button>
+      </Box>
+    );
+  }
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      <Input
+        label="E-mail para o pagamento"
+        type="email"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="email"
+        placeholder="use um e-mail diferente do da loja"
+        value={altEmail}
+        onChange={(event) => setAltEmail(event.target.value)}
+        data-testid="checkout-alt-email"
+      />
+      <Box>
+        <Button variant="solid" color="primary" size="md" disabled={!altEmail.trim()} onClick={() => onUseEmail(altEmail.trim())} dataTestId="checkout-use-alt-email">
+          Usar este e-mail e continuar
+        </Button>
+      </Box>
+    </Box>
+  );
+}

package/src/components/checkout/types.ts

@@ -176,6 +176,16 @@ export interface ChargeCardInput {
   orderId: string;
   /** A fresh token, or a saved card's id for reuse. */
   token: string;
+  /**
+   * One instrument per provider, keyed by provider name (FUT-563).
+   *
+   * A card token is bound to whoever minted it, so a store with a failover
+   * chain needs one per entry: without them the server can only ever attempt
+   * the provider the browser tokenized for, and the walk skips the rest rather
+   * than hand them a blob they cannot read. Omitted for a saved card (its owner
+   * is the vault that holds it) and for a store with a single provider.
+   */
+  tokensByProvider?: Record<string, string>;
   /** Persist the token for future purchases (backend saves it against the buyer). */
   saveCard: boolean;
   /**
@@ -189,10 +199,24 @@ export interface ChargeCardInput {
 }
 
 /**
- * The store's active payment protocol, as `GET /api/checkout/config` answers
- * it (FUT-697). Extends the tokenization triple the card path consumes with
- * `tokenization`, which the method picker reads (`REDIRECT` ⇒ the provider's
- * hosted page takes the card, so no in-browser card form is needed).
+ * ONE enabled provider of the store's chain (FUT-563), as the buyer's config
+ * answers it. The same protocol facts as the head, stated per provider —
+ * which is what lets the card path mint an instrument for each of them.
+ */
+export interface CheckoutChainLink {
+  provider: string;
+  tokenization: "NONE" | "PUBLIC_KEY" | "SDK" | "REDIRECT";
+  publicKey: string | null;
+  mockTokenization: boolean;
+  methods: ("PIX" | "CARD" | "BOLETO")[];
+}
+
+/**
+ * The store's payment protocol, as `GET /api/checkout/config` answers it
+ * (FUT-697 / FUT-563). Extends the tokenization triple the card path consumes
+ * with `tokenization`, which the method picker reads (`REDIRECT` ⇒ the
+ * provider's hosted page takes the card, so no in-browser card form is
+ * needed), and with the whole enabled `chain`.
  */
 export interface CheckoutProviderConfig {
   /** Active provider's name, or `null` when the store has none connected. */
@@ -209,6 +233,17 @@ export interface CheckoutProviderConfig {
    * never offers PIX. Empty when no provider is connected.
    */
   methods: ("PIX" | "CARD" | "BOLETO")[];
+  /**
+   * EVERY enabled provider, in the merchant's own failover order (FUT-563) —
+   * the order the server will walk. The client is a READER of it: it never
+   * sorts, filters or re-heads this list, because the order is the merchant's
+   * decision and the server has already truncated it to the plan's ceiling.
+   *
+   * Optional so a config served by an older host (or a mocked one) still
+   * renders: absent, the card path behaves exactly as it did before, minting
+   * for the head alone.
+   */
+  chain?: CheckoutChainLink[];
 }
 
 /**

package/src/components/checkout/use-card-checkout.ts

@@ -4,7 +4,6 @@ import {
   NEW_CARD,
   detectBrand,
   onlyDigits,
-  tokenizeForCheckout,
   tokenizerFor,
   validateCardNumber,
   validateCvv,
@@ -14,83 +13,23 @@ import {
   type CardDetails,
   type CardFieldErrors,
   type CardTokenizationConfig,
-  type CardToken,
   type SavedCard,
 } from "../../card";
 import { ok, type Result } from "../../result";
 
+import { resolveNewCardToken, type CardInstruments } from "./card-instruments";
 import {
   chargeCard,
   listSavedCards,
   refreshCardPublicKey,
 } from "./client";
 import { rememberHostedOrder } from "./hosted-return";
-import type {
-  BuyerInfo,
-  CheckoutOrder,
-  OrderStatus,
-  SavedCardMeta,
-} from "./types";
+import type { CardChainLink } from "./method-capability";
+import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
 import { usePaymentPolling } from "./use-payment-polling";
 
 const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
 
-/**
- * Tokenize a new card in the ACTIVE provider's protocol (FUT-697), self-healing
- * a rotated public key (FUT-174): the card has already passed local validation,
- * so a real-key encryption failure most likely means the store's key rotated.
- * Refresh the store's key once and retry before surfacing the error;
- * `onKeyRefreshed` caches the new key for the session. The refresh is scoped to
- * the buyer's OWN `orderId` (the route derives the store from it server-side),
- * never a client-supplied store id — and only PagBank can mint a key on demand,
- * so the self-heal is gated on its scheme.
- */
-async function tokenizeNewCard(
-  card: CardDetails,
-  config: CardTokenizationConfig,
-  orderId: string,
-  onKeyRefreshed: (key: string) => void,
-): Promise<Result<CardToken>> {
-  const first = await tokenizeForCheckout(card, config);
-  if (first.ok || !config.publicKey) return first;
-  if (config.provider === null || tokenizerFor(config.provider) !== "pagbank-sdk") return first;
-
-  const refreshed = await refreshCardPublicKey({ orderId });
-  if (refreshed.ok && refreshed.data.publicKey && refreshed.data.publicKey !== config.publicKey) {
-    onKeyRefreshed(refreshed.data.publicKey);
-    return tokenizeForCheckout(card, { ...config, publicKey: refreshed.data.publicKey });
-  }
-  return first;
-}
-
-/** Non-sensitive display metadata for saving a card (the PAN never leaves the form). */
-function toCardMeta(card: CardDetails, token: CardToken): SavedCardMeta {
-  const [mm = "", yy = ""] = card.expiry.split("/");
-  return {
-    brand: token.brand,
-    last4: token.last4,
-    expMonth: Number(mm),
-    expYear: 2000 + Number(yy),
-    holder: card.holder.trim(),
-  };
-}
-
-/** The charge token for a new card (tokenize + self-heal), plus optional save-meta. */
-async function resolveNewCardToken(
-  card: CardDetails,
-  config: CardTokenizationConfig,
-  orderId: string,
-  onKeyRefreshed: (key: string) => void,
-  saveCard: boolean,
-): Promise<Result<{ token: string; cardMeta?: SavedCardMeta }>> {
-  const tokenized = await tokenizeNewCard(card, config, orderId, onKeyRefreshed);
-  if (!tokenized.ok) return tokenized;
-  return ok({
-    token: tokenized.data.token,
-    ...(saveCard ? { cardMeta: toCardMeta(card, tokenized.data) } : {}),
-  });
-}
-
 /**
  * Saved-card list + current selection, loaded once on mount — scoped to the
  * current store (FUT-697), so only cards the store's active provider can
@@ -168,6 +107,8 @@ interface CardCheckout {
   saveCard: boolean;
   setSaveCard: (checked: boolean) => void;
   error: string | null;
+  /** The failure's machine code, when the server sent one — drives PRESENTATION. */
+  errorCode: string | null;
   submitting: boolean;
   submitted: boolean;
   pollError: string | null;
@@ -189,7 +130,13 @@ interface CardFormState {
 /** The submit slice of {@link useCardCheckout}. */
 type CardSubmit = Pick<
   CardCheckout,
-  "submitting" | "submitted" | "error" | "pollError" | "pollTimedOut" | "handlePay"
+  | "submitting"
+  | "submitted"
+  | "error"
+  | "errorCode"
+  | "pollError"
+  | "pollTimedOut"
+  | "handlePay"
 >;
 
 /**
@@ -209,6 +156,41 @@ function handOverToChallenge(order: CheckoutOrder, url: string): void {
   window.location.assign(url);
 }
 
+/** The buyer's card is invalid — block the submit and show which field. */
+function blockedByForm(form: CardFormState): boolean {
+  if (!form.usingNewCard) return false;
+  const errors = form.validate();
+  form.setFieldErrors(errors);
+  return Object.values(errors).some(Boolean);
+}
+
+/**
+ * What to charge with: a saved card's vault id, or fresh instruments minted for
+ * every provider the walk may reach (FUT-563).
+ *
+ * A saved card is deliberately never chained — a vault token names a card in
+ * whichever provider's vault holds it, which the server resolves; the
+ * instruments minted this session say nothing about who that is.
+ */
+async function resolveInstruments(input: {
+  form: CardFormState;
+  orderId: string;
+  config: CardTokenizationConfig;
+  onKeyRefreshed: (key: string) => void;
+  providerChain: readonly CardChainLink[];
+}): Promise<Result<CardInstruments>> {
+  const { form } = input;
+  if (!form.usingNewCard) return ok({ token: form.selection });
+  return resolveNewCardToken(
+    form.card,
+    input.config,
+    input.orderId,
+    input.onKeyRefreshed,
+    form.saveCard,
+    input.providerChain,
+  );
+}
+
 /**
  * The submit state machine (FUT-58): validate → tokenize (self-heal) → charge →
  * poll for the async confirmation, bubbling the terminal status up via
@@ -221,10 +203,12 @@ function useCardSubmit(
   onResolved: (status: OrderStatus) => void,
   pollIntervalMs: number,
   form: CardFormState,
+  providerChain: readonly CardChainLink[],
 ): CardSubmit {
   const [submitting, setSubmitting] = useState(false);
   const [submitted, setSubmitted] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [errorCode, setErrorCode] = useState<string | null>(null);
   // The active key: resolved by the checkout config, overridden by the
   // rotated-key self-heal for the rest of the session.
   const { publicKey, setPublicKey } = useCardPublicKey(order.orderId, providerConfig);
@@ -239,27 +223,19 @@ function useCardSubmit(
     if (status && status !== "AWAITING_PAYMENT") onResolved(status);
   }, [status, onResolved]);
 
-  async function resolveToken(): Promise<Result<{ token: string; cardMeta?: SavedCardMeta }>> {
-    if (!form.usingNewCard) return ok({ token: form.selection }); // reuse saved card's token id
-    return resolveNewCardToken(
-      form.card,
-      { ...providerConfig, publicKey },
-      order.orderId,
-      setPublicKey,
-      form.saveCard,
-    );
-  }
-
   const handlePay = async (): Promise<void> => {
     setError(null);
-    if (form.usingNewCard) {
-      const errors = form.validate();
-      form.setFieldErrors(errors);
-      if (Object.values(errors).some(Boolean)) return; // block submit until valid
-    }
+    setErrorCode(null);
+    if (blockedByForm(form)) return;
     setSubmitting(true);
 
-    const resolved = await resolveToken();
+    const resolved = await resolveInstruments({
+      form,
+      orderId: order.orderId,
+      config: { ...providerConfig, publicKey },
+      onKeyRefreshed: setPublicKey,
+      providerChain,
+    });
     if (!resolved.ok) {
       setError(resolved.error);
       setSubmitting(false);
@@ -269,12 +245,16 @@ function useCardSubmit(
     const charged = await chargeCard({
       orderId: order.orderId,
       token: resolved.data.token,
+      tokensByProvider: resolved.data.tokensByProvider,
       saveCard: form.usingNewCard && form.saveCard,
       cardMeta: resolved.data.cardMeta,
       taxId: buyer.taxId,
     });
     if (!charged.ok) {
       setError(charged.error); // transport/validation problem — stay on the form
+      // An UNRESOLVED charge is not a decline: some provider may be holding the
+      // money, so the view must not dress it as one (`card-view.tsx`).
+      setErrorCode(charged.code ?? null);
       setSubmitting(false);
       return;
     }
@@ -289,7 +269,7 @@ function useCardSubmit(
     else setSubmitted(true);
   };
 
-  return { submitting, submitted, error, pollError, pollTimedOut, handlePay };
+  return { submitting, submitted, error, errorCode, pollError, pollTimedOut, handlePay };
 }
 
 /**
@@ -304,6 +284,11 @@ export function useCardCheckout(
   pollIntervalMs: number,
   /** The store whose saved cards may be offered (host routing owns the slug). */
   tenantSlug?: string,
+  /**
+   * The merchant's ordered provider chain (FUT-563) — one instrument is minted
+   * per entry so a card charge can fail over. Omitted ⇒ the head alone.
+   */
+  providerChain: readonly CardChainLink[] = [],
 ): CardCheckout {
   const { savedCards, selection, setSelection } = useSavedCards(tenantSlug);
   const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
@@ -320,14 +305,15 @@ export function useCardCheckout(
     cvv: validateCvv(card.cvv, brand),
   });
 
-  const submit = useCardSubmit(order, buyer, providerConfig, onResolved, pollIntervalMs, {
-    card,
-    usingNewCard,
-    selection,
-    saveCard,
-    validate,
-    setFieldErrors,
-  });
+  const submit = useCardSubmit(
+    order,
+    buyer,
+    providerConfig,
+    onResolved,
+    pollIntervalMs,
+    { card, usingNewCard, selection, saveCard, validate, setFieldErrors },
+    providerChain,
+  );
 
   return {
     savedCards,

package/src/components/checkout/use-checkout-controller.ts

@@ -159,6 +159,33 @@ function usePaidPort(settled: OrderStatus | null, onPaid: (() => void) | undefin
   }, [settled, onPaid]);
 }
 
+/**
+ * The create-order refusal the steps render: what to say, which field to
+ * highlight, and the machine CODE that decides how it is presented — an
+ * unresolved charge is not a failed one, and the Pagamento step must not offer
+ * it a "Tentar novamente" (FUT-563). One hook so the three always move
+ * together; they were three `useState`s that could be cleared apart.
+ */
+function useCreateFailure() {
+  const [message, setMessage] = useState<string | null>(null);
+  const [field, setField] = useState<BuyerField | null>(null);
+  const [code, setCode] = useState<string | null>(null);
+  const clear = useCallback(() => {
+    setMessage(null);
+    setField(null);
+    setCode(null);
+  }, []);
+  const fail = useCallback(
+    (next: { message: string; field?: BuyerField | null; code?: string }) => {
+      setMessage(next.message);
+      setField(next.field ?? null);
+      setCode(next.code ?? null);
+    },
+    [],
+  );
+  return { message, field, code, clear, fail };
+}
+
 /**
  * All checkout state + handlers, so the checkout flow stays presentational.
  * - `setMethod` drops any order raised for the previous method (no stale QR/form).
@@ -195,10 +222,9 @@ export function useCheckoutController(
   const [order, setOrder] = useState<CheckoutOrder | null>(resume.order);
   const [finalStatus, setFinalStatus] = useState<OrderStatus | null>(null);
   const [creating, setCreating] = useState(false);
-  const [createError, setCreateError] = useState<string | null>(null);
-  const [errorField, setErrorField] = useState<BuyerField | null>(null);
+  const failure = useCreateFailure();
 
-  const clearError = useCallback(() => { setCreateError(null); setErrorField(null); }, []);
+  const clearError = failure.clear;
   const setBuyer = useCallback((next: BuyerInfo) => { setBuyerState(next); clearError(); }, [clearError]);
   const { back, editBuyer } = useCheckoutNav(taxIdOnFile, onExitToMenu, setStep);
   const setMethod = useCallback((next: PaymentMethod) => {
@@ -207,7 +233,7 @@ export function useCheckoutController(
   const goToPayment = useCallback(() => {
     clearError();
     const cpfError = cpfGateError(buyer.taxId?.trim() ?? "", taxIdOnFile);
-    if (cpfError) { setCreateError(cpfError); setErrorField("cpf"); return; }
+    if (cpfError) { failure.fail({ message: cpfError, field: "cpf" }); return; }
     // Persist the buyer's details HERE, on "Continuar" — not when a payment is
     // raised. Everything after this step can fail (no provider configured, a
     // declined card, an abandoned PIX, a closed tab) and the details must
@@ -225,7 +251,7 @@ export function useCheckoutController(
     setCreating(true);
     const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
     setCreating(false);
-    if (!result.ok) { setCreateError(result.error.message); setErrorField(result.error.field); return; }
+    if (!result.ok) { failure.fail(result.error); return; }
     if (handOverToProvider(result.data)) return;
     setOrder(result.data);
     setFinalStatus(null);
@@ -245,7 +271,8 @@ export function useCheckoutController(
 
   return {
     step, setStep, method, setMethod, buyer, setBuyer, saveProfile, setSaveProfile,
-    order, finalStatus: finalStatus ?? resume.status, creating, createError, errorField,
+    order, finalStatus: finalStatus ?? resume.status, creating,
+    createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
     goToPayment, startPayment, payWithEmail, handleResolved, retry, completed,
   };

package/src/result.ts

@@ -4,8 +4,21 @@
  * portable frontend never reaches back into a repo-specific package for a
  * ten-line type.
  */
-export type Result<T> = { ok: true; data: T } | { ok: false; error: string };
+export type Result<T> =
+  | { ok: true; data: T }
+  /**
+   * `code` is the API envelope's machine code, when the failure came from one
+   * (`PAYMENT_UNRESOLVED`, `GATEWAY_UNAVAILABLE`, …). Optional because a
+   * browser-side failure — a tokenizer bail, a dropped connection — has none.
+   * The MESSAGE is what the buyer reads; the code is what the surface uses to
+   * decide how to PRESENT it, which a message cannot be parsed for.
+   */
+  | { ok: false; error: string; code?: string };
 
 export const ok = <T,>(data: T): Result<T> => ({ ok: true, data });
 
-export const err = <T,>(error: string): Result<T> => ({ ok: false, error });
+export const err = <T,>(error: string, code?: string): Result<T> => ({
+  ok: false,
+  error,
+  ...(code ? { code } : {}),
+});