@12-apps/payments-frontend 1.3.1 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "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": {
@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^1.3.1",
+    "@12-apps/payments-backend": "^1.4.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -29,8 +29,8 @@
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",
-    "@12-apps/eslint-config": "^1.4.1",
-    "@12-apps/typescript-config": "^1.4.1",
+    "@12-apps/eslint-config": "^1.5.1",
+    "@12-apps/typescript-config": "^1.5.1",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
@@ -61,6 +61,14 @@
     "prisma",
     "*.js",
     "*.mjs",
-    "*.md"
+    "*.md",
+    "!eslint.config.js",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.stories.*",
+    "!**/*.test-story.*",
+    "!**/test-helpers.*"
   ]
 }

package/src/card/stripe-token.ts

@@ -37,6 +37,8 @@ export async function tokenizeWithStripe(
   publicKey: string,
   brand: string,
   last4: string,
+  /** Deadline for the round trip; an abort reads as "could not contact". */
+  signal?: AbortSignal,
 ): Promise<Result<CardToken>> {
   const match = /^(\d{2})\/(\d{2})$/.exec(card.expiry.trim());
   if (!match) return err("Validade inválida ou expirada.");
@@ -60,6 +62,7 @@ export async function tokenizeWithStripe(
         Authorization: `Bearer ${publicKey}`,
       },
       body: body.toString(),
+      signal,
     });
   } catch {
     return err("Não foi possível contatar o provedor do cartão. Verifique sua conexão.");

package/src/card/tokenize.ts

@@ -157,6 +157,8 @@ async function tokenizeWithPagarme(
   publicKey: string,
   brand: string,
   last4: string,
+  /** Deadline for the round trip; an abort reads as "could not contact". */
+  signal?: AbortSignal,
 ): Promise<Result<CardToken>> {
   const match = /^(\d{2})\/(\d{2})$/.exec(card.expiry.trim());
   if (!match) return err("Validade inválida ou expirada.");
@@ -166,6 +168,7 @@ async function tokenizeWithPagarme(
     response = await fetch(`${PAGARME_TOKENS_URL}?appId=${encodeURIComponent(publicKey)}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
+      signal,
       body: JSON.stringify({
         type: "card",
         card: {
@@ -203,6 +206,11 @@ export async function tokenizeCard(
   card: CardDetails,
   publicKey: string | null | undefined,
   tokenizer: CardTokenizer = "pagbank-sdk",
+  /**
+   * Bounds the network schemes (Pagar.me / Stripe). The PagBank one encrypts
+   * locally and has no request to abort.
+   */
+  signal?: AbortSignal,
 ): Promise<Result<CardToken>> {
   const validationError = validateCardInput(card);
   if (validationError) return err(validationError);
@@ -219,10 +227,10 @@ export async function tokenizeCard(
   const last4 = pan.slice(-4);
 
   if (tokenizer === "pagarme-token") {
-    return tokenizeWithPagarme(card, pan, publicKey, brand, last4);
+    return tokenizeWithPagarme(card, pan, publicKey, brand, last4, signal);
   }
   if (tokenizer === "stripe-pm") {
-    return tokenizeWithStripe(card, pan, publicKey, brand, last4);
+    return tokenizeWithStripe(card, pan, publicKey, brand, last4, signal);
   }
 
   if (!(await ensurePagBankSdk())) {
@@ -274,9 +282,15 @@ const CARD_PATH_UNAVAILABLE =
 export async function tokenizeForCheckout(
   card: CardDetails,
   config: CardTokenizationConfig,
+  /**
+   * Optional deadline for a provider that mints over the network. The chain
+   * path passes one so a backup acquirer nobody can reach cannot hold the
+   * buyer's Pagar button (FUT-563).
+   */
+  signal?: AbortSignal,
 ): Promise<Result<CardToken>> {
   const scheme = config.provider ? tokenizerFor(config.provider) : null;
-  if (scheme && config.publicKey) return tokenizeCard(card, config.publicKey, scheme);
+  if (scheme && config.publicKey) return tokenizeCard(card, config.publicKey, scheme, signal);
 
   if (!config.mockTokenization) return err(CARD_PATH_UNAVAILABLE);
 

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

@@ -0,0 +1,222 @@
+import {
+  tokenizeForCheckout,
+  tokenizerFor,
+  type CardDetails,
+  type CardToken,
+  type CardTokenizationConfig,
+} from "../../card";
+import { err, ok, type Result } from "../../result";
+
+import { refreshCardPublicKey } from "./client";
+import type { CardChainLink } from "./method-capability";
+import type { SavedCardMeta } from "./types";
+
+/**
+ * TOKENIZATION for the buyer's card — one instrument per provider the charge
+ * may reach (FUT-563).
+ *
+ * A card token is bound to whoever minted it: the gateway refuses to hand
+ * provider #2 provider #1's blob and skips it instead. So the checkout's whole
+ * contribution to card failover is here — take the card the buyer typed ONCE,
+ * and produce an instrument for each entry of the chain the server published.
+ *
+ * Split out of `use-card-checkout.ts` so the hook stays about SUBMIT state:
+ * nothing in this module touches React.
+ */
+
+/**
+ * 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(),
+  };
+}
+
+/**
+ * One instrument per provider in the chain (FUT-563), keyed by provider name.
+ *
+ * A card token is bound to whoever minted it, so a charge can only fail over
+ * onto a provider the browser ALSO tokenized for. Every entry is attempted and
+ * the failures are simply left out: a provider we could not mint for is one the
+ * walk will skip, which is the honest outcome and strictly better than failing
+ * the whole payment because the second acquirer's key was missing.
+ *
+ * Nothing is re-typed and nothing is asked of the buyer twice — the same
+ * validated card fields are encrypted once per provider, in the browser.
+ */
+async function mintChainInstruments(
+  card: CardDetails,
+  chain: readonly CardChainLink[],
+  timeoutMs: number,
+): Promise<Record<string, CardToken>> {
+  const results = await Promise.all(
+    chain.map(async (link) => {
+      // A hosted page (`REDIRECT`) or an instrument-free provider (`NONE`) is
+      // skipped, never mocked: minting for it would produce a FAKE token under
+      // stub mode and an error everywhere else. It still travels in `chain`,
+      // because the walk will reach it.
+      if (!link.provider || !link.mintable) return null;
+      const tokenized = await mintWithDeadline(card, link, timeoutMs);
+      return tokenized.ok ? ([link.provider, tokenized.data] as const) : null;
+    }),
+  );
+  return Object.fromEntries(results.filter((entry) => entry !== null));
+}
+
+/**
+ * How long ONE backup acquirer may hold the buyer's Pagar button.
+ *
+ * A tokenizer is a cross-origin POST to the acquirer (Pagar.me, Stripe) with
+ * no deadline of its own, and browser `fetch` has none either: a middlebox that
+ * accepts the socket and never answers leaves the promise pending for as long
+ * as the OS keeps the connection, which the buyer sees as a spinning, disabled
+ * "Pagar R$ …" with no cancel and no explanation. Bounding it degrades to what
+ * this module already documents — a provider we could not mint for is one the
+ * walk will skip.
+ */
+const MINT_TIMEOUT_MS = 8_000;
+
+/** One tail mint, abandoned (and aborted) when the deadline passes. */
+async function mintWithDeadline(
+  card: CardDetails,
+  link: CardChainLink,
+  timeoutMs: number,
+): Promise<Result<CardToken>> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // RACED as well as aborted: the abort ends a `fetch`, but the PagBank scheme
+  // waits on an injected <script> that can hang with nothing to cancel.
+  const deadline = new Promise<Result<CardToken>>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve(err("O provedor do cartão não respondeu a tempo."));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([tokenizeForCheckout(card, link, controller.signal), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** What a submitted card charge carries: the head's token plus the chain's. */
+export interface CardInstruments {
+  token: string;
+  tokensByProvider?: Record<string, string>;
+  cardMeta?: SavedCardMeta;
+}
+
+/**
+ * The chain entry the bare `token` is minted from — NOT the chain head.
+ *
+ * `usesHostedCheckout` asks the WHOLE chain whether anybody tokenizes in the
+ * browser, so a store headed by a hosted page whose NEXT provider does gets our
+ * card form rather than the handover. The head then has no in-browser scheme at
+ * all: minting against it returns "o pagamento com cartão está indisponível",
+ * and the buyer who just typed a full PAN is refused while the mintable tail —
+ * the very provider the form was shown for — is never asked. That is the whole
+ * card path of every REDIRECT-headed store that adds a backup provider, and
+ * enabling a provider APPENDS it, so the shape arises with no reordering.
+ *
+ * The ACTIVE provider still wins when it is itself mintable: only its config
+ * carries the key this session may have self-healed (FUT-174).
+ *
+ * Falls back to the active config when nothing in the chain can be minted for
+ * — the tokenizer then says so in the buyer's own words, which is the honest
+ * answer for a store that has no in-browser card path at all.
+ */
+function mintingConfig(
+  config: CardTokenizationConfig,
+  chain: readonly CardChainLink[],
+): CardTokenizationConfig {
+  const mintable = chain.filter((link) => link.mintable && link.provider);
+  if (mintable.length === 0) return config;
+  return mintable.some((link) => link.provider === config.provider) ? config : mintable[0]!;
+}
+
+/** The charge token for a new card (tokenize + self-heal), plus optional save-meta. */
+export async function resolveNewCardToken(
+  card: CardDetails,
+  config: CardTokenizationConfig,
+  orderId: string,
+  onKeyRefreshed: (key: string) => void,
+  saveCard: boolean,
+  chain: readonly CardChainLink[],
+  /** Per-entry mint deadline. Overridable so tests need not wait it out. */
+  timeoutMs: number = MINT_TIMEOUT_MS,
+): Promise<Result<CardInstruments>> {
+  // No chain served (an older host, or a fetch blip): the active provider
+  // alone, exactly the pre-FUT-563 behaviour.
+  const entries = chain.length > 0 ? chain : [{ ...config, mintable: true }];
+  const head = mintingConfig(config, entries);
+  // The self-heal rides along and stays PagBank-only — `tokenizeNewCard` gates
+  // on its scheme, so a chain headed elsewhere cannot ask for someone's key.
+  // Head and tail mint CONCURRENTLY. Sequentially, one unreachable backup
+  // acquirer held a healthy head's charge for as long as the network stack
+  // allowed — the failover feature blocking on the provider it exists to fall
+  // back to. The head keeps no deadline: it is the provider being paid, and
+  // its self-heal is a second round trip of our own.
+  const rest = entries.filter((link) => link.provider !== head.provider);
+  const [headToken, tail] = await Promise.all([
+    tokenizeNewCard(card, head, orderId, onKeyRefreshed),
+    mintChainInstruments(card, rest, timeoutMs),
+  ]);
+  // A failure in the tail is not fatal: that provider is simply one the walk
+  // will skip.
+  const minted = { ...tail };
+  if (headToken.ok && head.provider) minted[head.provider] = headToken.data;
+
+  // Refused only when NO entry could be minted for. While one still can, the
+  // charge goes out and the entries we hold nothing for are skipped by name.
+  const anyMinted = Object.values(minted);
+  if (!headToken.ok && anyMinted.length === 0) return headToken;
+  const primary = headToken.ok ? headToken.data : anyMinted[0]!;
+  const tokensByProvider = Object.fromEntries(
+    Object.entries(minted).map(([provider, instrument]) => [provider, instrument.token]),
+  );
+  return ok({
+    token: primary.token,
+    // Sent whenever the WALK has more than one provider to reach — counted on
+    // the chain the server published, never on how many instruments happened
+    // to be minted (FUT-563). A hosted-page provider mints nothing by design,
+    // so counting the map drops it for the two-provider store it exists for:
+    // the bare token is then read as the chain HEAD's and every other entry is
+    // refused as "holding someone else's instrument", including the one that
+    // needed none. A genuinely single-provider store still sends exactly what
+    // it sent before.
+    ...(entries.length > 1 ? { tokensByProvider } : {}),
+    ...(saveCard ? { cardMeta: toCardMeta(card, primary) } : {}),
+  });
+}

package/src/components/checkout/card-view.tsx

@@ -8,6 +8,8 @@ import {
   type CardTokenizationConfig,
 } from "../../card";
 
+import { UNRESOLVED_CODE } from "./failure-codes";
+import type { CardChainLink } from "./method-capability";
 import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
 import { useCardCheckout } from "./use-card-checkout";
@@ -58,6 +60,38 @@ function SubmittedState({
   );
 }
 
+/**
+ * What a submit came back with.
+ *
+ * An UNRESOLVED charge gets its own presentation (FUT-563): some provider may
+ * be holding the buyer's money, so wording it as a failure — and heading it
+ * "Não foi possível pagar" above a body that says "não pague de novo" — pushes
+ * the buyer toward exactly the second payment it forbids.
+ */
+function ChargeFailure({
+  message,
+  unresolved,
+}: {
+  message: string;
+  unresolved: boolean;
+}): JSX.Element {
+  const { Alert } = useCheckoutComponents();
+  if (unresolved) {
+    return (
+      <Alert
+        variant="warning"
+        title="Estamos confirmando seu pagamento"
+        description={message}
+        showIcon
+        data-testid="card-unresolved"
+      />
+    );
+  }
+  return (
+    <Alert variant="danger" title="Não foi possível pagar" description={message} showIcon data-testid="card-error" />
+  );
+}
+
 /**
  * Card payment view (FUT-58). Card data is validated + formatted client-side, then
  * tokenized (mock PagBank JS SDK) so the PAN never reaches our server; only the
@@ -72,6 +106,7 @@ export function CardView({
   order,
   buyer = {},
   providerConfig,
+  providerChain,
   tenantSlug,
   onResolved,
   pollIntervalMs = 2500,
@@ -80,13 +115,24 @@ export function CardView({
   buyer?: BuyerInfo;
   /** The active provider's tokenization protocol + key (FUT-697). */
   providerConfig: CardTokenizationConfig;
+  /**
+   * Every provider the charge may WALK, in the merchant's order (FUT-563) —
+   * one instrument is minted per entry so the charge survives the first
+   * provider failing. Omitted ⇒ the head alone, as before.
+   */
+  providerChain?: CardChainLink[];
   /** Scopes the saved-card list to cards the store's provider can charge. */
   tenantSlug?: string;
   onResolved: (status: OrderStatus) => void;
   pollIntervalMs?: number;
 }): JSX.Element {
-  const { Alert, Text } = useCheckoutComponents();
-  const cc = useCardCheckout(order, buyer, providerConfig, onResolved, pollIntervalMs, tenantSlug);
+  const { Text } = useCheckoutComponents();
+  const cc = useCardCheckout(order, buyer, providerConfig, onResolved, pollIntervalMs, tenantSlug, providerChain);
+  // A charge NOBODY can confirm yet is not a decline (FUT-563). Some provider
+  // may be holding the buyer's money, so it gets its own presentation: the
+  // danger heading "Não foi possível pagar" contradicts the body's "não pague
+  // de novo" and pushes the buyer toward exactly the retry it forbids.
+  const unresolved = cc.errorCode === UNRESOLVED_CODE;
 
   if (cc.submitted) {
     return <SubmittedState pollError={cc.pollError} pollTimedOut={cc.pollTimedOut} />;
@@ -118,11 +164,15 @@ export function CardView({
         />
       ) : null}
 
-      {cc.error ? (
-        <Alert variant="danger" title="Não foi possível pagar" description={cc.error} showIcon data-testid="card-error" />
-      ) : null}
+      {cc.error ? <ChargeFailure message={cc.error} unresolved={unresolved} /> : null}
 
-      <CardPayBar totalLabel={order.totalLabel} submitting={cc.submitting} onPay={() => void cc.handlePay()} />
+      {/* The pay bar is GONE while a charge is unresolved, not merely disabled
+          with a spinner: paying again is the one action the message forbids,
+          and a live "Pagar R$ …" directly under "não pague de novo" is what
+          the buyer's thumb reaches for. */}
+      {unresolved ? null : (
+        <CardPayBar totalLabel={order.totalLabel} submitting={cc.submitting} onPay={() => void cc.handlePay()} />
+      )}
     </Box>
   );
 }

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

@@ -161,6 +161,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
           creating={c.creating}
           createError={c.createError}
           errorField={c.errorField}
+          errorCode={c.errorCode}
           onGenerate={(chosen) => void c.startPayment(chosen)}
           onUseEmail={c.payWithEmail}
           // Set only for a skipped-Dados flow (the controller decides); the

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

@@ -1,16 +1,18 @@
 import { Box } from "@mui/material";
-import { useEffect, useRef, useState, type JSX, type ReactNode } from "react";
+import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import { BuyerInfoForm } from "./buyer-info-form";
 import { CardView } from "./card-view";
 import { LockOutlinedIcon } from "./icons";
 import {
+  cardChain,
   cardPathAvailable,
   cardTokenization,
   offeredMethods,
   usePreselectSoleMethod,
 } from "./method-capability";
 import { MethodPicker } from "./method-picker";
+import { PaymentErrorPanel } from "./payment-error-panel";
 import { PayerSummary } from "./payer-summary";
 import { PixView } from "./pix-view";
 import type {
@@ -74,6 +76,9 @@ function PaymentBody({
         order={order}
         buyer={buyer}
         providerConfig={cardTokenization(providerConfig)}
+        // The whole chain (FUT-563): one instrument is minted per provider so
+        // the charge survives the first one failing, with nothing re-typed.
+        providerChain={cardChain(providerConfig)}
         tenantSlug={tenantSlug}
         onResolved={onResolved}
         pollIntervalMs={pollIntervalMs}
@@ -229,6 +234,11 @@ interface PaymentStepProps {
   creating: boolean;
   createError: string | null;
   errorField: BuyerField | null;
+  /**
+   * The refusal's machine code (FUT-563). An UNRESOLVED charge is not a failed
+   * one — the panel below must not offer to raise a second.
+   */
+  errorCode?: string | null;
   onGenerate: (method: PaymentMethod) => void;
   onUseEmail: (email: string) => void;
   /**
@@ -262,6 +272,7 @@ export function PaymentStep({
   creating,
   createError,
   errorField,
+  errorCode,
   onGenerate,
   onUseEmail,
   onEditBuyer,
@@ -304,6 +315,7 @@ export function PaymentStep({
         <PaymentErrorPanel
           message={createError}
           emailFlagged={errorField === "email"}
+          code={errorCode}
           onUseEmail={onUseEmail}
           onRetry={() => onGenerate(method)}
         />
@@ -311,56 +323,3 @@ export function PaymentStep({
     </Box>
   );
 }
-
-/**
- * Order-creation failure (non-field) shown inline on Pagamento with a retry — the
- * buyer never leaves the step. When the buyer e-mail was rejected (owner testing
- * with the store's own e-mail) it offers a different e-mail to pay with.
- */
-function PaymentErrorPanel({
-  message,
-  emailFlagged,
-  onUseEmail,
-  onRetry,
-}: {
-  message: string;
-  emailFlagged: boolean;
-  onUseEmail: (email: string) => void;
-  onRetry: () => void;
-}): JSX.Element {
-  const { Alert, Button, Input } = useCheckoutComponents();
-  const [altEmail, setAltEmail] = useState("");
-
-  return (
-    <Box sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
-      <Alert variant="danger" title="Não foi possível continuar" description={message} showIcon data-testid="checkout-error" />
-      {emailFlagged ? (
-        <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>
-      ) : (
-        <Box>
-          <Button variant="solid" color="primary" size="md" onClick={onRetry} dataTestId="checkout-retry-payment">
-            Tentar novamente
-          </Button>
-        </Box>
-      )}
-    </Box>
-  );
-}

package/src/components/checkout/client.ts

@@ -31,6 +31,23 @@ import type {
 interface ApiEnvelope<T> {
   data?: T;
   error?: string;
+  /**
+   * Stable machine code for the failure (`checkoutErrorResponse` always sends
+   * one). Carried through so a surface can PRESENT a refusal for what it is —
+   * an unresolved charge is not a decline, and rendering it under "não foi
+   * possível pagar" with a live pay button invites the second payment its own
+   * text forbids.
+   */
+  code?: string;
+}
+
+/**
+ * A non-2xx envelope as a {@link Result} failure, carrying its machine CODE.
+ * The message is what the buyer reads; the code is what a surface uses to
+ * decide how to PRESENT it, which a message cannot be parsed for.
+ */
+function refused<T>(json: ApiEnvelope<T> | null): Result<T> {
+  return err(json?.error ?? "Não foi possível concluir a operação. Tente novamente.", json?.code);
 }
 
 /** Call an API route and normalize the response into a {@link Result}. */
@@ -41,9 +58,7 @@ async function requestResult<T>(input: string, init?: RequestInit): Promise<Resu
       headers: { "Content-Type": "application/json", ...init?.headers },
     });
     const json = (await res.json().catch(() => null)) as ApiEnvelope<T> | null;
-    if (!res.ok) {
-      return err(json?.error ?? "Não foi possível concluir a operação. Tente novamente.");
-    }
+    if (!res.ok) return refused(json);
     if (!json || json.data === undefined) {
       return err(json?.error ?? "Resposta inválida do servidor.");
     }
@@ -137,6 +152,9 @@ export async function chargeCard(input: ChargeCardInput): Promise<Result<ChargeO
     body: JSON.stringify({
       orderId: input.orderId,
       token: input.token,
+      // One instrument per provider (FUT-563) — the server hands each provider
+      // in the chain its own, which is what lets a card charge fail over.
+      ...(input.tokensByProvider ? { tokensByProvider: input.tokensByProvider } : {}),
       saveCard: input.saveCard,
       cardMeta: input.cardMeta,
       taxId: input.taxId,

package/src/components/checkout/failure-codes.ts

@@ -0,0 +1,17 @@
+/**
+ * Checkout failure codes the BUYER SURFACE presents differently (FUT-563).
+ *
+ * Everything else the server refuses is one thing to a shopper — "it did not
+ * work, try again" — and one danger Alert says it. These are the exceptions:
+ * codes whose correct rendering is not an error at all, and which a message
+ * string cannot be parsed for without turning copy edits into behaviour
+ * changes.
+ */
+
+/**
+ * The charge is IN DOUBT, not failed: some provider may be holding the buyer's
+ * money and no probe could say. It is the one outcome where inviting a retry
+ * is actively harmful, so the surface must drop every affordance that offers
+ * one and must not word it as a failure.
+ */
+export const UNRESOLVED_CODE = "PAYMENT_UNRESOLVED";