Checkout SDK

The Odus Checkout is a flexible, easy-to-implement JavaScript SDK that allows merchants to accept payments on their websites with minimal integration effort. This documentation provides all the necessary information to successfully implement the Odus Checkout on your website.

Table of Contents

• Installation
• Getting Started
• Configuration Options
• Payment Methods
• Callbacks and Event Handling
• Localization Support
• Advanced Usage
• API Reference
• Troubleshooting
• Related Guides

Installation

CDN Usage (Browser)

<script src="https://cdn.example.com/odus-js/checkout.js"></script>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    let checkout = null;

    function initializeCheckout() {
      try {
        // Create checkout configuration
        const checkoutConfig = {
          // Your configuration
        };

        // Initialize and mount checkout
        checkout = new window.OdusCheckout(checkoutConfig);
        checkout.mount('#checkout-container');
      } catch (error) {
        console.error('Checkout initialization error details:', error);
        console.trace();
      }
    }

    // Initialize checkout immediately
    initializeCheckout();
  });
</script>

NPM Usage (Module)

npm install @odus/checkout

import { OdusCheckout } from '@odus/checkout';
// Import the required styles
import '@odus/checkout/styles';

function CheckoutPage() {
  useEffect(() => {
    const checkout = new OdusCheckout({
      //  your configuration
    });

    try {
      checkout.mount('#checkout-container');
    } catch (error) {
      console.error('Error mounting checkout:', error);
    }

    return () => {
      checkout.unmount();
    };
  }, []);

  return <div id="checkout-container" />;
}

Important: Always import the styles using import '@odus/checkout/styles' to ensure the checkout UI renders correctly. Without the styles, the checkout component will not display properly.

TypeScript Support

For TypeScript users, we export type definitions to enhance your development experience with proper type checking and autocompletion:

// Import the main class and TypeScript types
import { OdusCheckout, CheckoutConfig, CheckoutInstance, Locale } from '@odus/checkout';

// Now you can use these types in your code
const config: CheckoutConfig = {
  apiKey: 'your_api_key',
  paymentId: 'your_payment_id',
  checkoutKey: 'your_unique_checkout_key',
  returnUrl: 'https://your-website.com/payment-complete',
  environment: 'test',
  locale: 'en', // Type-safe locale values
};

// The checkout instance is properly typed
const checkout: CheckoutInstance = new OdusCheckout(config);

Getting Started

Basic Implementation

Here's a simple example of how to implement the Odus Checkout in your application:

import { OdusCheckout } from '@odus/checkout';
// Import the required styles
import '@odus/checkout/styles';

// Initialize the checkout
const checkout = new OdusCheckout({
  apiKey: 'your_api_key',
  paymentId: 'your_payment_id',
  checkoutKey: 'your_unique_checkout_key',
  returnUrl: 'https://your-website.com/payment-complete',
  environment: 'test', // 'test' for sandbox or 'live' for production

  callbacks: {
    onPaymentSucceeded: (result) => {
      console.log('Payment successful!', result);
      // Handle successful payment (e.g., show confirmation page)
    },
    onPaymentFailed: (result) => {
      console.log('Payment failed!', result);
      // Handle failed payment
    },
    onActionRequired: (redirectUrl) => {
      console.log('3DS authentication required!', redirectUrl);
      // Custom redirect handling (only called when manualActionHandling is true)
    },
    onLoadingStateChange: (isLoading) => {
      console.log('Loading state changed:', isLoading);
      // Toggle loading indicators in your UI
    },
  },
  // Optional: Enable manual handling of 3DS redirects
  // manualActionHandling: true,
});

// Mount the checkout form to a container in your HTML
checkout.mount('#checkout-container');

Make sure you have a container element in your HTML:

<div id="checkout-container"></div>

Configuration Options

When initializing the Odus Checkout, you can configure various options:

Payment Methods

The Odus Checkout automatically displays payment methods based on your account configuration and the checkout profile. The following payment methods are supported:

• Credit/Debit Cards (Visa, Mastercard, American Express, Discover, JCB, Diners)
• PayPal
• Additional methods based on your account configuration

Callbacks and Event Handling

The Odus Checkout SDK provides callback functions to handle different payment scenarios:

onPaymentSucceeded

Called when a payment is successfully authorized.

onPaymentSucceeded: (result) => {
  // result is the payment status: 'authorized'
  console.log('Payment successful!', result);
  // Update UI, redirect to thank you page, etc.
};

onPaymentFailed

Called when a payment fails.

onPaymentFailed: (result) => {
  // result is the payment status: 'failed'
  console.log('Payment failed!', result);
  // Show error message, allow retry, etc.
};

onActionRequired

