@12-apps/payments-frontend 3.45.1 → 3.46.1

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/pix-banks.tsx

@@ -172,7 +172,23 @@ function Grid({ bank, state, stale }: { bank: CheckoutPixBank; state: PixBankSta
   );
 }
 
-/** The grid, or the bank being opened. */
+/** The one line under the bank being opened, where the checklist was (FUT-3612). */
+function AppHint({ text }: { text: string }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  return (
+    <Text variant="body" size="sm" color="secondary" as="p" style={{ margin: 0 }} data-testid="pix-bank-hint">
+      {text}
+    </Text>
+  );
+}
+
+/** The grid, or the bank being opened and the line that says what to do there. */
 export function PixBanks({ bank, state, stale }: { bank: CheckoutPixBank; state: PixBankState; stale: boolean }): JSX.Element {
-  return state.chosen ? <Opening bank={bank} state={state} chosen={state.chosen} /> : <Grid bank={bank} state={state} stale={stale} />;
+  if (!state.chosen) return <Grid bank={bank} state={state} stale={stale} />;
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      <Opening bank={bank} state={state} chosen={state.chosen} />
+      {bank.copy.appHint ? <AppHint text={bank.copy.appHint} /> : null}
+    </Box>
+  );
 }

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",

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. */
@@ -264,6 +270,11 @@ export interface PixBankCopy {
   notOpened: (bank: PixBankName) => string;
   /** "Tentar de novo". */
   retry: string;
+  /**
+   * The one line under the bank being opened, in place of the checklist —
+   * "Abra o app do seu banco e cole em Pix copia e cola." Absent ⇒ no line.
+   */
+  appHint?: string;
   /** The toasts. */
   copied: string;
   copiedPick: string;
@@ -286,6 +297,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

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';