# 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>;

  setCallbacks(callbacks: Partial<CheckoutCallbacks>): 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. Can be called multiple times on the same instance — all user-entered form data (email, card details, address fields) is preserved, and only the payment method buttons (card, PayPal, Apple Pay) are refreshed. This is the recommended way to handle price or plan changes without losing form state.
* **`setCallbacks(callbacks: Partial<CheckoutCallbacks>)`** — Updates one or more callback functions after initialization. Only the provided callbacks are replaced; omitted callbacks remain unchanged. This eliminates stale closure issues in reactive frameworks (React, Vue, Svelte) where callbacks capture state at mount time.
* **`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' | 'cs' | 'nl' | 'sk';



// 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; hiddenForCountries?: 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; hiddenForCountries?: 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>;

  setCallbacks(callbacks: Partial<CheckoutCallbacks>): void;

  displayError(message: string): void;

  clearError(): void;

}
```