Cards.js API Reference

Cards is available in sandbox only while we finish development. Dakota enables Cards per account. The Cards endpoints are in the API reference, marked Sandbox only. Endpoints, fields, and flows can still change before release.

The package has three entry points:

@dakota-xyz/cards-js — the framework-free core.
@dakota-xyz/cards-js/react — the React binding. It needs react >= 18.
@dakota-xyz/cards-js/styles.css — the default stylesheet.

This page documents the public surface. For task-oriented guidance, see the integration guide and theming.

`@dakota-xyz/cards-js` (core)

`class DakotaCards`

The client. Create one per app and reuse it.

new DakotaCards(options: DakotaCardsOptions)

Member	Signature	Description
`cardDetails`	`(options?: CardDetailsOptions) => CardDetailsHandle`	Create a card-details handle.

interface DakotaCardsOptions {
  environment: Environment;   // 'sandbox' | 'production'
  fetchSession: FetchSession; // client-wide default; overridable per handle
}

`class CardDetailsHandle`

Controls one card. Get it from cards.cardDetails(...) — you do not construct it yourself.

Member	Signature	Description
`state`	`get state(): CardDetailsState`	Current lifecycle state.
`mount`	`(targets: CardFieldTargets) => Promise<void>`	Paint the masked face into the target nodes. Call once. No network.
`reveal`	`() => Promise<void>`	Mint a session and show the real values. Resolves once revealed.
`mask`	`() => void`	Re-mask a revealed card. No-op unless the state is `revealed`.
`on`	`<K extends keyof CardDetailsEvents>(event: K, handler: (p: CardDetailsEvents[K]) => void) => () => void`	Subscribe. Returns an unsubscribe function.
`destroy`	`() => void`	Tear down all frames and listeners. Terminal.

type CardDetailsState = 'idle' | 'mounting' | 'masked' | 'revealing' | 'revealed' | 'destroyed';

type CardField = 'pan' | 'cvv' | 'expiryMonth' | 'expiryYear';
type CardFieldTargets = Partial<Record<CardField, string | HTMLElement>>; // CSS selector or element

interface CardDetailsOptions {
  last4?: string;                 // shown in the masked PAN placeholder
  fetchSession?: FetchSession;    // overrides the client default for this handle
  theme?: CardTheme;              // text styles propagated into the value frames
  autoMaskMs?: number;            // upper bound on the reveal window
  strings?: Partial<CardStrings>; // i18n overrides
}

Events

CardDetailsEvents maps each event name to its payload.

Event	Payload	Fires when
`ready`	`void`	The masked face has mounted.
`revealing`	`void`	A reveal attempt started. Drive your loading treatment from this event.
`revealed`	`void`	The real values are showing.
`masked`	`void`	The card returned to the masked face: `mask()` was called, or a reveal attempt failed.
`expired`	`void`	The reveal window ended and the SDK auto-masked.
`copied`	`CopiedPayload`	The cardholder copied a field.
`error`	`unknown`	Reserved — held for future out-of-band failures, and never emitted in this version. All current errors reject the returned promise or, for `invalid_theme`, throw from `cardDetails()`. See Errors.

interface CopiedPayload { field: CardField; success: boolean; }

Errors are not delivered as events. mount() and reveal() reject with a DakotaCardsError, so handle them with try/catch. cardDetails() throws invalid_theme synchronously when a theme value is not concrete.

Sessions

type FetchSession = (ctx: SessionRequestContext) => Promise<RevealSession>;

interface SessionRequestContext {
  sessionType: SessionType;
  origin: string; // window.location.origin at reveal time
}

interface RevealSession {
  session: string;
  expiresAt: string; // RFC 3339
  provider?: string; // reserved; omit
}

type SessionType = 'card_details';
type Environment = 'sandbox' | 'production';

Errors

class DakotaCardsError extends Error {
  readonly code: ErrorCode;
  readonly retryable: boolean;
  readonly diagnosticId?: string; // upstream request id, when available
}