Called when a payment requires additional action (such as 3DS authentication) and manualActionHandling is set to true.

onActionRequired: (redirectUrl) => {
  // redirectUrl is the URL where the customer needs to be redirected for 3DS authentication
  console.log('Action required!', redirectUrl);
  // Handle the redirect manually, e.g., open in a modal, new window, or custom redirect
  window.location.href = redirectUrl;
};

onLoadingStateChange

Called when the loading state of the checkout form changes. This is useful for showing or hiding custom loading indicators in your UI.

This callback is optional. If not provided, Odus will automatically render its default spinner during loading states.

onLoadingStateChange: (isLoading) => {
  // isLoading is a boolean indicating whether the form is currently loading
  console.log('Loading state changed:', isLoading);

  // Example: Toggle a custom spinner in your UI
  const spinner = document.getElementById('my-spinner');
  if (isLoading) {
    spinner.style.display = 'block';
  } else {
    spinner.style.display = 'none';
  }
};

Note: Implementing this callback will override the default Odus loading indicator, giving you complete control over the loading experience.

Localization Support

Odus provides localized payment experiences in 33 languages, helping you better serve your global customer base.

How it works

• Automatic Detection: By default, Odus detects your customer's browser locale and displays the payment page in that language if supported.
• Manual Override: You can specify a particular language by passing the locale parameter when creating a Checkout Session.

Supported Languages

Odus currently supports localization for 33 languages, ensuring broad international coverage for your payment processing needs.

Advanced Usage

Programmatic Control

You can programmatically control the checkout form:

// Mount the checkout to a container
checkout.mount('#checkout-container');

// Unmount the checkout (e.g., when navigating away)
checkout.unmount();

Custom 3DS Redirect Handling

By default, Odus Checkout automatically redirects customers to the 3DS authentication page when required. However, you can take control of this process for a more customized experience:

const checkout = new OdusCheckout({
  // ... other configuration options
  manualActionHandling: true,
  callbacks: {
    // ... other callbacks
    onActionRequired: (redirectUrl) => {
      // Example: Open 3DS in a modal or iframe instead of full-page redirect
      const modal = document.getElementById('auth-modal');
      const iframe = document.createElement('iframe');
      iframe.src = redirectUrl;
      modal.appendChild(iframe);
      modal.style.display = 'block';
    },
  },
});

This approach is useful for:

• Implementing a modal/popup for 3DS authentication
• Using an iframe instead of a full page redirect
• Adding custom tracking or analytics before redirecting
• Implementing custom UI transitions during the authentication flow

Displaying Error Messages Programmatically

You can display custom error messages using the checkout's 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:

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

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

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

// Clear the error message when needed
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

Note: 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. Both methods require the checkout to be mounted first.

API Reference

OdusCheckout Class

class OdusCheckout {
  constructor(config: CheckoutConfig);
  mount(containerId: string): this;
  unmount(): void;
  displayError(message: string): void;
  clearError(): void;
}

Methods

• mount(containerId: string) - Mounts the checkout form to the specified container element.
• unmount() - Unmounts and cleans up the checkout form.
• 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().

CheckoutConfig Type

type CheckoutConfig = {
  apiKey: string;
  returnUrl: string;
  checkoutKey: string;
  paymentId: string;
  environment: 'test' | 'live';
  callbacks?: {
    onPaymentSucceeded?: (result: string) => void;
    onPaymentFailed?: (result: string) => void;
    onActionRequired?: (redirectUrl: string) => void;
    onLoadingStateChange?: (isLoading: boolean) => void;
  };
  locale?: Locale;
  disableErrorMessages?: boolean;
  manualActionHandling?: boolean;
};

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

CheckoutInstance Type

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

Troubleshooting

Common Issues

Checkout not appearing

• Ensure the container element exists before calling mount()
• Check that styles are imported with import '@odus/checkout/styles' when using npm/module approach
• Check browser console for errors
• Verify your API key and profile ID are correct
• Confirm that you're using the correct environment ('test' or 'live')

3DS Authentication Issues

• Ensure your returnUrl is properly configured
• Verify your domain is whitelisted in your Odus account settings
• If using manualActionHandling: true, make sure the onActionRequired callback is properly implemented

Manual 3DS Handling Not Working

• Check that both manualActionHandling: true is set and onActionRequired callback is provided
• Ensure the callback correctly handles the redirectUrl parameter
• Verify that any custom redirect implementation maintains all URL parameters

Related Guides

For a complete understanding of how to integrate the Checkout SDK in your application, please refer to these additional guides:

• Payment Flow Overview - Understand the different payment flows and how they work
• Handling Redirects - Learn how to handle redirects for 3DS authentication and alternative payment methods
• Making Payments - Step-by-step guide on how to process payments