# 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; validate(): ValidationResult; authorize(payload?: AuthorizePayload): Promise; setCallbacks(callbacks: Partial): void; applyTheme(theme: Record): void; resetTheme(theme: Record): 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 | Element | Description | | ---------------------------- | -------------------------------------------------------------------------- | | `elements.address.firstName` | First name input | | `elements.address.lastName` | Last name input | | `elements.address.street` | Street address input | | `elements.address.city` | City input | | `elements.address.state` | State/province — auto-switches between text and dropdown for US, CA and AU | | `elements.address.zipCode` | Zip/postal code input | | `elements.address.country` | Country 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 ``` 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 — key is element name, value is error message ``` #### authorize ``` authorize(payload?: AuthorizePayload): Promise ``` 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): void ``` Applies CSS custom property overrides to all instantiated elements. See [Theming](https://docs.odus.com/docs/guides/checkout/elements/theming.md) for available variables. #### resetTheme ``` resetTheme(theme: Record): 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): 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): void; setTheme(theme: Record): void; resetTheme(theme: Record): 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): void ``` Merges new options into the element's current options and re-renders if the element is mounted. #### setTheme ``` setTheme(theme: Record): void ``` Sets CSS custom properties on this element's host element, overriding the global theme for this element only. #### resetTheme ``` resetTheme(theme: Record): void ``` Removes CSS custom properties from this element's host element. ### Properties | Property | Type | Description | | ----------- | ---------------- | --------------------------------------------------------- | | `value` | `unknown` | The current value of the element (type varies by element) | | `isValid` | `boolean` | Whether the element's current value passes validation | | `error` | `string \| null` | The current validation error message, or `null` | | `isMounted` | `boolean` | Whether 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 void>>; }; ``` ### ElementEvent ``` type ElementEvent = 'change' | 'blur' | 'focus' | 'error' | 'ready'; ``` ### ValidationResult ``` type ValidationResult = { valid: boolean; errors: Record; }; ``` ### AuthorizePayload ``` type AuthorizePayload = { customerData?: { email?: string; name?: string; phoneNumber?: string; dateOfBirth?: string; gender?: string; billingAddress?: Record; shippingAddress?: Record; [key: string]: unknown; }; }; ``` ### AuthorizeResult ``` type AuthorizeResult = { status: 'succeeded'; data: PaymentSuccessResult } | { status: 'action_required'; action: ActionRequiredData } | { status: 'failed'; error: PaymentError }; ``` ### OdusTheme A `Record` mapping CSS custom property names to values. See [Theming](https://docs.odus.com/docs/guides/checkout/elements/theming.md) 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'; ```