SDK Reference

Complete reference for the OdusCheckout class, its methods, and TypeScript types.

OdusCheckout Class

class OdusCheckout {
  constructor(config: CheckoutConfig);
  mount(containerId: string): this;
  unmount(): void;
  associatePayment(paymentId: string, checkoutKey: string): Promise<void>;
  displayError(message: string): void;
  clearError(): void;
}

Methods

• constructor(config: CheckoutConfig) — Creates a new checkout instance with the provided configuration.
• mount(containerId: string) — Mounts the checkout form to the specified container element. Returns this for chaining.
• unmount() — Unmounts and cleans up the checkout form.
• associatePayment(paymentId: string, checkoutKey: string) — Associates a payment with the checkout session. This enables payment method options and checkout details to be displayed.
• displayError(message: string) — Displays a custom error message using the checkout's built-in Alert UI. This method bypasses the disableErrorMessages configuration flag. Throws an error if called before mount().
• clearError() — Removes the currently displayed error message. Throws an error if called before mount().

Programmatic Error Display

The Checkout SDK provides methods to programmatically display and clear error messages using the built-in Alert UI. This is particularly useful for showing errors that occur outside the normal payment flow, such as after a failed 3DS redirect.

Displaying Custom Errors

Use the displayError() method to show an error message:

const checkout = new OdusCheckout({
  // ... configuration
});

checkout.mount('#checkout-container');

// Display a custom error message
checkout.displayError('Payment failed after 3DS authentication. Please try again.');

Important notes:

• The displayError() method always displays the message, even when disableErrorMessages: true is set in the configuration, since it represents an explicit intent to show a message
• The method must be called after the checkout is mounted, otherwise it will throw an error
• The error uses the SDK's built-in Alert styling with red color scheme and slide-in animation

Clearing Error Messages

Use the clearError() method to remove the currently displayed error:

// Clear the error message
checkout.clearError();

Common use cases:

• Displaying errors after returning from 3DS authentication
• Showing validation errors from your backend
• Communicating payment failures that occur outside the checkout flow
• Clearing errors before re-initializing or retrying a payment

CheckoutConfig Type

type CheckoutConfig = {
  apiKey: string;
  returnUrl: string;
  environment: 'test' | 'live';
  callbacks?: {
    onPaymentSucceeded?: (result: string) => void;
    onPaymentFailed?: (result: string) => void;
    onActionRequired?: (redirectUrl: string) => void;
    onLoadingStateChange?: (isLoading: boolean) => void;
  };
  locale?: Locale;
  appearance?: Appearance;
  initialValues?: {
    email?: string;
    name?: string;
    phoneNumber?: string;
    billingAddress?: Partial<AddressData>;
    shippingAddress?: Partial<AddressData>;
  };
  disableErrorMessages?: boolean;
  manualActionHandling?: boolean;
};

// Where Locale is a type representing supported languages
type Locale = 'en' | 'de' | 'es' | 'fr' | 'pl' | 'pt' | 'it' | 'tr';

// Contact fields that can be requested from Apple Pay
type ApplePayContactField = 'email' | 'name' | 'phone' | 'postalAddress' | 'phoneticName';

// Appearance configuration type
type Appearance = {
  additionalPaymentMethods?: {
    paypal?: {
      enabled: boolean;
      order: number;
      countries?: string[];
    };
    applePay?: {
      enabled: boolean;
      order: number;
      displayName?: string;
      countries?: string[];
      requiredBillingContactFields?: ApplePayContactField[];
      requiredShippingContactFields?: ApplePayContactField[];
    };
  };
  styles?: {
    borderRadius: number;
    buttonColor: string;
    buttonFontSize: number;
    buttonTextColor: string;
    fontFamily: string;
    fontSize: number;
    textColor: string;
  };
  layout?: {
    actionButton?: {
      label: string;
      translationKey: string;
    };
    phoneNumber?: {
      enabled: boolean;
      label?: string;
      defaultCountry?: string;
      allowedCountries?: string[];
    };
    billingFields?: {
      street?: { enabled: boolean; label?: string };
      city?: { enabled: boolean; label?: string };
      state?: { enabled: boolean; label?: string; options?: string[] };
      zipCode?: { enabled: boolean; label?: string };
      firstName?: { enabled: boolean; label?: string };
      lastName?: { enabled: boolean; label?: string };
      country?: { enabled: boolean; label?: string; options?: string[] };
    };
    shippingFields?: {
      street?: { enabled: boolean; label?: string };
      firstName?: { enabled: boolean; label?: string };
      lastName?: { enabled: boolean; label?: string };
      city?: { enabled: boolean; label?: string };
      state?: { enabled: boolean; label?: string; options?: string[] };
      zipCode?: { enabled: boolean; label?: string };
      country?: { enabled: boolean; label?: string; options?: string[] };
    };
  };
};

CheckoutInstance Type

// This represents the checkout instance returned when you create a new OdusCheckout
interface CheckoutInstance {
  mount(containerId: string): this;
  unmount(): void;
  associatePayment(paymentId: string, checkoutKey: string): Promise<void>;
  displayError(message: string): void;
  clearError(): void;
}