Skip to main content

​
Elements SDK — API Reference

​
OzVault

The main entry point. Manages all elements, the hidden tokenizer iframe, and vault credentials. 
new OzVault(apiKey: string, options: VaultOptions): OzVault

​
Constructor

Both apiKey and options.pubKey are required. Tokenization will fail if either is missing.
ParameterTypeRequiredDescription
apiKeystring✅Vault API key — client-side key, safe to expose in browser code
optionsVaultOptions✅Configuration object (see below)

​
VaultOptions

type VaultOptions = {
  pubKey:         string;       // required — authenticates the tokenize request
  apiUrl?:        string;       // default: 'https://api.ozuravault.com'
  frameBaseUrl?:  string;       // default: 'https://elements.ozura.com'
  fonts?:         FontSource[]; // custom web fonts to load in iframes
  appearance?:    Appearance;   // global theme and variable overrides
  onLoadError?:   () => void;   // called if tokenizer iframe fails to load
  loadTimeoutMs?: number;       // default: 10000 (ms)
};

​
Properties

PropertyTypeDescription
vaultIdstringUnique ID for this vault instance
isReadybooleantrue once the tokenizer iframe has loaded

​
Methods

​
createElement

vault.createElement(type: ElementType, options?: ElementOptions): OzElement
Creates a card input element. Call .mount() on the result to attach it to the DOM. ElementType values: 'cardNumber' | 'expirationDate' | 'cvv'

​
getElement

vault.getElement(type: ElementType): OzElement | null
Returns the existing element of the given type, or null.

​
createBankElement

vault.createBankElement(type: BankElementType, options?: ElementOptions): OzElement
Creates a bank account input element. BankElementType values: 'accountNumber' | 'routingNumber'

​
getBankElement

vault.getBankElement(type: BankElementType): OzElement | null
Returns the existing bank element of the given type, or null.

​
createToken

vault.createToken(options?: TokenizeOptions): Promise<TokenResponse>
Tokenizes all mounted card elements. Throws OzError on failure.

​
createBankToken

vault.createBankToken(options: BankTokenizeOptions): Promise<BankTokenResponse>
Tokenizes all mounted bank elements. Throws OzError on failure.

​
destroy

vault.destroy(): void
Removes all element iframes, the tokenizer iframe, and the global message listener. Call this when the checkout component unmounts.

​
OzElement

Returned by createElement() and createBankElement(). Represents a single input field.

​
Properties

PropertyTypeDescription
frameIdstringUnique ID for this element’s iframe
typeElementType | BankElementTypeThe element type
isReadybooleantrue once the iframe has loaded

​
Methods

​
mount

el.mount(target: string | HTMLElement): void
Attaches the iframe to the DOM. target can be a CSS selector string or an HTMLElement.

​
unmount

el.unmount(): void
Removes the iframe from the DOM and resets internal state, but does not destroy the element. The element can be re-mounted after calling unmount(). Use destroy() for permanent teardown.

​
on

el.on(event: ElementEvent, callback: (payload?) => void): this
Registers an event listener. Returns this for chaining.

​
off

el.off(event: ElementEvent, callback: (payload?) => void): this
Removes a previously registered event listener.

​
once

el.once(event: ElementEvent, callback: (payload?) => void): this
Registers a one-time event listener that fires once then removes itself.

​
update

el.update(options: Partial<ElementOptions>): void
Updates element options (style, placeholder, disabled) without re-mounting the iframe.

​
focus

el.focus(): void
Programmatically focuses the input inside the iframe.

​
blur

el.blur(): void
Programmatically blurs the input.

​
clear

el.clear(): void
Clears the current value.

​
setCvvLength

el.setCvvLength(length: 3 | 4): void
Overrides the CVV max length. Called automatically when card brand changes; available for manual override.

​
destroy

el.destroy(): void
Permanently removes the iframe, clears all event handlers, and prevents future use. Distinct from unmount().

​
Events

type ElementEvent = 'ready' | 'change' | 'focus' | 'blur' | 'loaderror';

​
change

el.on('change', (event: ElementChangeEvent) => void)
Fired whenever the value or state changes. 
type ElementChangeEvent = {
  empty:      boolean;           // true when the field has no input
  complete:   boolean;           // user has entered a full, valid value
  valid:      boolean;           // value passes validation
  error?:     string;            // human-readable error message, or undefined
  cardBrand?: string;            // card brand (cardNumber element only)
  month?:     string;            // parsed month '01'–'12' (expirationDate element only)
  year?:      string;            // parsed 2-digit year e.g. '27' (expirationDate element only)
};

​
focus / blur

el.on('focus', () => void)
el.on('blur',  () => void)
Fired when the iframe input gains or loses focus.

​
ready

el.on('ready', () => void)
Fired once the iframe has fully loaded and is interactive.

​
loaderror

el.on('loaderror', () => void)
Fired if the iframe fails to load within loadTimeoutMs.

​
TokenizeOptions

