Odus Checkout SDK Documentation

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
• Advanced Usage
• API Reference
• Troubleshooting

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-js

import { OdusCheckout } from '@odus/checkout';

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" />;
}

Getting Started

Basic Implementation

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

import { OdusCheckout } from '@odus/checkout';

// 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)
    },
  },
  // 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;
};

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: PaymentResult) => void;
    onPaymentFailed?: (result: string) => void;
    onActionRequired?: (redirectUrl: string) => void;
  };
  locale?: 'en' | 'de' | 'es' | 'fr' | 'pl' | 'pt' | null;
  disableErrorMessages?: boolean;
  manualActionHandling?: boolean;
};

Troubleshooting

Common Issues

Checkout not appearing

• Ensure the container element exists before calling mount()
• 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

© 2025 Odus Payments, Inc. All rights reserved.