@12-apps/payments-frontend 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.0.0",
+  "version": "1.2.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": {
@@ -14,6 +14,9 @@
     "check-types": "tsc --noEmit",
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "react-qr-code": "^2.2.0"
+  },
   "peerDependencies": {
     "@emotion/react": ">=11.0.0",
     "@emotion/styled": ">=11.0.0",
@@ -25,9 +28,9 @@
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",
-    "@12-apps/eslint-config": "^1.1.0",
-    "@12-apps/payments-backend": "^1.0.0",
-    "@12-apps/typescript-config": "^1.1.0",
+    "@12-apps/eslint-config": "^1.3.0",
+    "@12-apps/payments-backend": "^1.2.0",
+    "@12-apps/typescript-config": "^1.3.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",

package/src/__tests__/provider-priority-list.test.tsx

@@ -36,8 +36,8 @@ function viewOf(configs: MaskedProviderConfig[]): MerchantSettingsView {
   const chain = configs.filter((c) => c.enabled).map((c) => c.provider);
   return {
     providers: [
-      { name: 'stone', displayName: 'Stone', authMode: 'credentials', capabilities: CAPS, credentialSchema: [] },
-      { name: 'stripe', displayName: 'Stripe', authMode: 'oauth', capabilities: CAPS, credentialSchema: [] },
+      { name: 'stone', displayName: 'Stone', urlSlug: 'stone', authMode: 'credentials', capabilities: CAPS, credentialSchema: [] },
+      { name: 'stripe', displayName: 'Stripe', urlSlug: 'stripe', authMode: 'oauth', capabilities: CAPS, credentialSchema: [] },
     ],
     configs,
     providerChain: chain,

package/src/__tests__/slugged-provider.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MerchantSettingsView } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { PaymentProviderSettings } from '../components/PaymentProviderSettings';
+
+/**
+ * How a provider is spelled in a URL is the ADAPTER's declaration (FUT-557),
+ * carried in the catalog as `urlSlug`. A controlled host passes its path
+ * segment verbatim and writes back whatever `onProviderChange` reports, so
+ * it holds no map of providers: resolution here must accept the slug AND the
+ * raw name (old links must not 404), and report the slug on every change.
+ */
+
+const VIEW: MerchantSettingsView = {
+  providers: [
+    {
+      name: 'infinitepay',
+      displayName: 'InfinitePay',
+      urlSlug: 'infinite-pay',
+      authMode: 'credentials',
+      credentialSchema: [],
+    },
+    { name: 'pagbank', displayName: 'PagBank', urlSlug: 'pagbank', authMode: 'oauth', credentialSchema: [] },
+  ],
+  configs: [],
+  activeProvider: null,
+} as unknown as MerchantSettingsView;
+
+function fakeClient(): PaymentsSettingsClient {
+  return {
+    getSettings: vi.fn().mockResolvedValue(VIEW),
+    getSetupGuide: vi.fn().mockResolvedValue(null),
+    setEnabled: vi.fn(),
+    saveCredentials: vi.fn(),
+  } as unknown as PaymentsSettingsClient;
+}
+
+describe('PaymentProviderSettings — adapter-declared URL slugs', () => {
+  it('opens the provider a slug segment names', async () => {
+    render(<PaymentProviderSettings client={fakeClient()} selectedProvider="infinite-pay" />);
+
+    expect(await screen.findByTestId('payments-provider-back')).toBeDefined();
+    await waitFor(() => expect(screen.queryByTestId('payments-provider-picker')).toBeNull());
+  });
+
+  it('still resolves the raw name, so a link minted before the slug existed lands', async () => {
+    render(<PaymentProviderSettings client={fakeClient()} selectedProvider="infinitepay" />);
+
+    expect(await screen.findByTestId('payments-provider-back')).toBeDefined();
+  });
+
+  it('reports the slug on selection, for the host to write into its URL verbatim', async () => {
+    const onProviderChange = vi.fn();
+    render(
+      <PaymentProviderSettings
+        client={fakeClient()}
+        selectedProvider={null}
+        onProviderChange={onProviderChange}
+      />,
+    );
+    const card = await screen.findByTestId('payments-provider-card-infinitepay');
+
+    card.click();
+
+    await waitFor(() => expect(onProviderChange).toHaveBeenCalledWith('infinite-pay'));
+  });
+
+  /**
+   * The OAuth callback's `?connected=` carries the raw NAME, and the host
+   * writes it into the URL before the catalog exists — it holds no map. The
+   * screen is right either way (the alias resolves); the ADDRESS BAR is what
+   * would stay wrong, and it is what a reload or a shared link uses. So once
+   * the catalog can spell the provider, the component asks the host to respell
+   * the segment — as a `replace`, so Voltar never revisits the alias.
+   */
+  it('asks the host to respell an alias segment to the canonical slug, as a replace', async () => {
+    const onProviderChange = vi.fn();
+    render(
+      <PaymentProviderSettings
+        client={fakeClient()}
+        selectedProvider="infinitepay"
+        onProviderChange={onProviderChange}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(onProviderChange).toHaveBeenCalledWith('infinite-pay', { replace: true }),
+    );
+  });
+
+  it('leaves a segment already spelled canonically alone', async () => {
+    const onProviderChange = vi.fn();
+    render(
+      <PaymentProviderSettings
+        client={fakeClient()}
+        selectedProvider="infinite-pay"
+        onProviderChange={onProviderChange}
+      />,
+    );
+
+    await screen.findByTestId('payments-provider-back');
+    expect(onProviderChange).not.toHaveBeenCalled();
+  });
+});

package/src/card/cpf.ts

@@ -0,0 +1,42 @@
+import { onlyDigits } from "./format";
+
+/**
+ * CPF (Brazilian taxpayer id) formatting + validation.
+ *
+ * PagBank requires the payer's CPF (`customer.tax_id`) on every PIX/card charge
+ * — the shopper's at checkout, and the owner's on the R$0,01 charge that proves
+ * their provider works (FUT-463). It is sent to PagBank as digits and — by
+ * design — never persisted in our database (data minimization).
+ */
+
+/** Progressive `000.000.000-00` mask for a partially-typed CPF. */
+export function formatCpf(value: string): string {
+  const d = onlyDigits(value).slice(0, 11);
+  let out = d.slice(0, 3);
+  if (d.length >= 4) out += `.${d.slice(3, 6)}`;
+  if (d.length >= 7) out += `.${d.slice(6, 9)}`;
+  if (d.length >= 10) out += `-${d.slice(9, 11)}`;
+  return out;
+}
+
+/** Verify the two CPF check digits (rejects all-same-digit sequences too). */
+function isValidCpf(value: string): boolean {
+  const d = onlyDigits(value);
+  if (d.length !== 11) return false;
+  if (/^(\d)\1{10}$/.test(d)) return false;
+
+  const checkDigit = (len: number): number => {
+    let sum = 0;
+    for (let i = 0; i < len; i += 1) sum += Number(d[i]) * (len + 1 - i);
+    const mod = (sum * 10) % 11;
+    return mod === 10 ? 0 : mod;
+  };
+
+  return checkDigit(9) === Number(d[9]) && checkDigit(10) === Number(d[10]);
+}
+
+/** Field validator: returns an error message, or `undefined` when valid. */
+export function validateCpf(value: string): string | undefined {
+  if (!onlyDigits(value)) return "CPF obrigatório.";
+  return isValidCpf(value) ? undefined : "CPF inválido.";
+}

package/src/card/fields.tsx

@@ -0,0 +1,254 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { useCheckoutComponents } from "../components/checkout/ui";
+
+import {
+  cvvLength,
+  formatCardNumber,
+  formatCvv,
+  formatExpiry,
+  validateCardNumber,
+  validateCvv,
+  validateExpiry,
+  validateHolder,
+  type CardBrand,
+} from "./format";
+import { NEW_CARD, type CardDetails, type CardFieldErrors, type SavedCard } from "./types";
+
+type SetCard = React.Dispatch<React.SetStateAction<CardDetails>>;
+type SetErrors = React.Dispatch<React.SetStateAction<CardFieldErrors>>;
+
+/** Saved-cards radio list, with a trailing "Novo cartão" option. */
+export function SavedCardsPicker({
+  savedCards,
+  selection,
+  onSelect,
+}: {
+  savedCards: SavedCard[];
+  selection: string;
+  onSelect: (id: string) => void;
+}): JSX.Element {
+  const { RadioGroup } = useCheckoutComponents();
+  return (
+    <RadioGroup
+      label="Cartão"
+      value={selection}
+      onChange={(_event, next) => onSelect(next)}
+      options={[
+        ...savedCards.map((saved) => ({
+          value: saved.id,
+          label: `${saved.brand} •••• ${saved.last4}`,
+          description: `Validade ${String(saved.expMonth).padStart(2, "0")}/${saved.expYear}`,
+        })),
+        { value: NEW_CARD, label: "Novo cartão", description: "Inserir outro cartão" },
+      ]}
+      dataTestId="saved-cards"
+    />
+  );
+}
+
+/** The card-number field — carries the detected-brand adornment. */
+function CardNumberInput({
+  card,
+  fieldErrors,
+  brand,
+  setCard,
+  setFieldErrors,
+}: {
+  card: CardDetails;
+  fieldErrors: CardFieldErrors;
+  brand: CardBrand;
+  setCard: SetCard;
+  setFieldErrors: SetErrors;
+}): JSX.Element {
+  const { Input, Text } = useCheckoutComponents();
+  return (
+    <Input
+      label="Número do cartão"
+      type="text"
+      inputMode="numeric"
+      variant="outlined"
+      size="md"
+      fullWidth
+      autoComplete="cc-number"
+      placeholder="0000 0000 0000 0000"
+      value={card.number}
+      error={Boolean(fieldErrors.number)}
+      helperText={fieldErrors.number}
+      endAdornment={
+        brand !== "Cartão" ? (
+          <Text variant="caption" size="xs" color="secondary" as="span">
+            {brand}
+          </Text>
+        ) : undefined
+      }
+      onChange={(event) => setCard((prev) => ({ ...prev, number: formatCardNumber(event.target.value) }))}
+      onBlur={() => setFieldErrors((prev) => ({ ...prev, number: validateCardNumber(card.number) }))}
+      data-testid="card-number"
+    />
+  );
+}
+
+/** The side-by-side expiry + CVV fields. */
+function ExpiryCvvFields({
+  card,
+  fieldErrors,
+  brand,
+  setCard,
+  setFieldErrors,
+}: {
+  card: CardDetails;
+  fieldErrors: CardFieldErrors;
+  brand: CardBrand;
+  setCard: SetCard;
+  setFieldErrors: SetErrors;
+}): JSX.Element {
+  const { Input } = useCheckoutComponents();
+  return (
+    <Box sx={{ display: "flex", gap: 2 }}>
+      <Input
+        label="Validade (MM/AA)"
+        type="text"
+        inputMode="numeric"
+        placeholder="MM/AA"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="cc-exp"
+        value={card.expiry}
+        error={Boolean(fieldErrors.expiry)}
+        helperText={fieldErrors.expiry}
+        onChange={(event) => setCard((prev) => ({ ...prev, expiry: formatExpiry(event.target.value) }))}
+        onBlur={() => setFieldErrors((prev) => ({ ...prev, expiry: validateExpiry(card.expiry) }))}
+        data-testid="card-expiry"
+      />
+      <Input
+        label="CVV"
+        type="text"
+        inputMode="numeric"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="cc-csc"
+        maxLength={cvvLength(brand)}
+        value={card.cvv}
+        error={Boolean(fieldErrors.cvv)}
+        helperText={fieldErrors.cvv}
+        onChange={(event) => setCard((prev) => ({ ...prev, cvv: formatCvv(event.target.value) }))}
+        onBlur={() => setFieldErrors((prev) => ({ ...prev, cvv: validateCvv(card.cvv, brand) }))}
+        data-testid="card-cvv"
+      />
+    </Box>
+  );
+}
+
+/**
+ * New-card entry form: number, holder, expiry+CVV, and the save-card opt-in.
+ *
+ * The opt-in appears only when the caller can act on it. A one-off card — the
+ * owner's, on the R$0,01 charge that proves their provider works — has nothing
+ * to save it for, and offering a dead checkbox there would be a promise the
+ * screen does not keep.
+ */
+export function NewCardForm({
+  card,
+  fieldErrors,
+  brand,
+  saveCard = false,
+  setCard,
+  setFieldErrors,
+  onSaveCardChange,
+}: {
+  card: CardDetails;
+  fieldErrors: CardFieldErrors;
+  brand: CardBrand;
+  saveCard?: boolean;
+  setCard: SetCard;
+  setFieldErrors: SetErrors;
+  onSaveCardChange?: (checked: boolean) => void;
+}): JSX.Element {
+  const { Input, Checkbox } = useCheckoutComponents();
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <CardNumberInput
+        card={card}
+        fieldErrors={fieldErrors}
+        brand={brand}
+        setCard={setCard}
+        setFieldErrors={setFieldErrors}
+      />
+      <Input
+        label="Nome impresso no cartão"
+        type="text"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="cc-name"
+        value={card.holder}
+        error={Boolean(fieldErrors.holder)}
+        helperText={fieldErrors.holder}
+        onChange={(event) => setCard((prev) => ({ ...prev, holder: event.target.value }))}
+        onBlur={() => setFieldErrors((prev) => ({ ...prev, holder: validateHolder(card.holder) }))}
+        data-testid="card-holder"
+      />
+      <ExpiryCvvFields
+        card={card}
+        fieldErrors={fieldErrors}
+        brand={brand}
+        setCard={setCard}
+        setFieldErrors={setFieldErrors}
+      />
+      {onSaveCardChange ? (
+        <Checkbox
+          label="Salvar cartão para próximas compras"
+          checked={saveCard}
+          onChange={(_event, checked) => onSaveCardChange(checked)}
+          data-testid="save-card"
+        />
+      ) : null}
+    </Box>
+  );
+}
+
+/** Sticky primary "Pagar" action — pinned to the bottom of the viewport on mobile. */
+export function CardPayBar({
+  totalLabel,
+  submitting,
+  onPay,
+}: {
+  totalLabel: string;
+  submitting: boolean;
+  onPay: () => void;
+}): JSX.Element {
+  const { Button } = useCheckoutComponents();
+  return (
+    <Box
+      data-testid="card-pay-bar"
+      sx={{
+        position: { xs: "sticky", sm: "static" },
+        bottom: 0,
+        zIndex: 2,
+        mx: { xs: -2, sm: 0 },
+        px: { xs: 2, sm: 0 },
+        py: { xs: 1.5, sm: 0 },
+        bgcolor: "background.paper",
+        borderTop: { xs: "1px solid", sm: "none" },
+        borderColor: "divider",
+      }}
+    >
+      <Button
+        variant="solid"
+        color="primary"
+        size="lg"
+        fullWidth
+        loading={submitting}
+        disabled={submitting}
+        onClick={onPay}
+        dataTestId="card-pay"
+      >
+        Pagar {totalLabel}
+      </Button>
+    </Box>
+  );
+}

package/src/card/format.ts

@@ -0,0 +1,103 @@
+/**
+ * Client-side card formatting + validation (FUT-58).
+ *
+ * Pure helpers with no imports — the card form uses them to format input live and
+ * to validate before tokenizing. They never transmit anything; the PAN is only
+ * checked locally (Luhn + brand + length) then handed to the tokenizer.
+ */
+
+export type CardBrand = "Visa" | "Mastercard" | "Amex" | "Elo" | "Cartão";
+
+/** Strip everything but digits. */
+export function onlyDigits(value: string): string {
+  return value.replace(/\D/g, "");
+}
+
+/** Best-effort brand detection from the leading digits. */
+export function detectBrand(digits: string): CardBrand {
+  if (/^4/.test(digits)) return "Visa";
+  if (/^(5[1-5]|2[2-7])/.test(digits)) return "Mastercard";
+  if (/^3[47]/.test(digits)) return "Amex";
+  if (/^6/.test(digits)) return "Elo";
+  return "Cartão";
+}
+
+/** Expected CVV length for a brand (Amex uses 4, everyone else 3). */
+export function cvvLength(brand: CardBrand): number {
+  return brand === "Amex" ? 4 : 3;
+}
+
+/** Format a PAN into brand-appropriate groups, e.g. `4242 4242 4242 4242`. */
+export function formatCardNumber(value: string): string {
+  const digits = onlyDigits(value).slice(0, 19);
+  const groups = detectBrand(digits) === "Amex" ? [4, 6, 5] : [4, 4, 4, 4, 3];
+  const parts: string[] = [];
+  let cursor = 0;
+  for (const size of groups) {
+    if (cursor >= digits.length) break;
+    parts.push(digits.slice(cursor, cursor + size));
+    cursor += size;
+  }
+  return parts.join(" ");
+}
+
+/** Format an expiry as `MM/YY`, inserting the slash after the month. */
+export function formatExpiry(value: string): string {
+  const digits = onlyDigits(value).slice(0, 4);
+  return digits.length <= 2 ? digits : `${digits.slice(0, 2)}/${digits.slice(2)}`;
+}
+
+/** Keep CVV digits only (max 4). */
+export function formatCvv(value: string): string {
+  return onlyDigits(value).slice(0, 4);
+}
+
+/** Luhn checksum — rejects mistyped/invalid card numbers. */
+function luhnValid(digits: string): boolean {
+  if (digits.length < 12) return false;
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i -= 1) {
+    let d = digits.charCodeAt(i) - 48; // '0' → 0
+    if (d < 0 || d > 9) return false;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+/** @returns an error message, or `undefined` when valid. */
+export function validateCardNumber(value: string): string | undefined {
+  const digits = onlyDigits(value);
+  if (!digits) return "Informe o número do cartão.";
+  if (digits.length < 13) return "Número de cartão incompleto.";
+  if (!luhnValid(digits)) return "Número de cartão inválido.";
+  return undefined;
+}
+
+export function validateHolder(value: string): string | undefined {
+  return value.trim().length < 2 ? "Informe o nome impresso no cartão." : undefined;
+}
+
+export function validateExpiry(value: string, now: Date = new Date()): string | undefined {
+  const match = /^(\d{2})\/(\d{2})$/.exec(value.trim());
+  if (!match) return "Validade incompleta (MM/AA).";
+  const mm = match[1];
+  const yy = match[2];
+  if (mm === undefined || yy === undefined) return "Validade incompleta (MM/AA).";
+  const month = Number(mm);
+  if (month < 1 || month > 12) return "Mês inválido.";
+  const endOfMonth = new Date(2000 + Number(yy), month, 0, 23, 59, 59, 999);
+  return endOfMonth.getTime() < now.getTime() ? "Cartão expirado." : undefined;
+}
+
+export function validateCvv(value: string, brand: CardBrand = "Cartão"): string | undefined {
+  const digits = onlyDigits(value);
+  if (!digits) return "Informe o CVV.";
+  const len = cvvLength(brand);
+  return digits.length === len ? undefined : `CVV deve ter ${len} dígitos.`;
+}

package/src/card/index.ts

@@ -0,0 +1,42 @@
+/**
+ * The shared card-entry surface: format/validate helpers, the form fields, and
+ * the browser tokenizer. Moved here from `@12-apps/spa-shared` with the buyer
+ * checkout (FUT-564) — the tokenization helpers follow the screens.
+ *
+ * Two consumers, on purpose. The storefront checkout takes a shopper's card;
+ * the admin's provider activation takes the OWNER's card for a R$0,01 proof
+ * charge (FUT-463). They must be the same form — a verification that exercised
+ * a different path would prove nothing about the path a shopper takes.
+ *
+ * The form components render through the checkout's slot contract (`ui.tsx`),
+ * so they carry no design system of their own: raw MUI by default, the host's
+ * primitives when a `CheckoutComponentsProvider` sits above them.
+ */
+
+export {
+  cvvLength,
+  detectBrand,
+  formatCardNumber,
+  formatCvv,
+  formatExpiry,
+  onlyDigits,
+  validateCardNumber,
+  validateCvv,
+  validateExpiry,
+  validateHolder,
+  type CardBrand,
+} from "./format";
+
+export { formatCpf, validateCpf } from "./cpf";
+
+export { CardPayBar, NewCardForm, SavedCardsPicker } from "./fields";
+
+export {
+  tokenizeCard,
+  tokenizeForCheckout,
+  tokenizerFor,
+  type CardTokenizationConfig,
+  type CardTokenizer,
+} from "./tokenize";
+
+export { NEW_CARD, type CardDetails, type CardFieldErrors, type CardToken, type SavedCard } from "./types";

package/src/card/stripe-token.ts

@@ -0,0 +1,81 @@
+/**
+ * Stripe browser-side card tokenization (FUT-698) — the `stripe-pm` scheme.
+ *
+ * The card is POSTed straight from the browser to Stripe's payment-methods
+ * endpoint, authenticated with the store's PUBLISHABLE key, and only the
+ * minted `pm_…` id comes back to us — the same PCI boundary the Stone path
+ * reaches through Pagar.me's tokens endpoint, and the same wire call
+ * Stripe.js itself makes under its iframe. Stripe.js is NOT loaded here on
+ * purpose: its public API only tokenizes cards typed into its own Elements
+ * iframe, and this checkout's card form is the shared {@link CardDetails}
+ * form every provider uses (`fields.tsx`) — the admin's vault flow
+ * (`apps/admin/.../stripe-sdk.ts`) keeps Elements where the UI was built
+ * around it.
+ *
+ * The `pm_…` id is what `stripe-charges.ts` sends as `payment_method` when it
+ * confirms the PaymentIntent server-side.
+ */
+
+import { err, ok, type Result } from "../result";
+
+import type { CardDetails, CardToken } from "./types";
+
+/** Stripe payment-methods endpoint — the publishable key authenticates. */
+const STRIPE_PAYMENT_METHODS_URL = "https://api.stripe.com/v1/payment_methods";
+
+/**
+ * Mint a Stripe PaymentMethod for a checkout card.
+ *
+ * `card` has already passed local validation; `pan`, `brand` and `last4` are
+ * derived by the caller so every scheme reports the same display metadata.
+ * A refusal carries Stripe's own message verbatim — a rejected tokenization
+ * is the provider's answer, and it must reach a human.
+ */
+export async function tokenizeWithStripe(
+  card: CardDetails,
+  pan: string,
+  publicKey: string,
+  brand: string,
+  last4: string,
+): Promise<Result<CardToken>> {
+  const match = /^(\d{2})\/(\d{2})$/.exec(card.expiry.trim());
+  if (!match) return err("Validade inválida ou expirada.");
+
+  // Stripe's API speaks form-encoding, not JSON.
+  const body = new URLSearchParams({
+    type: "card",
+    "card[number]": pan,
+    "card[exp_month]": String(Number(match[1])),
+    "card[exp_year]": `20${match[2]}`,
+    "card[cvc]": card.cvv.trim(),
+    "billing_details[name]": card.holder.trim(),
+  });
+
+  let response: Response;
+  try {
+    response = await fetch(STRIPE_PAYMENT_METHODS_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Bearer ${publicKey}`,
+      },
+      body: body.toString(),
+    });
+  } catch {
+    return err("Não foi possível contatar o provedor do cartão. Verifique sua conexão.");
+  }
+
+  const parsed = (await response.json().catch(() => null)) as {
+    id?: unknown;
+    error?: { message?: unknown };
+  } | null;
+  if (!response.ok || typeof parsed?.id !== "string") {
+    const reason =
+      typeof parsed?.error?.message === "string" ? parsed.error.message : JSON.stringify(parsed);
+    return err(
+      `O provedor recusou os dados do cartão (HTTP ${response.status}). ` +
+        `Resposta: ${String(reason).slice(0, 300)}`,
+    );
+  }
+  return ok({ token: parsed.id, brand, last4 });
+}