Skip to main content
Version: v1

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>;
  setCallbacks(callbacks: Partial<OdusElementsCallbacks>): 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, rendered inside secure iFrames. The card number and security code stay inside those iFrames and never enter your page. authorize() exchanges them for a token and submits the payment for you; it returns no card data. If the card fields cannot load, the element shows an error and authorize() fails, rather than asking the shopper for a card number in your page.

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 and AU
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.

After the element is mounted and a payment has been associated (both must happen, since isAvailable is computed when the element renders), read the applePay.isAvailable property to decide whether to show the button's surrounding layout (heading, divider, or "or pay with" separator). On browsers that don't support Apple Pay — or when the payment's country isn't allowed — nothing is rendered and the element's host collapses, so you don't need to measure the button's height to detect availability.

await elements.associatePayment(paymentId, checkoutKey);

const applePay = elements.express.applePay;
applePay.mount('#apple-pay-slot'); // the SDK collapses this slot itself when unavailable

// Read isAvailable only after mounting, then hide your OWN surrounding chrome
// (heading, "or pay with" divider, padding) — the SDK can't see or collapse that:
document.querySelector('#apple-pay-container').hidden = !applePay.isAvailable;

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.

If the call rejects, the payment is not associated: authorize() keeps throwing until a later associatePayment() succeeds. A rejection also discards a previous successful association, so retry it before you authorize.

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.

authorize() charges the card, so mount elements.card before you call it. The only exception is Apple Pay: once the sheet has authorized, authorize() submits that instead. If there is no card to charge, or the card details cannot be tokenized, no request is sent — the reason goes to onPaymentFailed and to a mounted elements.error.

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);
});

setCallbacks​

setCallbacks(callbacks: Partial<OdusElementsCallbacks>): void

Updates one or more payment lifecycle callbacks after initialization. Only the provided callbacks are replaced; omitted callbacks remain unchanged. This eliminates stale closure issues in reactive frameworks where callbacks capture state at mount time.

// React example — update callbacks when dependencies change
useEffect(() => {
  checkoutRef.current?.setCallbacks({
    onPaymentSucceeded: () => trackPurchase(priceId, quantity),
  });
}, [priceId, quantity]);

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;
  maxLength?: number;
  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';