Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Headless SDK
  4. enrollCard

enrollCard

​​ Overview

enrollCard submits a card’s details to Firmly’s Network Token Router. Firmly detects the network from the BIN, enrolls the card, and returns a FlowSession plus the verificationMethods available for cardholder authentication.

Persist virtualCardId, cardArt, and masked from the result — they are used to render a saved-card UI and to call selectCard for returning buyers.

​​ Signature 


const result = await fap.enrollCard(input, options);

​​ Parameters

  • input.pan (string, required) — Card number (PAN).

  • input.expiry_month (string, required) — Two-digit expiry month (e.g. "03", "12").

  • input.expiry_year (string, required) — Four-digit expiry year (e.g. "2030").

  • input.cvv (string) — Card verification value.

  • input.cardholder_full_name (string) — Full name as printed on the card.

  • input.consumer (object) — Cardholder information. Fields: first_name, last_name, email, phone, country_code — all strings, all optional.

  • options (object) — Optional CallOptions: apiTokenOverride (string), signal (AbortSignal).

​​ Returns

Promise<EnrollResult>

  • session (FlowSession) — Flow session — pass it to the next call in the chain. Treat it as mostly opaque, but it does expose a small surface:

  • session.network — the detected network ("visa" / "mastercard"), readable for branching your UI (as the example below does).

  • session.serialize() — returns a plain, JSON-serializable snapshot of the session (including cardArt) so you can persist it and later restore the session for a returning buyer. See selectCard for the returning-buyer path.

  • virtualCardId (string | null) — Durable network-assigned card identifier (null if the network did not return one). Persist it — it is the handle passed to selectCard.

  • verificationMethods (array) — Verification challenges the card supports. Empty array if none were returned.

    VerificationMethod
    • id (string) — Method identifier (e.g. "MANAGED_AUTHENTICATION" for Mastercard, "VISA_IFRAME_HANDSHAKE" for Visa).
    • type (string) — "otp", "embed_iframe", or "embed_iframe_handshake".
    • attributes (object) — Method-specific data (e.g. uri).

  • cardArt (CardArt | null) — Issuer card art. Captured at enroll time only — re-enrolling the same PAN may return null (the network caches enrollments), and selectCard never re-fetches it. Persist the cardArt object itself alongside masked and virtualCardId (as saveCard({ cardArt, masked }) shows below), or capture the whole session via session.serialize(). Fall back to a placeholder when null.

  • masked (MaskedCard | null) — Masked card details for rendering a saved-card chip. null when the network omits it.

    MaskedCard
    • last4 (string) — Last four digits of the funding PAN (not the network token).
    • exp_month (string) — Two-digit expiry month.
    • exp_year (string) — Four-digit expiry year.
    • brand (string) — "visa" or "mastercard".
    • card_type (string) — "DEBIT" / "CREDIT" — Mastercard only.
    • issuer_name (string) — Issuer / bank descriptor (e.g. "Test Bank 2") — Mastercard only.

​​ Example 


import { FirmlyAgenticPay } from '@firmly/agentic-pay-sdk';



const fap = new FirmlyAgenticPay({
  baseUrl: 'https://api.firmly.work',
  apiToken: '<bearer>'

});



const { session, virtualCardId, verificationMethods, cardArt, masked } =
  await fap.enrollCard({
    pan: '4111111111111111',
    expiry_month: '12',
    expiry_year: '2030',
    cvv: '123'
  });



// Persist for returning customers — selectCard does not re-fetch these.

saveCard({ network: session.network, virtualCardId, cardArt, masked });