@12-apps/payments-frontend 3.45.0 → 3.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.45.0",
+  "version": "3.46.0",
   "type": "module",
   "sideEffects": false,
   "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.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.34.0",
+    "@12-apps/payments-backend": "^4.37.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/card/pagbank-test-cards.ts

@@ -7,7 +7,7 @@
  * encrypts them and only the encrypted blob leaves it.
  */
 interface PagBankTestCard {
-  scenario: "approved" | "declined";
+  scenario: "approved" | "declined" | "debit";
   brand: string;
   number: string;
   holder: string;
@@ -44,6 +44,22 @@ export const PAGBANK_TEST_CARDS: readonly PagBankTestCard[] = [
   },
 ];
 
+/**
+ * PagBank's 3-D Secure sandbox test card (FUT-3755), charged as DEBIT. The
+ * sandbox answers it by AMOUNT: authenticated for R$ 27,01
+ * (`PAGBANK_SANDBOX_DEBIT_CENTS`) it is AUTHENTICATED with no challenge and
+ * then PAID, so the evidence run needs no one to type a code.
+ */
+export const PAGBANK_3DS_TEST_CARD: PagBankTestCard = {
+  scenario: "debit",
+  brand: "VISA",
+  number: "4000000000002701",
+  holder: "Jose da Silva",
+  expMonth: "12",
+  expYear: TEST_EXPIRY_YEAR,
+  securityCode: "123",
+};
+
 /** `4539 62** **** 2097` — the first six and last four, as a receipt prints them. */
 export function maskTestCard(number: string): string {
   return `${number.slice(0, 4)} ${number.slice(4, 6)}** **** ${number.slice(-4)}`;

package/src/card/three-ds.ts

@@ -0,0 +1,166 @@
+import { ensurePagBankSdk } from "./tokenize";
+
+/**
+ * PagBank's 3-D Secure, in the buyer's browser (FUT-3754) — the step a DEBIT
+ * card charge cannot skip.
+ *
+ * Per "Criar e pagar com autenticação 3DS do PagBank": the SDK is pointed at a
+ * session the SERVER minted with the seller's token (`setUp`), then
+ * `authenticate3DS` runs the issuer's check — silently, or with a challenge the
+ * SDK draws itself — and answers an `id` that the debit charge carries as
+ * `authentication_method: { type: "THREEDS", id }`.
+ *
+ * What the statuses mean for a DEBIT card, and therefore what this answers:
+ *   AUTH_FLOW_COMPLETED    the id may be charged (authenticated or not — the
+ *                          issuer decides, PagBank still processes it)
+ *   AUTH_NOT_SUPPORTED     "para débito, a transação deve ser finalizada": the
+ *                          card cannot be charged as debit here
+ *   CHANGE_PAYMENT_METHOD  PagBank refused the authentication outright
+ * `REQUIRE_CHALLENGE` is intermediate — the SDK opens the challenge itself when
+ * no `beforeChallenge` is given — so it never reaches the caller.
+ */
+
+/** The SDK's request, field for field. Only the shape this package sends. */
+export interface PagBankThreeDSRequest {
+  data: {
+    customer: {
+      name: string;
+      email: string;
+      phones: { country: string; area: string; number: string; type: "MOBILE" }[];
+    };
+    paymentMethod: {
+      type: "DEBIT_CARD" | "CREDIT_CARD";
+      installments: number;
+      card: { encrypted: string };
+    };
+    amount: { value: number; currency: "BRL" };
+    billingAddress: PagBankThreeDSAddress;
+    dataOnly: false;
+  };
+}
+
+export interface PagBankThreeDSAddress {
+  street: string;
+  number: string;
+  complement?: string;
+  regionCode: string;
+  country: "BRA";
+  city: string;
+  postalCode: string;
+}
+
+export interface PagBankThreeDSResult {
+  status: "AUTH_FLOW_COMPLETED" | "AUTH_NOT_SUPPORTED" | "CHANGE_PAYMENT_METHOD" | "REQUIRE_CHALLENGE";
+  authenticationStatus?: "AUTHENTICATED" | "NOT_AUTHENTICATED";
+  id?: string;
+}
+
+/** Everything a debit authentication needs, in this package's own words. */
+export interface ThreeDSInput {
+  /** From the server's `3ds-session` answer. */
+  session: string;
+  environment: "SANDBOX" | "PRODUCTION";
+  /** The card, already encrypted with the seller's public key. */
+  encryptedCard: string;
+  amountCents: number;
+  customer: { name: string; email: string; phone: string };
+  billingAddress: Omit<PagBankThreeDSAddress, "country">;
+  /**
+   * Give up after this long, answering `ERROR`. Only for a run nobody types
+   * into (the homologation's no-challenge test card): a buyer's challenge may
+   * honestly take minutes, so the checkout passes none.
+   */
+  timeoutMs?: number;
+}
+
+/** Why a debit card could not be authenticated — a CODE; the caller words it. */
+export type ThreeDSFailure =
+  | "SDK_UNAVAILABLE"
+  | "NOT_SUPPORTED"
+  | "REFUSED"
+  | "INVALID_DATA"
+  | "ERROR";
+
+type ThreeDSOutcome =
+  | { ok: true; authenticationId: string; authenticated: boolean }
+  | { ok: false; failure: ThreeDSFailure };
+
+/**
+ * A Brazilian phone as the SDK's `{ country, area, number }`; null when it
+ * cannot be split. PagBank requires at least one MOBILE phone on the request.
+ */
+function mobileOf(phone: string): PagBankThreeDSRequest["data"]["customer"]["phones"][number] | null {
+  const digits = phone.replace(/\D/g, "");
+  const local = digits.length >= 12 && digits.startsWith("55") ? digits.slice(2) : digits;
+  if (local.length < 10 || local.length > 11) return null;
+  return { country: "55", area: local.slice(0, 2), number: local.slice(2), type: "MOBILE" };
+}
+
+/** The SDK's request, or null when the buyer's data cannot fill it. */
+export function threeDSRequestOf(input: ThreeDSInput): PagBankThreeDSRequest | null {
+  const mobile = mobileOf(input.customer.phone);
+  if (!mobile) return null;
+  return {
+    data: {
+      customer: { name: input.customer.name.trim(), email: input.customer.email.trim(), phones: [mobile] },
+      paymentMethod: { type: "DEBIT_CARD", installments: 1, card: { encrypted: input.encryptedCard } },
+      amount: { value: input.amountCents, currency: "BRL" },
+      billingAddress: {
+        ...input.billingAddress,
+        postalCode: input.billingAddress.postalCode.replace(/\D/g, ""),
+        country: "BRA",
+      },
+      dataOnly: false,
+    },
+  };
+}
+
+/** What the SDK answered, as this package's outcome. */
+export function threeDSOutcomeOf(result: PagBankThreeDSResult): ThreeDSOutcome {
+  if (result.status === "AUTH_FLOW_COMPLETED" && result.id) {
+    return {
+      ok: true,
+      authenticationId: result.id,
+      authenticated: result.authenticationStatus === "AUTHENTICATED",
+    };
+  }
+  if (result.status === "AUTH_NOT_SUPPORTED") return { ok: false, failure: "NOT_SUPPORTED" };
+  if (result.status === "CHANGE_PAYMENT_METHOD") return { ok: false, failure: "REFUSED" };
+  return { ok: false, failure: "ERROR" };
+}
+
+/** The SDK's answer, or a rejection once `ms` have passed (never, without `ms`). */
+function withTimeout<T>(pending: Promise<T>, ms: number | undefined): Promise<T> {
+  if (ms === undefined) return pending;
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("3-D Secure timed out")), ms);
+    pending.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      },
+    );
+  });
+}
+
+/** Authenticate a debit card with PagBank's SDK. Never throws. */
+export async function authenticatePagBankDebit(input: ThreeDSInput): Promise<ThreeDSOutcome> {
+  const request = threeDSRequestOf(input);
+  if (!request) return { ok: false, failure: "INVALID_DATA" };
+  if (!(await ensurePagBankSdk())) return { ok: false, failure: "SDK_UNAVAILABLE" };
+  const sdk = typeof window === "undefined" ? undefined : window.PagSeguro;
+  if (!sdk?.setUp || !sdk.authenticate3DS) return { ok: false, failure: "SDK_UNAVAILABLE" };
+  try {
+    sdk.setUp({ session: input.session, env: input.environment === "PRODUCTION" ? "PROD" : "SANDBOX" });
+    return threeDSOutcomeOf(await withTimeout(sdk.authenticate3DS(request), input.timeoutMs));
+  } catch {
+    // The SDK rejects with `{ detail: { httpStatus, traceId, errorMessages } }`
+    // — a bad field or an expired session. Neither can be fixed by the buyer
+    // retrying the same card in the same second.
+    return { ok: false, failure: "ERROR" };
+  }
+}

