Skip to main content

SDK Reference

Complete API reference for the OdusElements class, BaseElement class, and all TypeScript types.

OdusElements Class​

class OdusElements {
  constructor(config: ElementsConfig);

  readonly elements: {
    card: CardElement;
    cardholderName: CardholderElement;
    contact: {
      email: EmailElement;
      phone: PhoneElement;
    };
    address: {
      firstName: AddressFirstNameElement;
      lastName: AddressLastNameElement;
      street: AddressStreetElement;
      city: AddressCityElement;
      state: AddressStateElement;
      zipCode: AddressZipCodeElement;
      country: AddressCountryElement;
    };
    express: {
      applePay: ApplePayElement;
      payPal: PayPalElement;
    };
    error: ErrorElement;
  };

  associatePayment(paymentId: string, checkoutKey: string): Promise<void>;
  validate(): ValidationResult;
  authorize(payload?: AuthorizePayload): Promise<void>;
  applyTheme(theme: Record<string, string>): void;
  resetTheme(theme: Record<string, string>): void;
  onChange(listener: () => void): void;
  destroy(): void;

  readonly isValid: boolean;
}

Constructor​

new OdusElements(config: ElementsConfig)

Creates a new Elements instance. Element accessors on the elements namespace are lazily initialized — elements are created when first accessed.

Available Elements​

Card Input​

elements.card — Combined card number, expiry, and CVV input. Validates card number (Luhn), expiry (not expired), and CVV (3-4 digits). Card data is encrypted and transmitted automatically on authorize().

Cardholder Name​