type TokenizeOptions = {
  billing?:   BillingDetails;
  firstName?: string;   // deprecated — use billing.firstName
  lastName?:  string;   // deprecated — use billing.lastName
};

​
TokenResponse

type TokenResponse = {
  token:       string;
  cvcSession?: string;
  card?: {
    last4:    string;
    brand:    string;
    expMonth: string;  // '01'–'12'
    expYear:  string;  // '2026', '2027', …
  };
  billing?: BillingDetails;
};

​
BillingDetails

type BillingDetails = {
  firstName: string;          // required, 1–50 chars
  lastName:  string;          // required, 1–50 chars
  email?:    string;          // valid email, max 50 chars
  phone?:    string;          // E.164 format, e.g. '+15551234567'
  address?:  BillingAddress;
};

type BillingAddress = {
  line1:    string;   // required
  line2?:   string;   // optional
  city:     string;   // required
  state:    string;   // required; US/CA normalized to 2-letter code
  zip:      string;   // required
  country:  string;   // ISO 3166-1 alpha-2, e.g. 'US'
};

​
BankTokenizeOptions

type BankTokenizeOptions = {
  firstName: string;   // required
  lastName:  string;   // required
};

​
BankTokenResponse

type BankTokenResponse = {
  token: string;
  bank?: {
    last4:         string;
    routingNumber: string;
  };
};

​
ElementOptions

type ElementOptions = {
  style?:         ElementStyleConfig;
  placeholder?:   string;
  disabled?:      boolean;
  loadTimeoutMs?: number;   // ms before loaderror fires on this element; default 10000
};

​
ElementStyleConfig

type ElementStyleConfig = {
  base?:        ElementStyle;
  focus?:       ElementStyle;
  invalid?:     ElementStyle;
  complete?:    ElementStyle;
  placeholder?: ElementStyle;
};
See the Styling guide for the full list of supported ElementStyle keys.

​
Appearance

The appearance option on OzVault and <OzElements> accepts an Appearance object, not a raw ElementStyleConfig. It applies a preset theme and/or CSS variable overrides across all elements. 
type Appearance = {
  theme?:     OzTheme;              // 'default' | 'night' | 'flat'
  variables?: AppearanceVariables;  // flat overrides applied on top of theme
};

type OzTheme = 'default' | 'night' | 'flat';

type AppearanceVariables = {
  colorText?:        string;  // maps to base.color
  colorBackground?:  string;  // maps to base.backgroundColor
  colorPrimary?:     string;  // maps to focus.caretColor and focus.color
  colorDanger?:      string;  // maps to invalid.color
  colorSuccess?:     string;  // maps to complete.color
  colorPlaceholder?: string;  // maps to placeholder.color
  fontFamily?:       string;  // maps to base.fontFamily
  fontSize?:         string;  // maps to base.fontSize
  fontWeight?:       string;  // maps to base.fontWeight
  letterSpacing?:    string;  // maps to base.letterSpacing
  lineHeight?:       string;  // maps to base.lineHeight
  padding?:          string;  // maps to base.padding
};
Example: 
const vault = new OzVault('YOUR_API_KEY', {
  pubKey: 'YOUR_PUB_KEY',
  appearance: {
    theme: 'flat',
    variables: {
      colorPrimary: '#6366f1',
      fontFamily:   '"Inter", sans-serif',
    },
  },
});

​
FontSource

// Google Fonts / remote CSS
type CssFontSource = { cssSrc: string };

// Self-hosted @font-face
type CustomFontSource = {
  family:       string;
  src:          string;   // url(https://...) value
  weight?:      string;
  style?:       string;
  display?:     string;
  unicodeRange?: string;
};

type FontSource = CssFontSource | CustomFontSource;

​
OzError

class OzError extends Error {
  message:    string;        // normalized, user-facing message
  errorCode:  OzErrorCode;   // machine-readable code
  raw:        string;        // raw vault API message (use for logging)
  retryable:  boolean;       // true for network, timeout, server errors
}

type OzErrorCode =
  | 'network'
  | 'auth'
  | 'validation'
  | 'server'
  | 'timeout'
  | 'config'
  | 'unknown';

​
Exports

// @ozura/elements
export { OzVault };
export { OzElement };
export { OzError, normalizeVaultError, normalizeCardSaleError };
export type {
  ElementType, BankElementType,
  ElementOptions, ElementStyleConfig, ElementStyle, ElementChangeEvent,
  VaultOptions,
  TokenizeOptions, TokenResponse,
  BankTokenizeOptions, BankTokenResponse,
  BankAccountMetadata, CardMetadata,
  BillingDetails, BillingAddress,
  FontSource, CssFontSource, CustomFontSource,
  Appearance, AppearanceVariables, OzTheme,
  OzErrorCode,
};

// @ozura/elements/react
export { OzElements };
export { useOzElements };
export { OzCardNumber, OzExpiry, OzCvv };
export { OzCard };
export type { OzFieldProps, OzCardProps, OzCardState, OzElementsProps, UseOzElementsReturn };