Skip to main content

​
Overview

The Dodo Payments Checkout SDK provides a seamless way to integrate our payment overlay into your web application. Built with TypeScript and modern web standards, it offers a robust solution for handling payments with real-time event handling and customizable themes.
Overlay Checkout Cover Image

​
Resources

​
Installation

# Using npm
npm install dodopayments-checkout

# Using yarn
yarn add dodopayments-checkout

# Using pnpm
pnpm add dodopayments-checkout

​
Quick Start

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "live", // 'test' or 'live'
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123" // Get this url from create checkout session api
});

​
Configuration

​
Initialize Options

interface InitializeOptions {
  mode: "test" | "live";
  onEvent: (event: CheckoutEvent) => void;
}
OptionTypeRequiredDescription
modestringYesEnvironment mode: ‘test’ or ‘live’
onEventfunctionYesCallback function for handling checkout events

​
Checkout Options

interface CheckoutOptions {
  checkoutUrl: string;
}
OptionTypeRequiredDescription
checkoutUrlstringYesCheckout session URL from create checkout session API

​
Event Handling

The SDK provides real-time events that you can listen to: 
DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        break;
    }
  }
});

​
Methods

​
Open Checkout

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123" // Get this url from create checkout session api
});

​
Close Checkout

DodoPayments.Checkout.close();

​
Check Status

const isOpen = DodoPayments.Checkout.isOpen();

​
Browser Support

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • IE11+
Note: Apple Pay is not currently supported in the overlay checkout experience. We plan to add support for Apple Pay in a future release.

​
CDN Implementation

For quick integration, you can use our CDN: 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123" // Get this url from create checkout session api
            });
        }
    </script>
</body>
</html>

​
TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions. All public APIs are fully typed for better developer experience.

​
Error Handling

The SDK provides detailed error information through the event system. Always implement proper error handling in your onEvent callback: 
DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});

​
Best Practices

  1. Always initialize the SDK before attempting to open the checkout
  2. Implement proper error handling in your event callback
  3. Use the test mode during development
  4. Handle all relevant events for a complete user experience
  5. Use valid checkout URLs from the create checkout session API
  6. Use TypeScript for better type safety and developer experience

​
Step-by-Step Guide

​
1. Project Setup

First, ensure you have a modern JavaScript/TypeScript project. We recommend using Next.js, React, or Vue.js.

​
2. Install the SDK

Install the Dodo Payments Checkout SDK using your preferred package manager: 
# Using npm
npm install dodopayments-checkout

# Using yarn
yarn add dodopayments-checkout

# Using pnpm
pnpm add dodopayments-checkout

​
3. Basic Implementation

Create a new component for your checkout button: 
// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test", // Change to 'live' for production
      onEvent: (event) => {
        console.log("Checkout event:", event);
        
        // Handle different events
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            // Handle error
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://checkout.dodopayments.com/session/cks_123" // Get this url from create checkout session api
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

​
4. Add to Your Page

Use the checkout button in your page: 
// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

​
5. Handle Success and Failure

Create success and failure pages: 
// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful!</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

​
6. Testing Your Integration

  1. Start your development server:
npm run dev
  1. Test the checkout flow:
    • Click the checkout button
    • Verify the overlay appears
    • Test the payment flow using test credentials
    • Confirm redirects work correctly

​
7. Going Live

When you’re ready to go live:
  1. Change the mode to ‘live’:
DodoPayments.Initialize({
  mode: "live",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. Update your checkout URLs to use live checkout sessions
  2. Test the complete flow in production
  3. Monitor events and errors

​
Common Issues and Solutions

  1. Checkout not opening
    • Verify SDK initialization
    • Check for console errors
    • Ensure checkout URL is valid and from create checkout session API
  2. Events not firing
    • Confirm event handler is properly set up
    • Check for JavaScript errors
    • Verify network connectivity
  3. Styling issues
    • Ensure no CSS conflicts
    • Check theme settings
    • Verify responsive design
For more help, visit our Discord or contact our developer support team.
⌘I