package/src/card/tokenize.ts

@@ -27,6 +27,7 @@ import { detectBrand, onlyDigits } from "./format";
 import { tokenizeWithStripe } from "./stripe-token";
 import type { CardDetails, CardToken } from "./types";
 import type { CardCopy } from "./copy";
+import type { PagBankThreeDSRequest, PagBankThreeDSResult } from "./three-ds";
 
 /** Test PAN that always declines (mirrors common sandbox decline cards). */
 const DECLINE_PAN = "4000000000000002";
@@ -56,6 +57,10 @@ declare global {
         expYear: string;
         securityCode: string;
       }): PagBankEncryptResult;
+      /** 3-D Secure (FUT-3754): point the SDK at a server-minted session. */
+      setUp?(params: { session: string; env: "SANDBOX" | "PROD" }): void;
+      /** 3-D Secure (FUT-3754): see `three-ds.ts` for the request and the answer. */
+      authenticate3DS?(request: PagBankThreeDSRequest): Promise<PagBankThreeDSResult>;
     };
   }
 }
@@ -66,7 +71,7 @@ declare global {
  * surfaces a friendly retry message.
  */
 let sdkLoad: Promise<boolean> | null = null;
-function ensurePagBankSdk(): Promise<boolean> {
+export function ensurePagBankSdk(): Promise<boolean> {
   if (typeof window === "undefined") return Promise.resolve(false);
   if (window.PagSeguro?.encryptCard) return Promise.resolve(true);
   sdkLoad ??= new Promise<boolean>((resolve) => {

package/src/components/checkout/client-context.tsx

@@ -53,6 +53,7 @@ function unboundClient(copy: CheckoutTransportCopy): CheckoutClient {
     beginVault: () => createCheckoutClient({ copy }).beginVault(),
     completeVault: (input) => createCheckoutClient({ copy }).completeVault(input),
     refreshBrowserKey: (input) => refreshCardPublicKey(input, copy),
+    threeDSecureSession: (input) => createCheckoutClient({ copy }).threeDSecureSession!(input),
   };
 }
 

package/src/components/checkout/debit-charge.ts

@@ -0,0 +1,60 @@
+import { authenticatePagBankDebit, type ThreeDSFailure } from "../../card/three-ds";
+import { err, ok, type Result } from "../../result";
+
+import type { CheckoutBillingAddress, PaymentListDebitCopy } from "./list/types";
+import type { CheckoutClient } from "./transport";
+import type { BuyerInfo, CheckoutOrder } from "./types";
+
+/**
+ * A DEBIT card's 3-D Secure, between the card's encryption and its charge
+ * (FUT-3754).
+ *
+ * The session is minted by the server for the order's own store (`/3ds-session`
+ * is payable-scoped), the provider's SDK authenticates the encrypted card in
+ * this browser — drawing the bank's challenge itself when the bank asks for
+ * one — and the id it answers is what the debit charge carries. Nothing is
+ * charged when the authentication fails: the buyer reads why and stays on the
+ * list with the card they typed.
+ */
+
+/** What the debit row hands the card charge: the address the bank checks, and the row's words. */
+export interface DebitAuthentication {
+  billingAddress: CheckoutBillingAddress;
+  copy: PaymentListDebitCopy;
+}
+
+/** The session a stub connection answers — authenticating it needs no SDK and no bank. */
+const STUB_SESSION = "stub-3ds-session";
+
+function failureWords(copy: PaymentListDebitCopy, failure: ThreeDSFailure): string {
+  if (failure === "NOT_SUPPORTED") return copy.notSupported;
+  if (failure === "REFUSED") return copy.refused;
+  return copy.failed;
+}
+
+/** The authentication id to charge the debit card with, or the buyer's reason why not. */
+export async function authenticateDebit(input: {
+  client: Pick<CheckoutClient, "threeDSecureSession">;
+  order: CheckoutOrder;
+  buyer: BuyerInfo;
+  encryptedCard: string;
+  debit: DebitAuthentication;
+}): Promise<Result<string>> {
+  const { copy } = input.debit;
+  const minted = await input.client.threeDSecureSession?.({ orderId: input.order.orderId });
+  if (!minted?.ok) return err(copy.failed);
+  if (minted.data.session === STUB_SESSION) return ok("stub-3ds");
+  const outcome = await authenticatePagBankDebit({
+    session: minted.data.session,
+    environment: minted.data.environment,
+    encryptedCard: input.encryptedCard,
+    amountCents: minted.data.amountCents,
+    customer: {
+      name: input.buyer.name ?? "",
+      email: input.buyer.email ?? "",
+      phone: input.buyer.phone ?? "",
+    },
+    billingAddress: input.debit.billingAddress,
+  });
+  return outcome.ok ? ok(outcome.authenticationId) : err(failureWords(copy, outcome.failure));
+}

package/src/components/checkout/debit-types.ts

@@ -0,0 +1,31 @@
+/**
+ * The debit card's wire and config shapes (FUT-3754) — their own module for
+ * the size gate on `types.ts`, which extends them.
+ */
+
+/** A chain entry's debit claim: absent (an older host) means no debit, as `wallets`. */
+export interface DebitDeclaration {
+  /** THIS entry charges a card as DEBIT, 3-D Secure authenticated. */
+  debit?: boolean;
+}
+
+/** What makes a card charge a debit one. Absent means credit, as every charge before it. */
+export interface DebitChargeFields {
+  funding?: "DEBIT";
+  /** The 3-D Secure authentication the buyer completed for this charge. */
+  authenticationId?: string;
+}
+
+/** `POST /3ds-session`'s answer: what the provider's 3-D Secure SDK runs on. */
+export interface ThreeDSecureSessionView {
+  provider: string;
+  session: string;
+  expiresAt: number;
+  environment: "SANDBOX" | "PRODUCTION";
+  /**
+   * What the charge will take, in cents — the figure the bank authenticates.
+   * The server's, never the browser's: an authentication for any other amount
+   * is refused or, worse, approves a debit the buyer never confirmed.
+   */
+  amountCents: number;
+}

package/src/components/checkout/list/charge-runners.tsx

@@ -19,6 +19,7 @@ import type { ChallengeScope } from "../card-outcome";
 import { useCheckoutCopy } from "../copy-context";
 import type { BuyerInfo, CheckoutOrder, CheckoutWalletType, OnCheckoutResolved } from "../types";
 import { useCardSubmit } from "../use-card-checkout";
+import type { DebitAuthentication } from "../debit-charge";
 import { useWalletCharge } from "../use-wallet-charge";
 
 import type { ListCard } from "./use-list-state";
@@ -60,10 +61,13 @@ export function CardRun({
   pollIntervalMs,
   onAccepted,
   onFailed,
+  debit,
 }: RunnerCallbacks & {
   order: CheckoutOrder;
   buyer: BuyerInfo;
   card: ListCard;
+  /** The debit row is the choice: authenticate, then charge as debit (FUT-3754). */
+  debit?: DebitAuthentication;
   config: CardTokenizationConfig;
   chain: readonly CardChainLink[];
   scope: ChallengeScope;
@@ -89,6 +93,7 @@ export function CardRun({
         number: card.complete ? undefined : fieldCopy.numberInvalid,
       }),
       setFieldErrors: card.setFieldErrors,
+      debit,
     },
     chain,
     scope,

package/src/components/checkout/list/choice-list.tsx

@@ -8,16 +8,19 @@ import { cardName, type OnlineRow } from "./choice";
 import type { ListChargeFailure } from "./charge-runners";
 import { OnlineContent, opensContent } from "./online-content";
 import { GroupHeading, OptionRow } from "./option-row";
-import type { CheckoutDoorOption, CheckoutOnlineChoice, PaymentListCopy } from "./types";
+import type { CheckoutDoorOption, PaymentListCopy } from "./types";
 import type { ListState } from "./use-list-state";
 
 /** An online row's label and hint, worded for what the store and the buyer hold. */
 function onlineWords(
-  method: CheckoutOnlineChoice,
+  row: OnlineRow,
   copy: PaymentListCopy,
   state: ListState,
   provider: string | null,
 ): { label: string; hint: string } {
+  const { method } = row;
+  // A debit row exists only with these words (`useDebitReady`).
+  if (row.funding === "DEBIT" && copy.debit) return { label: copy.debit.label, hint: copy.debit.hint };
   if (method === "PIX") return copy.pix;
   if (method === "GOOGLE_PAY") return copy.googlePay;
   if (method === "HAND_OFF") return { label: copy.handOff.label, hint: copy.handOff.hint(provider) };
@@ -28,6 +31,11 @@ function onlineWords(
   };
 }
 
+/** A row's identity — its method, and `-DEBIT` for the debit card (FUT-3754). */
+function rowKey(row: OnlineRow): string {
+  return row.funding ? `${row.method}-${row.funding}` : row.method;
+}
+
 /** The hint of a card the store declares and this browser cannot take — today's words (N9). */
 function useUnavailableHint(): string {
   return useCheckoutCopy().screens.method.unavailableHere;
@@ -50,23 +58,24 @@ interface RowProps {
 function OnlineOptionRow({ row, props }: { row: OnlineRow; props: RowProps }): JSX.Element {
   const { copy, state, provider } = props;
   const unavailable = useUnavailableHint();
-  const words = onlineWords(row.method, copy, state, provider);
-  const chosen = state.choice?.kind === "online" && state.choice.method === row.method;
+  const words = onlineWords(row, copy, state, provider);
+  const chosen = state.choice?.kind === "online" && state.choice.method === row.method && state.choice.funding === row.funding;
   return (
     <OptionRow
       name={props.name}
-      value={row.method}
+      value={rowKey(row)}
       chosen={chosen}
       disabled={row.disabled}
       label={words.label}
       hint={row.disabled ? unavailable : words.hint}
-      onChoose={() => state.choose({ kind: "online", method: row.method })}
-      testId={`list-option-${row.method}`}
+      onChoose={() => state.choose({ kind: "online", method: row.method, ...(row.funding ? { funding: row.funding } : {}) })}
+      testId={`list-option-${rowKey(row)}`}
     >
       {opensContent(row.method, state.asked, props.failure, props.covered) ? (
         <OnlineContent
         withConsent={!state.top}
         method={row.method}
+        debit={row.funding === "DEBIT"}
         asked={state.asked}
         buyer={props.buyer}
         onBuyerChange={props.onBuyerChange}
@@ -164,7 +173,7 @@ export function ChoiceList({
       {/* Each heading only over a group that has rows (a door-only store shows the door one alone). */}
       {state.rows.length > 0 ? (
         <Group id={`${base}-online`} heading={copy.onlineHeading}>
-          {state.rows.map((row) => <OnlineOptionRow key={row.method} row={row} props={props} />)}
+          {state.rows.map((row) => <OnlineOptionRow key={rowKey(row)} row={row} props={props} />)}
         </Group>
       ) : null}
       {door.length > 0 ? (

package/src/components/checkout/list/choice.ts

@@ -28,6 +28,8 @@ export interface OnlineRow {
   method: CheckoutOnlineChoice;
   /** A card the store declares but this browser cannot mint for — drawn, not choosable. */
   disabled: boolean;
+  /** The DEBIT card row (FUT-3754): the card again, authenticated by 3-D Secure. */
+  funding?: "DEBIT";
 }
 
 /** What the chain lets this browser offer, as the list needs it. */
@@ -37,6 +39,8 @@ export interface OnlineCapability {
   /** The methods the chain declares, or `null` while unknown (fails OPEN). */
   offered: PaymentMethod[] | null;
   cardUnavailable: boolean;
+  /** The debit row is offered: the head declares debit and the host gave an address (FUT-3754). */
+  debit?: boolean;
 }
 
 /**
@@ -51,6 +55,8 @@ export function onlineRows(cap: OnlineCapability): OnlineRow[] {
   const rows: OnlineRow[] = [];
   if (offers("PIX")) rows.push({ method: "PIX", disabled: false });
   if (offers("CARD")) rows.push({ method: "CARD", disabled: cap.cardUnavailable });
+  // Right under the credit card, and only where the store has debit on.
+  if (offers("CARD") && cap.debit) rows.push({ method: "CARD", funding: "DEBIT", disabled: cap.cardUnavailable });
   return rows;
 }
 
@@ -197,9 +203,12 @@ export function actionLabel(
   choice: CheckoutListChoice | null,
   door: CheckoutDoorOption | undefined,
   provider: string | null,
+  covered = false,
 ): string {
   if (!choice) return copy.actions.choose;
   if (choice.kind === "door") return door?.action ?? copy.actions.choose;
+  // A handoff leaves the store for a provider even at zero: it keeps its own verb.
+  if (covered && choice.method !== "HAND_OFF") return copy.actions.covered;
   const verbs: Record<CheckoutOnlineChoice, string> = {
     PIX: copy.actions.pix,
     CARD: copy.actions.card,

package/src/components/checkout/list/debit-copy.ts

@@ -0,0 +1,32 @@
+/**
+ * The debit card row's host inputs (FUT-3754) — their own module for the size
+ * gate on `types.ts`, which re-exports them.
+ */
+
+/** `PaymentListCopy.debit` — the debit card row and its 3-D Secure refusals. */
+export interface PaymentListDebitCopy {
+  /** "Cartão de débito". */
+  label: string;
+  /** "Digite os dados do cartão; o banco pode pedir uma confirmação". */
+  hint: string;
+  /** The card cannot be authenticated as debit here — try credit or Pix. */
+  notSupported: string;
+  /** The bank refused the authentication. */
+  refused: string;
+  /** The authentication could not run (a session, the SDK, the buyer's data). */
+  failed: string;
+}
+
+/**
+ * Where the buyer's card bill goes, as a debit's 3-D Secure needs it
+ * (FUT-3754). The host's delivery address is the one it has; Brazil only.
+ */
+export interface CheckoutBillingAddress {
+  street: string;
+  number: string;
+  complement?: string;
+  city: string;
+  /** The state's two letters — "SP". */
+  regionCode: string;
+  postalCode: string;
+}

package/src/components/checkout/list/en-US.ts

@@ -11,6 +11,13 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
     hintSaved: (card) => `${card} or another card`,
     hintNew: "Enter your card details",
   },
+  debit: {
+    label: "Debit card",
+    hint: "Your bank may ask you to confirm in its app",
+    notSupported: "This card can't be used as debit here. Try credit or Pix.",
+    refused: "Your bank didn't confirm the debit payment. Try another card or Pix.",
+    failed: "We couldn't confirm the debit with your bank. Try again.",
+  },
   googlePay: { label: "Google Pay", hint: "With the card saved in your Google account" },
   wallets: {
     heading: "Quick payment",
@@ -50,6 +57,7 @@ export const EN_US_PAYMENT_LIST_COPY: PaymentListCopy = {
     card: "Pay",
     pix: "Create Pix",
     googlePay: "Pay with Google Pay",
+    covered: "Pay with balance",
     handOff: (provider) => (provider ? `Go to ${provider}` : "Go to payment"),
   },
   payer: (name) => `Paying as ${name} · CPF ✓`,

package/src/components/checkout/list/list-face.tsx

@@ -5,6 +5,7 @@ import { cardChain, cardTokenization, handOffMethod } from "../method-capability
 import { PaymentErrorPanel } from "../payment-error-panel";
 import { UNRESOLVED_CODE } from "../failure-codes";
 import type { CheckoutBasketIdentity } from "../basket";
+import type { DebitAuthentication } from "../debit-charge";
 import type { BuyerContact, CheckoutProviderConfig, PaymentMethod } from "../types";
 import type { useCheckoutController } from "../use-checkout-controller";
 
@@ -173,7 +174,7 @@ function buttonFacts(props: ListFaceProps): { label: string; total: string; busy
   const door = chosenDoor(props);
   const online = state.choice?.kind === "online";
   return {
-    label: list.hold ? list.hold.action : pixBankLabel(list, state) ?? actionLabel(list.copy, state.choice, door, props.provider),
+    label: list.hold ? list.hold.action : pixBankLabel(list, state) ?? actionLabel(list.copy, state.choice, door, props.provider, coveredByHost(list)),
     total: door ? (door.totalLabel ?? props.total) : online ? onlineTotal(props) : props.total,
     busy: inFlight(props),
   };
@@ -226,6 +227,14 @@ function BarAction({ props, failure, act, onCancel, reason, returnFocus }: {
   return <PressButton props={props} act={act} reason={reason} returnFocus={returnFocus} />;
 }
 
+/** The debit card's 3-D Secure inputs when the debit row is the choice (FUT-3754), else none. */
+function debitOf(props: ListFaceProps): DebitAuthentication | undefined {
+  const { choice } = props.state;
+  const { billingAddress, copy } = props.list;
+  if (choice?.kind !== "online" || choice.funding !== "DEBIT" || !billingAddress || !copy.debit) return undefined;
+  return { billingAddress, copy: copy.debit };
+}
+
 /** The charge under way, once there is an order to run it against. */
 function Runners({ props, sheet, onFailed, onWalletFailed }: {
   props: ListFaceProps;
@@ -242,7 +251,7 @@ function Runners({ props, sheet, onFailed, onWalletFailed }: {
     onResolved: c.handleResolved, pollIntervalMs: props.pollIntervalMs, onAccepted: charge.accepted, onFailed,
   };
   if (charge.kind === "CARD") {
-    return <CardRun {...common} card={props.state.card} config={cardTokenization(config)} chain={cardChain(config)} />;
+    return <CardRun {...common} card={props.state.card} config={cardTokenization(config)} chain={cardChain(config)} debit={debitOf(props)} />;
   }
   if (charge.kind !== null && charge.kind === sheet?.type) return <WalletRun {...common} onFailed={onWalletFailed} sheet={sheet} />;
   return null;

package/src/components/checkout/list/online-content.tsx

@@ -86,6 +86,30 @@ function focusCardNumber(scope: HTMLElement | null): void {
   scope?.querySelector<HTMLInputElement>('input[data-testid="card-number"]')?.focus();
 }
 
+/**
+ * The card's own fields: the saved cards, then the form for a new one. A debit
+ * card (FUT-3754) is always typed — a saved card is charged as credit — and is
+ * never offered for saving.
+ */
+function CardFields({ card, copy, debit }: { card: ListCard; copy: PaymentListCopy; debit: boolean }): JSX.Element {
+  return (
+    <>
+      {debit ? null : <SavedChips card={card} copy={copy} />}
+      {card.selection === NEW_CARD ? (
+        <NewCardForm
+          card={card.card}
+          fieldErrors={card.fieldErrors}
+          brand={detectBrand(onlyDigits(card.card.number))}
+          saveCard={card.saveCard}
+          setCard={card.setCard}
+          setFieldErrors={card.setFieldErrors}
+          onSaveCardChange={debit ? undefined : card.setSaveCard}
+        />
+      ) : null}
+    </>
+  );
+}
+
 /**
  * What opens inside a chosen ONLINE option, top to bottom (M11, FN:180-202):
  * the buyer's missing details, then — for the card — the saved-card chips and
@@ -103,8 +127,11 @@ export function OnlineContent({
   failure,
   covered = false,
   withConsent = true,
+  debit = false,
 }: {
   method: "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
+  /** The debit card row (FUT-3754): no saved cards, and nothing to save. */
+  debit?: boolean;
   asked: readonly CheckoutCustomerField[];
   buyer: BuyerInfo;
   onBuyerChange: (buyer: BuyerInfo) => void;
@@ -130,18 +157,7 @@ export function OnlineContent({
         onComplete={isCard ? () => focusCardNumber(scope.current) : undefined}
         withConsent={withConsent}
       />
-      {isCard ? <SavedChips card={card} copy={copy} /> : null}
-      {isCard && card.selection === NEW_CARD ? (
-        <NewCardForm
-          card={card.card}
-          fieldErrors={card.fieldErrors}
-          brand={detectBrand(onlyDigits(card.card.number))}
-          saveCard={card.saveCard}
-          setCard={card.setCard}
-          setFieldErrors={card.setFieldErrors}
-          onSaveCardChange={card.setSaveCard}
-        />
-      ) : null}
+      {isCard ? <CardFields card={card} copy={copy} debit={debit} /> : null}
       {failure ? <ChargeFailure message={failure.message} unresolved={failure.code === UNRESOLVED_CODE} /> : null}
     </Box>
   );

package/src/components/checkout/list/payment-list-step.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useState, type JSX, type ReactNode } f
 
 import type { CheckoutBasketIdentity } from "../basket";
 import { CartChangedBoundary } from "../cart-changed";
+import { useCheckoutClientApi } from "../client-context";
 import { displayTotals } from "../checkout-totals";
 import type { CheckoutSummaryLine } from "../payment-summary";
 import { usePaymentPixStage } from "../payment-step-layout";
@@ -144,6 +145,16 @@ function ListFaceFor({ props, state, charge, cap, onHandOff, reveal }: {
   );
 }
 
+/**
+ * Everything a debit row needs besides the provider's claim (FUT-3754): the
+ * host's billing address, its words for the row, and a client that can ask for
+ * the 3-D Secure session. Missing any one, there is no row.
+ */
+function useDebitReady(list: CheckoutPaymentList): boolean {
+  const client = useCheckoutClientApi();
+  return Boolean(list.billingAddress) && list.copy.debit !== undefined && client.threeDSecureSession !== undefined;
+}
+
 /**
  * The Pagamento step as ONE list (FUT-3591, FUT-3592) — see `./types.ts`.
  *
@@ -156,7 +167,8 @@ function ListFaceFor({ props, state, charge, cap, onHandOff, reveal }: {
 export function PaymentListStep(props: PaymentListStepProps): JSX.Element {
   const { c, list } = props;
   const config = props.providerConfig ?? null;
-  const cap = useListCapability(config, list.totalCents, props.validateApplePayMerchant);
+  const debitReady = useDebitReady(list);
+  const cap = useListCapability(config, list.totalCents, props.validateApplePayMerchant, debitReady);
   const reveal = useReveal(c, props.defaultBuyer);
   const { revealed } = reveal;
   const state = useListState({

package/src/components/checkout/list/pt-BR.ts

@@ -27,6 +27,13 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
     hintSaved: (card) => `${card} ou outro cartão`,
     hintNew: "Digite os dados do cartão",
   },
+  debit: {
+    label: "Cartão de débito",
+    hint: "O banco pode pedir confirmação no app",
+    notSupported: "Esse cartão não pode ser usado no débito aqui. Tente no crédito ou no Pix.",
+    refused: "O banco não confirmou o pagamento no débito. Tente outro cartão ou o Pix.",
+    failed: "O banco não confirmou o débito agora. Tente de novo.",
+  },
   googlePay: { label: "Google Pay", hint: "Com o cartão salvo no seu Google" },
   wallets: {
     heading: "Pagamento rápido",
@@ -66,6 +73,7 @@ export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
     card: "Pagar",
     pix: "Gerar Pix",
     googlePay: "Pagar com Google Pay",
+    covered: "Pagar com saldo",
     handOff: (provider) => (provider ? `Ir para ${the(provider)}` : "Ir para o pagamento"),
   },
   payer: (name) => `Pagando como ${name} · CPF ✓`,

package/src/components/checkout/list/types.ts

@@ -20,6 +20,10 @@
  */
 import type { ReactNode } from "react";
 
+import type { CheckoutBillingAddress, PaymentListDebitCopy } from "./debit-copy";
+
+export type { CheckoutBillingAddress, PaymentListDebitCopy };
+
 /**
  * What a door option's `content` function is handed (FUT-3715).
  *
@@ -103,7 +107,7 @@ export type CheckoutOnlineChoice = "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
 
 /** What the buyer has chosen in the list. */
 export type CheckoutListChoice =
-  | { kind: "online"; method: CheckoutOnlineChoice }
+  | { kind: "online"; method: CheckoutOnlineChoice; funding?: "DEBIT" }
   | { kind: "door"; id: string };
 
 /**
@@ -214,6 +218,8 @@ export interface CheckoutPaymentList {
    * wide, the bar otherwise. The Pix screen and the hand-off keep their bar.
    */
   summaryTarget?: HTMLElement | null;
+  /** The billing address a DEBIT card's 3-D Secure needs (FUT-3754); none ⇒ no debit row. */
+  billingAddress?: CheckoutBillingAddress | null;
 }
 
 /** The six banks the Pix face offers to open, in the prototype's order. */
@@ -286,6 +292,8 @@ export interface PaymentListCopy {
     /** "Digite os dados do cartão". */
     hintNew: string;
   };
+  /** The DEBIT card row's words (FUT-3754). A pack without them offers no debit row. */
+  debit?: PaymentListDebitCopy;
   /**
    * @deprecated Google Pay is no longer a row (FUT-3685): it is a button in
    * the "PAGAMENTO RÁPIDO" block — see {@link PaymentListCopy.wallets}. Kept so
@@ -354,6 +362,8 @@ export interface PaymentListCopy {
     card: string;
     pix: string;
     googlePay: string;
+    /** The bar's verb when the host's balance pays the whole amount. */
+    covered: string;
     handOff: (provider: string | null) => string;
   };
   /** "Pagando como Ana Teste · CPF ✓". */

package/src/components/checkout/list/use-capability.ts

@@ -71,12 +71,21 @@ function googleSheet(config: CheckoutProviderConfig | null, client: GooglePaymen
   return params && client ? { client, params } : null;
 }
 
+/**
+ * The debit row (FUT-3754): the card is here, the head declares debit, and the
+ * host gave the address PagBank's 3-D Secure refuses to run without.
+ */
+function debitOffered(config: CheckoutProviderConfig | null, card: boolean, hasBillingAddress: boolean): boolean {
+  return card && hasBillingAddress && config?.chain?.[0]?.debit === true;
+}
+
 /** {@link useListCapability}'s answer, from what it read. */
 function capabilityOf(
   config: CheckoutProviderConfig | null,
   client: GooglePaymentsClient | null,
   price: { priced: boolean; repricing: boolean },
   port: ListApplePay["validateMerchant"] | undefined,
+  hasBillingAddress: boolean,
 ): ListCapability {
   const offered = offeredMethods(config);
   const cardUnavailable = !cardPathAvailable(config);
@@ -89,6 +98,7 @@ function capabilityOf(
     handOff,
     offered,
     cardUnavailable,
+    debit: debitOffered(config, card, hasBillingAddress),
     wallets: walletsShown(card && (price.priced || price.repricing), google, apple),
     googlePay: live ? google : null,
     applePay: live ? apple : null,
@@ -114,10 +124,12 @@ export function useListCapability(
   /** The host's price for the sheets — no price (or zero), no wallet. */
   totalCents: number | undefined,
   validateApplePayMerchant?: ListApplePay["validateMerchant"],
+  /** The host gave the billing address a debit card's 3-D Secure needs. */
+  hasBillingAddress = false,
 ): ListCapability {
-  const declared = googlePayConfig(config) !== null;
+  const declared = googlePayConfig(config);
   // `null` tells the client hook not to load pay.js at all.
-  const client = useGooglePayClient(declared ? undefined : null, "TEST");
+  const client = useGooglePayClient(declared ? undefined : null, declared?.environment ?? "TEST");
   const { priced, repricing } = useRepricing(totalCents);
   // The port is read at the press, through a ref: a host passing a new
   // function each render must not rebuild the capability (and the wallets'
@@ -130,7 +142,7 @@ export function useListCapability(
     return current ? current(validationURL) : Promise.reject(new Error("no merchant validation port"));
   }, []);
   return useMemo(
-    () => capabilityOf(config, client, { priced, repricing }, hasPort ? stablePort : undefined),
-    [config, client, priced, repricing, hasPort, stablePort],
+    () => capabilityOf(config, client, { priced, repricing }, hasPort ? stablePort : undefined, hasBillingAddress),
+    [config, client, priced, repricing, hasPort, stablePort, hasBillingAddress],
   );
 }

package/src/components/checkout/list/use-list-state.ts

@@ -92,6 +92,25 @@ function reopenedSelection(cards: readonly SavedCard[], fresh: boolean): string
   return fresh ? null : head.id;
 }
 
+/**
+ * The card selection a choice opens on, or `undefined` when it opens no card.
+ * Coming back to the card from another option starts on the head of the saved
+ * list again (FN:420), or on the fields when there is none; what was typed in
+ * them is kept. The debit row always types one: a saved card is charged as
+ * credit (FUT-3754).
+ */
+function cardOpenedBy(
+  previous: CheckoutListChoice | null,
+  next: CheckoutListChoice,
+  cards: readonly SavedCard[],
+  fresh: boolean,
+): string | null | undefined {
+  if (next.kind !== "online" || next.method !== "CARD") return undefined;
+  const sameRow = previous?.kind === "online" && previous.method === "CARD" && previous.funding === next.funding;
+  if (sameRow) return undefined;
+  return next.funding === "DEBIT" ? NEW_CARD : reopenedSelection(cards, fresh);
+}
+
 /**
  * The one list's state (FUT-3591). Picking an option changes THIS and nothing
  * else: no order, no charge, no request — the bar's button is the only thing
@@ -133,20 +152,20 @@ export function useListState(input: {
     (next: CheckoutListChoice) => {
       touched.current = true;
       setChoice((previous) => {
-        // Coming back to the card from another option starts on the head of
-        // the saved list again (FN:420), or on the fields when there is none;
-        // what was typed in them is kept.
-        const reopensCard = next.kind === "online" && next.method === "CARD" && !(previous?.kind === "online" && previous.method === "CARD");
-        if (reopensCard) setSelection(reopenedSelection(cards, input.fresh));
+        const selection = cardOpenedBy(previous, next, cards, input.fresh);
+        if (selection !== undefined) setSelection(selection);
         return next;
       });
     },
     [cards, setSelection, input.fresh],
   );
   // A choice the chain no longer offers (a config that resolved to a hand-off
-  // store after the card was preselected) is no choice at all.
+  // store after the card was preselected) is no choice at all. Matched on the
+  // funding too: a debit row that went away (its billing address with it) must
+  // not leave a choice the card charge would run as CREDIT (FUT-3754).
   useEffect(() => {
-    if (choice?.kind === "online" && !rows.some((row) => row.method === choice.method && !row.disabled)) setChoice(null);
+    if (choice?.kind !== "online") return;
+    if (!rows.some((row) => row.method === choice.method && row.funding === choice.funding && !row.disabled)) setChoice(null);
   }, [choice, rows]);
   const { onChoiceChange } = input;
   useEffect(() => {

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

@@ -158,13 +158,15 @@ function toCardLink(link: CheckoutChainLink): CardChainLink {
  */
 export function googlePayConfig(
   config: CheckoutProviderConfig | null,
-): { gateway: string; gatewayMerchantId: string } | null {
+): { gateway: string; gatewayMerchantId: string; environment: "TEST" | "PRODUCTION" } | null {
   const head = config?.chain?.[0];
   if (!head?.methods.includes("CARD")) return null;
   if (!head.wallets?.includes("GOOGLE_PAY")) return null;
   const params = head.googlePay;
   if (!params?.gatewayMerchantId) return null;
-  return { gateway: params.gateway, gatewayMerchantId: params.gatewayMerchantId };
+  // The connection's own environment (FUT-3756): a production store must never
+  // mint Google's test tokens. Absent ⇒ TEST, as before it was published.
+  return { gateway: params.gateway, gatewayMerchantId: params.gatewayMerchantId, environment: params.environment ?? "TEST" };
 }
 
 /**

package/src/components/checkout/transport.ts

@@ -20,6 +20,7 @@ import type { BuyerVaultSession, VaultedCardDisplay } from "@12-apps/payments-ba
 import type { SavedCard } from "../../card";
 import { err, ok, type Result } from "../../result";
 
+import type { ThreeDSecureSessionView } from "./debit-types";
 import type { CheckoutTransportCopy } from "./screens-copy";
 
 import type {
@@ -127,6 +128,11 @@ export interface CheckoutClient {
    */
   completeVault(input: CompleteVaultInput): Promise<Result<VaultedCardDisplay>>;
   refreshBrowserKey(input: { orderId: string }): Promise<Result<{ publicKey: string | null }>>;
+  /**
+   * `POST /3ds-session` (FUT-3754): the 3-D Secure session a debit card is
+   * authenticated on. Optional — a host without the row offers no debit.
+   */
+  threeDSecureSession?(input: { orderId: string }): Promise<Result<ThreeDSecureSessionView>>;
 }
 
 /** Envelope the API routes return: `{ data }` on success, `{ error }` on failure. */
@@ -192,6 +198,11 @@ function returnedSettlement(): Record<string, string> {
   };
 }
 
+/** A POST naming the payable — the body every payable-scoped row takes. */
+function orderBody(input: { orderId: string }): RequestInit {
+  return { method: "POST", body: JSON.stringify({ orderId: input.orderId }) };
+}
+
 /** The ambient `fetch`, wrapped so it is never invoked detached from its global. */
 function ambientFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
   return globalThis.fetch(input, init);
@@ -211,6 +222,8 @@ function flatChargeBody(input: ChargeCardInput): string {
     saveCard: input.saveCard,
     cardMeta: input.cardMeta,
     taxId: input.taxId,
+    ...(input.funding ? { funding: input.funding } : {}),
+    ...(input.authenticationId ? { authenticationId: input.authenticationId } : {}),
   });
 }
 
@@ -321,10 +334,8 @@ export function createCheckoutClient(transport: CheckoutTransport): CheckoutClie
         body: completeVaultBody(input),
       }),
 
-    refreshBrowserKey: (input) =>
-      call<{ publicKey: string | null }>("/refresh-key", {
-        method: "POST",
-        body: JSON.stringify({ orderId: input.orderId }),
-      }),
+    refreshBrowserKey: (input) => call<{ publicKey: string | null }>("/refresh-key", orderBody(input)),
+
+    threeDSecureSession: (input) => call<ThreeDSecureSessionView>("/3ds-session", orderBody(input)),
   };
 }

package/src/components/checkout/types.ts

@@ -7,7 +7,7 @@
  * this folder. The host-side halves — the cart, the catalog, order CREATION — stay in the
  * host app and reach the flow through the ports declared on `CheckoutFlowProps`.
  */
-
+import type { DebitChargeFields, DebitDeclaration } from "./debit-types";
 import type { CheckoutDecline, CheckoutDeclineReason } from "./decline";
 
 /** Payment methods offered at checkout. Mirrors `Payment.method` (FUT-42). */
@@ -215,7 +215,7 @@ export interface SavedCardMeta {
 }
 
 /** Input to charge a tokenized card against an order. */
-export interface ChargeCardInput {
+export interface ChargeCardInput extends DebitChargeFields {
   orderId: string;
   /** A fresh token, or a saved card's id for reuse. */
   token: string;
@@ -271,7 +271,7 @@ export interface CheckoutCustomerField {
  * 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 {
+export interface CheckoutChainLink extends DebitDeclaration {
   provider: string;
   /**
    * The provider's own name as a BUYER should read it ("InfinitePay"), which
@@ -322,7 +322,7 @@ export interface CheckoutChainLink {
    * — the button must not render, because a token minted against a missing id
    * charges nobody.
    */
-  googlePay?: { gateway: string; gatewayMerchantId: string | null } | null;
+  googlePay?: { gateway: string; gatewayMerchantId: string | null; environment?: "TEST" | "PRODUCTION" } | null;
   /**
    * The buyer screen THIS provider's flow needs (FUT-596) — an opaque id the
    * adapter declares and `providers/registry.ts` resolves to a component.

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

@@ -14,7 +14,7 @@ import {
   type CardTokenizationConfig,
   type SavedCard,
 } from "../../card";
-import { ok, type Result } from "../../result";
+import { err, ok, type Result } from "../../result";
 
 import {
   resolveNewCardToken,
@@ -27,7 +27,9 @@ import { useCheckoutClientApi } from "./client-context";
 import { useCheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
 import { useOneClickArmed, useOneClickPay } from "./one-click";
-import type { BuyerInfo, CheckoutOrder, OnCheckoutResolved, OrderStatus } from "./types";
+import type { BuyerInfo, ChargeCardInput, CheckoutOrder, OnCheckoutResolved, OrderStatus } from "./types";
+import { authenticateDebit, type DebitAuthentication } from "./debit-charge";
+import type { CheckoutClient } from "./transport";
 import { usePaymentPolling } from "./use-payment-polling";
 import type { CardCopy } from "../../card/copy";
 import { useCheckoutCopy } from "./copy-context";
@@ -80,6 +82,32 @@ interface CardFormState {
   saveCard: boolean;
   validate: () => CardFieldErrors;
   setFieldErrors: React.Dispatch<React.SetStateAction<CardFieldErrors>>;
+  /** Charge the card as DEBIT, after its 3-D Secure (FUT-3754). */
+  debit?: DebitAuthentication;
+}
+
+/**
+ * The charge's body. A DEBIT card (FUT-3754) is 3-D Secure authenticated first
+ * and charged with the head's own instrument only — the authentication is that
+ * provider's — so no per-provider map, and nothing saved.
+ */
+async function chargeBodyOf(
+  form: CardFormState,
+  instruments: CardInstruments,
+  ctx: { client: CheckoutClient; order: CheckoutOrder; buyer: BuyerInfo },
+): Promise<Result<ChargeCardInput>> {
+  const body: ChargeCardInput = {
+    orderId: ctx.order.orderId,
+    token: instruments.token,
+    tokensByProvider: instruments.tokensByProvider,
+    saveCard: form.usingNewCard && form.saveCard,
+    cardMeta: instruments.cardMeta,
+    taxId: ctx.buyer.taxId,
+  };
+  if (!form.debit) return ok(body);
+  const authenticated = await authenticateDebit({ ...ctx, encryptedCard: instruments.token, debit: form.debit });
+  if (!authenticated.ok) return authenticated;
+  return ok({ ...body, tokensByProvider: undefined, saveCard: false, funding: "DEBIT", authenticationId: authenticated.data });
 }
 
 /** The submit slice of {@link useCardCheckout}. */
@@ -223,20 +251,13 @@ export function useCardSubmit(
       refreshKey: client.refreshBrowserKey,
       copy: cardCopy,
     });
-    if (!resolved.ok) {
-      setError(resolved.error);
+    const body = resolved.ok ? await chargeBodyOf(form, resolved.data, { client, order, buyer }) : err<ChargeCardInput>(resolved.error);
+    if (!body.ok) {
+      setError(body.error);
       setSubmitting(false);
       return;
     }
-
-    const charged = await client.charge({
-      orderId: order.orderId,
-      token: resolved.data.token,
-      tokensByProvider: resolved.data.tokensByProvider,
-      saveCard: form.usingNewCard && form.saveCard,
-      cardMeta: resolved.data.cardMeta,
-      taxId: buyer.taxId,
-    });
+    const charged = await client.charge(body.data);
     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

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

@@ -128,6 +128,7 @@ function WalletButtons({
         <GooglePayButton
           order={props.order}
           params={googlePay}
+          environment={googlePay.environment}
           onKey={(key) => void wallet.payWithKey("GOOGLE_PAY", key)}
           onError={onSheetError}
           onReady={() => setGoogleReady(true)}

package/src/components/platform/HomologacaoEvidenceCard.tsx

@@ -4,12 +4,16 @@ import { Alert, Box, Button, LinearProgress, Stack, Typography } from '@mui/mate
 import { useState, type ReactNode } from 'react';
 
 import type {
+  BrowserCardFailure,
   BrowserCardResult,
+  DebitTestData,
   EvidenceSummary,
   PaymentEnvironment,
+  ThreeDSecureSession,
 } from '@12-apps/payments-backend';
 
-import { maskTestCard, PAGBANK_TEST_CARDS } from '../../card/pagbank-test-cards';
+import { maskTestCard, PAGBANK_3DS_TEST_CARD, PAGBANK_TEST_CARDS } from '../../card/pagbank-test-cards';
+import { authenticatePagBankDebit, type ThreeDSFailure } from '../../card/three-ds';
 import { encryptPagBankCard } from '../../card/tokenize';
 import { CARD_SX, TAP_SX } from './ConnectEnvironmentCard';
 import type { PlatformHomologacaoCopy } from './copy';
@@ -21,7 +25,8 @@ import { PlatformCopyProvider, usePlatformCopy } from './copy-context';
  *
  * The one thing this card does itself is the part that has to happen in a
  * browser: encrypting PagBank's official TEST cards with the seller's public
- * key, through the same SDK call the checkout makes. Everything else is the
+ * key, through the same SDK call the checkout makes, and authenticating the
+ * 3DS test card with PagBank's SDK for the debit scenario (FUT-3755). Everything else is the
  * host's — each callback is a call to its own mounted routes — and what the
  * file says is decided by the server, from what was recorded. This card shows
  * the counts it answered and never infers a result of its own.
@@ -47,8 +52,18 @@ export interface HomologacaoEvidenceCardProps {
   connectOutcome?: 'connected' | 'failed' | null;
   /** Start the authorization: the host mints the state and navigates away. */
   onConnect: () => Promise<void>;
-  /** Phase 1 — the seller's public key, null when it could not be minted. */
-  onPrepare: () => Promise<{ runId: string; publicKey: string | null }>;
+  /**
+   * Phase 1 — the seller's public key and the debit card's 3DS session, each
+   * null when it could not be minted (the session absent on a host that does
+   * not mint one yet: the debit scenarios then stay pending, saying why).
+   */
+  onPrepare: () => Promise<{
+    runId: string;
+    publicKey: string | null;
+    threeDSSession?: ThreeDSecureSession | null;
+    /** What the debit card is authenticated with — the server's, so the amount matches what it charges. */
+    debitTest?: DebitTestData;
+  }>;
   /** Phase 2 — raise the orders with the encrypted cards. */
   onRun: (runId: string, cards: BrowserCardResult[]) => Promise<void>;
   /** Build and deliver the file; resolves to the counts it holds. */
@@ -58,29 +73,69 @@ export interface HomologacaoEvidenceCardProps {
 type Phase = 'idle' | 'preparing' | 'encrypting' | 'running' | 'downloading';
 type ActivePhase = Exclude<Phase, 'idle'>;
 
-/** Each official test card, encrypted — or the code saying why it is not. */
-async function encryptTestCards(publicKey: string | null): Promise<BrowserCardResult[]> {
+type TestCard = typeof PAGBANK_3DS_TEST_CARD;
+
+/** One official test card, encrypted — or the code saying why it is not. */
+async function encryptTestCard(card: TestCard, publicKey: string | null): Promise<BrowserCardResult> {
+  const base = { scenario: card.scenario, brand: card.brand, masked: maskTestCard(card.number) };
+  if (!publicKey) return { ...base, encrypted: null, failure: 'NO_PUBLIC_KEY' };
+  const encrypted = await encryptPagBankCard({
+    publicKey,
+    holder: card.holder,
+    number: card.number,
+    expMonth: card.expMonth,
+    expYear: card.expYear,
+    securityCode: card.securityCode,
+  });
+  return 'encrypted' in encrypted
+    ? { ...base, encrypted: encrypted.encrypted }
+    : { ...base, encrypted: null, failure: encrypted.failure };
+}
+
+/** The SDK's 3DS failure, as the code the evidence copy words. */
+const THREEDS_FAILURES: Readonly<Record<ThreeDSFailure, BrowserCardFailure>> = {
+  SDK_UNAVAILABLE: 'SDK_UNAVAILABLE',
+  NOT_SUPPORTED: 'THREEDS_NOT_SUPPORTED',
+  REFUSED: 'THREEDS_REFUSED',
+  INVALID_DATA: 'THREEDS_FAILED',
+  ERROR: 'THREEDS_FAILED',
+};
+
+/**
+ * The 3DS test card, encrypted and authenticated with PagBank's SDK for the
+ * amount the server will charge — or the code saying where it stopped. The
+ * server charges it as DEBIT only with the authentication id.
+ */
+async function authenticateDebitTestCard(
+  publicKey: string | null,
+  session: ThreeDSecureSession | null,
+  test: DebitTestData | undefined,
+): Promise<BrowserCardResult> {
+  const encrypted = await encryptTestCard(PAGBANK_3DS_TEST_CARD, publicKey);
+  if (!encrypted.encrypted) return encrypted;
+  if (!session || !test) return { ...encrypted, failure: 'NO_THREEDS_SESSION' };
+  const outcome = await authenticatePagBankDebit({
+    session: session.session,
+    environment: session.environment,
+    encryptedCard: encrypted.encrypted,
+    amountCents: test.amountCents,
+    customer: test.customer,
+    billingAddress: test.billingAddress,
+    // The test card never challenges; a hung SDK must not hold the Pix and
+    // credit scenarios back with it.
+    timeoutMs: 60_000,
+  });
+  return outcome.ok
+    ? { ...encrypted, authenticationId: outcome.authenticationId, authenticated: outcome.authenticated }
+    : { ...encrypted, failure: THREEDS_FAILURES[outcome.failure] };
+}
+
+/** Each official test card, encrypted, then the debit one authenticated (FUT-3755). */
+async function prepareTestCards(prepared: Awaited<ReturnType<HomologacaoEvidenceCardProps['onPrepare']>>): Promise<BrowserCardResult[]> {
+  const { publicKey } = prepared;
   const results: BrowserCardResult[] = [];
-  for (const card of PAGBANK_TEST_CARDS) {
-    const base = { scenario: card.scenario, brand: card.brand, masked: maskTestCard(card.number) };
-    if (!publicKey) {
-      results.push({ ...base, encrypted: null, failure: 'NO_PUBLIC_KEY' });
-      continue;
-    }
-    const encrypted = await encryptPagBankCard({
-      publicKey,
-      holder: card.holder,
-      number: card.number,
-      expMonth: card.expMonth,
-      expYear: card.expYear,
-      securityCode: card.securityCode,
-    });
-    results.push(
-      'encrypted' in encrypted
-        ? { ...base, encrypted: encrypted.encrypted }
-        : { ...base, encrypted: null, failure: encrypted.failure },
-    );
-  }
+  for (const card of PAGBANK_TEST_CARDS) results.push(await encryptTestCard(card, publicKey));
+  results.push(await authenticateDebitTestCard(publicKey, prepared.threeDSSession ?? null, prepared.debitTest));
   return results;
 }
 
@@ -169,7 +224,7 @@ function useEvidenceRun({ onPrepare, onRun, onDownload }: Pick<HomologacaoEviden
         enter('preparing');
         const prepared = await onPrepare();
         enter('encrypting');
-        const cards = await encryptTestCards(prepared.publicKey);
+        const cards = await prepareTestCards(prepared);
         enter('running');
         await onRun(prepared.runId, cards);
       }

package/src/components/platform/en-US.ts

@@ -123,12 +123,12 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     connectFailed: 'Could not start the test seller connection.',
     returnedConnected: 'Test seller connected. The callback and the code exchange were recorded in the evidence.',
     returnedFailed: 'The test seller connection did not complete. Try connecting again.',
-    generate: 'Generate evidence file\u00a0(TXT)',
+    generate: 'Generate evidence file\u00a0(TXT and JSON)',
     downloadLatest: 'Download the latest recorded',
     phases: {
-      preparing: 'Consulting the application, renewing the token and minting the public key…',
-      encrypting: 'Encrypting the test cards in the browser…',
-      running: 'Creating the Pix and card orders in the sandbox — this can take up to a minute…',
+      preparing: 'Consulting the application, renewing the token and minting the public key and the 3DS session…',
+      encrypting: 'Encrypting the test cards and authenticating the debit card (3DS) in the browser…',
+      running: 'Creating the Pix, credit and debit orders in the sandbox — this can take a few minutes…',
       downloading: 'Building the file…',
     },
     summary: ({ executed, failed, pending }) =>
@@ -139,7 +139,7 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       `${
         {
           preparing: 'Consulting the application and preparing the test seller failed.',
-          encrypting: 'Encrypting the test cards in the browser failed.',
+          encrypting: 'Encrypting the test cards or authenticating the debit card in the browser failed.',
           running: 'Creating the orders in the sandbox failed.',
           downloading: 'Building the file failed.',
         }[phase]

package/src/components/platform/pt-BR.ts

@@ -104,12 +104,12 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       'Lojista de teste conectado. O callback e a troca do código foram registrados nas evidências.',
     returnedFailed:
       'A conexão do lojista de teste não foi concluída. Tente conectar de novo.',
-    generate: 'Gerar arquivo de evidências\u00a0(TXT)',
+    generate: 'Gerar arquivo de evidências\u00a0(TXT e JSON)',
     downloadLatest: 'Baixar o último registrado',
     phases: {
-      preparing: 'Consultando a aplicação, renovando o token e gerando a chave pública…',
-      encrypting: 'Criptografando os cartões de teste no navegador…',
-      running: 'Criando os pedidos Pix e cartão no sandbox — pode levar até um minuto…',
+      preparing: 'Consultando a aplicação, renovando o token e gerando a chave pública e a sessão 3DS…',
+      encrypting: 'Criptografando os cartões de teste e autenticando o cartão de débito (3DS) no navegador…',
+      running: 'Criando os pedidos Pix, crédito e débito no sandbox — pode levar alguns minutos…',
       downloading: 'Montando o arquivo…',
     },
     summary: ({ executed, failed, pending }) =>
@@ -123,7 +123,7 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       `${
         {
           preparing: 'Falhou ao consultar a aplicação e preparar o lojista de teste.',
-          encrypting: 'Falhou ao criptografar os cartões de teste no navegador.',
+          encrypting: 'Falhou ao criptografar os cartões de teste ou autenticar o cartão de débito no navegador.',
           running: 'Falhou ao criar os pedidos no sandbox.',
           downloading: 'Falhou ao montar o arquivo.',
         }[phase]

package/src/index.ts

@@ -56,7 +56,7 @@ export { PT_BR_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-pt-BR
 // ---------------------------------------------------------------------------
 export { CheckoutFlow, type CheckoutCartView, type CheckoutFlowProps } from './components/checkout/checkout-flow';
 // The Pagamento step as ONE list (FUT-3591/3592) — opt-in via `CheckoutFlowProps.paymentList`.
-export type { CheckoutDoorOption, CheckoutDoorRowControls, CheckoutListChoice, CheckoutListHold, CheckoutOnlineChoice, CheckoutPaymentList, CheckoutPixBank, PaymentListCopy, PixBankCopy, PixBankId, PixBankName } from './components/checkout/list/types';
+export type { CheckoutBillingAddress, CheckoutDoorOption, CheckoutDoorRowControls, CheckoutListChoice, CheckoutListHold, CheckoutOnlineChoice, CheckoutPaymentList, CheckoutPixBank, PaymentListCopy, PaymentListDebitCopy, PixBankCopy, PixBankId, PixBankName } from './components/checkout/list/types';
 export { PT_BR_PAYMENT_LIST_COPY } from './components/checkout/list/pt-BR';
 export type { BackActionEmphasis } from './components/checkout/payment-status-parts';
 export type { CheckoutDeliverySummary, CheckoutSummaryLine } from './components/checkout/payment-summary';