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',
  profileId: 'your_profile_id',
  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',
  profileId: 'your_profile_id',
  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:

| Option | Type | Required | Description | | ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | ✅ | Your Odus API key obtained from the dashboard's API Keys page | | profileId | string | ✅ | Your Odus checkout profile ID obtained from the dashboard's Checkout Builder page | | checkoutKey | string | ✅ | Unique checkout key for this payment session | | paymentId | string | ✅ | The ID of the payment being processed | | environment | string | ✅ | API environment to use - either 'test' or 'live' | | returnUrl | string | ✅ | The URL where the customer will be redirected after 3DS authentication or other redirect flows | | locale | Locale | | Language code for checkout localization. If not set, automatically defaults to the customer's browser language when supported. If browser language is not supported, falls back to English. | | disableErrorMessages | boolean | | Set to true to disable built-in error messages (defaults to false) | | manualActionHandling | boolean | | Set to true to manually handle 3DS redirects via the onActionRequired callback (defaults to false) | | callbacks | object | | Event callback functions (see Callbacks) |

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

API Reference

OdusCheckout Class

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

CheckoutConfig Type

type CheckoutConfig = {
  apiKey: string;
  returnUrl: string;
  profileId: 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;
}

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