elements.cardholderName — Cardholder name input (filtered to [a-zA-Z\s\-'.]).

Contact​

elements.contact.email — Email address input with validation.

elements.contact.phone — Phone number input with country dial code selector.

Address​

ElementDescription
elements.address.firstNameFirst name input
elements.address.lastNameLast name input
elements.address.streetStreet address input
elements.address.cityCity input
elements.address.stateState/province — auto-switches between text and dropdown for US/CA. Use setStates(states) to restrict options
elements.address.zipCodeZip/postal code input
elements.address.countryCountry dropdown. Use setCountries(countries) to restrict options

Express Payments​

elements.express.applePay — Apple Pay button. Renders only after associatePayment() and only when the payment supports Apple Pay. Triggers the native payment sheet and completes authorization automatically.

elements.express.payPal — PayPal button. Renders only after associatePayment() and only when the payment supports PayPal. Triggers authorization and redirects via onActionRequired.

Error Display​

elements.error — Shows API-level payment errors automatically. Use setError(message) and clearError() for manual control.

OdusElements Methods​

associatePayment​

associatePayment(paymentId: string, checkoutKey: string): Promise<void>

Links the Elements instance to a payment created on your backend. This fetches checkout details, stores payment state, and configures express payment methods (Apple Pay, PayPal). Express payment buttons only render after this call succeeds.

Can be called multiple times on the same instance — all user-entered form data is preserved, and only the express payment buttons are refreshed. This is the recommended way to handle price or plan changes without losing form state.

validate​

validate(): ValidationResult

Validates all mounted elements and returns a ValidationResult. Unmounted elements are skipped.

const { valid, errors } = checkout.validate();
// errors: Record<string, string> — key is element name, value is error message

authorize​

authorize(payload?: AuthorizePayload): Promise<void>

Authorizes the payment. Requires a prior associatePayment() call. The optional payload parameter allows passing merchant-collected data (e.g., email, name) that supplements or overrides element-derived values.

await checkout.authorize({
  customerData: {
    email: 'user@example.com',
    name: 'John Doe',
  },
});

applyTheme​

applyTheme(theme: Record<string, string>): void

Applies CSS custom property overrides to all instantiated elements. See Theming for available variables.

resetTheme​

resetTheme(theme: Record<string, string>): void

Removes the specified CSS custom property overrides from all instantiated elements, reverting them to defaults.

onChange​

onChange(listener: () => void): void

Registers a listener that fires whenever any mounted element emits a change event. Useful for tracking form validity.

checkout.onChange(() => {
  setIsFormValid(checkout.isValid);
});

destroy​

destroy(): void

Destroys all elements and clears all listeners. Call this when unmounting your checkout component.

Properties​

isValid​

readonly isValid: boolean

Shorthand for validate().valid. Returns true if all mounted elements are valid.

BaseElement Class​

All individual elements extend BaseElement. This is the shared API available on every element.

abstract class BaseElement {
  mount(target: string | HTMLElement): void;
  unmount(): void;
  destroy(): void;
  on(event: ElementEvent, handler: (data?: unknown) => void): this;
  update(options: Partial<MountOptions>): void;
  setTheme(theme: Record<string, string>): void;
  resetTheme(theme: Record<string, string>): void;

  readonly value: unknown;
  readonly isValid: boolean;
  readonly error: string | null;
  readonly isMounted: boolean;
}

Methods​

mount​

mount(target: string | HTMLElement): void

Creates a Shadow DOM host element, appends it to the target (CSS selector or DOM element), renders the element UI, and emits a ready event.

unmount​

unmount(): void

Removes the host element from the DOM and clears the shadow root.

destroy​

destroy(): void

Calls unmount() and clears all registered event listeners.

on​

on(event: ElementEvent, handler: (data?: unknown) => void): this

Registers an event listener. Returns this for chaining.

checkout.elements.card.on('change', () => console.log('Card changed')).on('blur', () => console.log('Card blurred'));

update​

update(options: Partial<MountOptions>): void

Merges new options into the element's current options and re-renders if the element is mounted.

setTheme​

setTheme(theme: Record<string, string>): void

Sets CSS custom properties on this element's host element, overriding the global theme for this element only.

resetTheme​

resetTheme(theme: Record<string, string>): void

Removes CSS custom properties from this element's host element.

Properties​

PropertyTypeDescription
valueunknownThe current value of the element (type varies by element)
isValidbooleanWhether the element's current value passes validation
errorstring | nullThe current validation error message, or null
isMountedbooleanWhether the element is currently mounted in the DOM

Types​

ElementsConfig​

type ElementsConfig = {
  apiKey: string;
  environment: 'test' | 'live';
  returnUrl: string;
  locale?: Locale;
  callbacks?: OdusElementsCallbacks;
  additionalPaymentMethods?: AdditionalPaymentMethodsConfig;
};

OdusElementsCallbacks​

type OdusElementsCallbacks = {
  onPaymentSucceeded?: (result: PaymentResult) => void;
  onPaymentFailed?: (result: string) => void;
  onActionRequired?: (redirectUrl: string) => void;
  onLoadingStateChange?: (isLoading: boolean) => void;
};

MountOptions​

type MountOptions = {
  locale?: string;
  disabled?: boolean;
  initialValue?: unknown;
  callbacks?: Partial<Record<ElementEvent, (data?: unknown) => void>>;
};

ElementEvent​

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

ValidationResult​

type ValidationResult = {
  valid: boolean;
  errors: Record<string, string>;
};

AuthorizePayload​

type AuthorizePayload = {
  customerData?: {
    email?: string;
    name?: string;
    phoneNumber?: string;
    dateOfBirth?: string;
    gender?: string;
    billingAddress?: Record<string, unknown>;
    shippingAddress?: Record<string, unknown>;
    [key: string]: unknown;
  };
};

AuthorizeResult​

type AuthorizeResult = { status: 'succeeded'; data: PaymentSuccessResult } | { status: 'action_required'; action: ActionRequiredData } | { status: 'failed'; error: PaymentError };

OdusTheme​

A Record<string, string> mapping CSS custom property names to values. See Theming for the full list of available variables.

ApplePayConfig​

type ApplePayConfig = {
  displayName?: string;
  countries?: string[];
  requiredBillingContactFields?: ApplePayContactField[];
  requiredShippingContactFields?: ApplePayContactField[];
};

AdditionalPaymentMethodsConfig​

type AdditionalPaymentMethodsConfig = {
  applePay?: ApplePayConfig;
};

Locale​

type Locale = 'en' | 'de' | 'es' | 'fr' | 'pl' | 'pt' | 'it' | 'tr' | 'cs' | 'nl' | 'sk';