function isDakotaCardsError(e: unknown): e is DakotaCardsError;

type ErrorCode =
  | 'session_fetch_failed'
  | 'session_rejected'
  | 'origin_mismatch'
  | 'mount_target_not_found'
  | 'invalid_state'
  | 'invalid_theme'
  | 'reveal_failed';

The SDK creates these errors. You catch them — you do not construct them. See the error-code table for when each code occurs and which codes are retryable.

Theming & strings types

interface CardTheme {
  color?: string;
  fontFamily?: string;
  fontSize?: string;
  fontWeight?: string;
  letterSpacing?: string;
}

interface CardStrings {
  validThru: string;
  cvvLabel: string;
  panPlaceholder: string; // e.g. '•••• •••• •••• {last4}'
  revealedAnnouncement: string;
  maskedAnnouncement: string;
}

See theming for defaults and behaviour.

`@dakota-xyz/cards-js/react`

The React entry point re-exports DakotaCards, CardDetailsHandle, and the card types its own signatures use. Import FetchSession, the error types, and the theming types from the core entry point.

`<DakotaCardsProvider>`

Supplies a DakotaCards client to the component tree.

<DakotaCardsProvider client={client}>{children}</DakotaCardsProvider>

function DakotaCardsProvider(input: { client: DakotaCards; children: ReactNode }): JSX.Element;

`useDakotaCards()`

function useDakotaCards(): DakotaCards;

Returns the client from the nearest provider. Throws if it is used outside one.

`<CardDetails>` and `useCardDetails`

<CardDetails> renders the .dk-card recipe and exposes reveal and mask through a ref.

const CardDetails: ForwardRefExoticComponent<CardDetailsProps & RefAttributes<CardDetailsHandleRef>>;

interface CardDetailsProps extends CardDetailsOptions {
  fields?: CardField[]; // which fields to bind; defaults to all four
  className?: string;
}

interface CardDetailsHandleRef {
  reveal: () => Promise<void>;
  mask: () => void;
}

<CardDetails> always renders all four value slots and their captions from the .dk-card recipe. fields only selects which of those slots the SDK binds — mounts the masked face into, and reveals. Slots you omit still render, as empty captioned placeholders. To render a genuinely partial layout, with fewer slots on the page, use the headless useCardDetails hook and lay out only the fields you want. useCardDetails is the headless form: you render the recipe yourself and wire the refs.

function useCardDetails(options?: CardDetailsOptions & { fields?: CardField[] }): UseCardDetailsResult;

interface UseCardDetailsResult {
  readonly refs: Partial<Record<CardField, RefCallback<HTMLElement>>>;
  readonly state: CardDetailsState;
  readonly handle: { readonly current: CardDetailsHandle | null };
  readonly reveal: () => Promise<void>;
  readonly mask: () => void;
}

When you render your own markup, some CSS rules are load-bearing. See Custom markup.

Playground

Documentation

Import Share Tokens

Agentic Payments

Cards

Authentication

Developer Tools

Cards.js API Reference

`@dakota-xyz/cards-js` (core)

`class DakotaCards`

`class CardDetailsHandle`

Events

Sessions

Errors

Theming & strings types

`@dakota-xyz/cards-js/react`

`<DakotaCardsProvider>`

`useDakotaCards()`

`<CardDetails>` and `useCardDetails`

​@dakota-xyz/cards-js (core)

​class DakotaCards

​class CardDetailsHandle

​Events

​Sessions

​Errors

​Theming & strings types

​@dakota-xyz/cards-js/react

​<DakotaCardsProvider>

​useDakotaCards()

​<CardDetails> and useCardDetails

`@dakota-xyz/cards-js` (core)

`class DakotaCards`

`class CardDetailsHandle`

Events

Sessions

Errors

Theming & strings types

`@dakota-xyz/cards-js/react`

`<DakotaCardsProvider>`

`useDakotaCards()`

`<CardDetails>` and `useCardDetails`