Overlay Checkout - Dodo Payments Documentation

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.

Demo

Interactive Demo

See the overlay checkout in action with our live demo.

Quick Start

Get started with the Dodo Payments Checkout SDK in just a few lines of code:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Get your checkout URL from the create checkout session API.

Step-by-Step Integration Guide

Install the SDK

Install the Dodo Payments Checkout SDK using your preferred package manager:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Initialize the SDK in your application, typically in your main component or app entry point:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Always initialize the SDK before attempting to open the checkout. Initialization should happen once when your application loads.

Create a Checkout Button Component

Create a component that opens the checkout overlay:

// 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",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

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

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

Add Checkout to Your Page

Use the checkout button component in your application:

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

Handle Success and Failure Pages

Create pages to handle checkout redirects:

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

Test Your Integration

Start your development server:

npm run dev

Test the checkout flow:
- Click the checkout button
- Verify the overlay appears
- Test the payment flow using test credentials
- Confirm redirects work correctly

You should see checkout events logged in your browser console.

Go Live

When you’re ready for production:

Change the mode to 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Update your checkout URLs to use live checkout sessions from your backend
Test the complete flow in production
Monitor events and errors

API Reference

Configuration

Initialize Options

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

Option	Type	Required	Description
`mode`	`"test" \| "live"`	Yes	Environment mode: `'test'` for development, `'live'` for production
`displayType`	`"overlay" \| "inline"`	No	Display type: `'overlay'` for modal checkout (default), `'inline'` for embedded checkout
`onEvent`	`function`	Yes	Callback function for handling checkout events

Checkout Options

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}

Option	Type	Required	Description
`checkoutUrl`	`string`	Yes	create checkout session API からのチェックアウトセッションURL
`options.showTimer`	`boolean`	No	チェックアウトタイマーを表示または非表示にする。デフォルトは `true`。無効にすると、セッションが切れると `checkout.link_expired` イベントを受け取ります。
`options.showSecurityBadge`	`boolean`	No	セキュリティバッジを表示または非表示にする。デフォルトは `true`。

Methods

Open Checkout

Opens the checkout overlay with the specified checkout session URL.

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

You can also pass additional options to customize the checkout behavior:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
  },
});

チェックアウトを閉じる

プログラムでチェックアウトオーバーレイを閉じます。

DodoPayments.Checkout.close();

ステータスを確認

チェックアウトオーバーレイが現在開いているかどうかを返します。

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

イベント

SDK は onEvent コールバックを通じてリスニング可能なリアルタイムイベントを提供します。

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        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
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
    }
  }
});

イベントタイプ	説明
`checkout.opened`	チェックアウトオーバーレイが開かれた
`checkout.form_ready`	ユーザー入力を受け入れる準備が完了したチェックアウトフォーム。ローディング状態を隠すのに便利です。
`checkout.payment_page_opened`	支払いページが表示された
`checkout.customer_details_submitted`	カスタマーおよび請求情報が送信された
`checkout.closed`	チェックアウトオーバーレイが閉じられた
`checkout.redirect`	チェックアウトがリダイレクトを実行します
`checkout.error`	チェックアウト中にエラーが発生しました
`checkout.link_expired`	チェックアウトセッションが切れると発火します。`showTimer` が `false` に設定されている場合のみ受信します。

実装オプション

パッケージマネージャーインストール

ステップバイステップ統合ガイドに示されているように、npm、yarn、またはpnpmを介してインストールします。

CDN 実装

ビルドステップなしで素早く統合するには、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
            displayType: "overlay",
            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"
            });
        }
    </script>
</body>
</html>

テーマのカスタマイズ

チェックアウトを開くときに options パラメータに themeConfig オブジェクトを渡すことで、チェックアウトの外観をカスタマイズできます。テーマ設定はライトモードとダークモードの両方をサポートしており、色、ボーダー、テキスト、ボタン、ボーダー半径をカスタマイズできます。

Checkout SDK のクライアントサイドの themeConfig オプションは 非推奨 であり、次のメジャーバージョン（v2.0.0）で削除されます。このオプションを渡すと、ブラウザのコンソールに非推奨警告が記録されます。代わりに、API を使用して checkout session を作成する際にテーマを設定してください。customization.theme_config パラメーターを使用します。詳しくは Checkout Theme Customization を参照してください。または、ダッシュボードの Design page で視覚的に設定できます。session で設定したテーマは、overlay、inline、hosted のすべての checkout に適用されます。

このセクションでは、Checkout SDK を使用した、非推奨の クライアントサイド テーマ設定について説明します。推奨される方法は、API を使用して checkout session を作成する際に、theme_config パラメーターを使用して サーバーサイド でテーマを設定することです。API レベルでの設定については Checkout Theme Customization を参照してください。または、ダッシュボードの Design page を使用して、ライブプレビューでテーマを視覚的に設定できます。

基本的なテーマ設定

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

完全なテーマ設定

利用可能なすべてのテーマプロパティ:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

ライトモードのみ

ライトテーマのみをカスタマイズする場合:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

ダークモードのみ

ダークテーマのみをカスタマイズする場合:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

部分的なテーマの上書き

特定のプロパティのみを上書きできます。指定しなかったプロパティには、checkout のデフォルト値が使用されます:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

その他のオプションと組み合わせたテーマ設定

テーマ設定は、その他の checkout オプションと組み合わせることができます:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

TypeScript の型

TypeScript ユーザー向けに、テーマ設定のすべての型がエクスポートされています:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

エラーハンドリング

SDK は、イベントシステムを通じて詳細なエラー情報を提供します。onEvent コールバックには、必ず適切なエラーハンドリングを実装してください:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

エラー発生時に優れたユーザー体験を提供するため、checkout.error イベントを必ず処理してください。

ベストプラクティス

一度だけ初期化する: アプリケーションの読み込み時に SDK を一度だけ初期化し、checkout を試行するたびに初期化しないでください
エラーハンドリング: イベントコールバックには、必ず適切なエラーハンドリングを実装してください
テストモード: 開発中は test モードを使用し、本番環境の準備が整った場合にのみ live に切り替えてください
イベント処理: 完全なユーザー体験を提供するため、関連するすべてのイベントを処理してください
有効な URL: create checkout session API から取得した有効な checkout URL を必ず使用してください
TypeScript: より優れた型安全性と開発者体験のために TypeScript を使用してください
読み込み状態: UX を向上させるため、checkout の表示中は読み込み状態を表示してください
タイマー管理: session の有効期限切れを手動で処理する場合は、タイマー（showTimer: false）を無効にしてください

トラブルシューティング

Checkout not opening

考えられる原因:

open() を呼び出す前に SDK が初期化されていない
checkout URL が無効
コンソールに JavaScript エラーがある
ネットワーク接続の問題

解決策:

checkout を開く前に SDK の初期化が行われていることを確認する
コンソールエラーを確認する
checkout URL が有効で、create checkout session API から取得したものであることを確認する
ネットワーク接続を確認する

Events not firing

考えられる原因:

イベントハンドラーが正しく設定されていない
イベントの伝播を妨げる JavaScript エラーがある
SDK が正しく初期化されていない

解決策:

Initialize() でイベントハンドラーが正しく設定されていることを確認する
ブラウザのコンソールで JavaScript エラーを確認する
SDK の初期化が正常に完了したことを確認する
まずは単純なイベントハンドラーでテストする

Styling issues

考えられる原因:

アプリケーションのスタイルと CSS が競合している
テーマ設定が正しく適用されていない
レスポンシブデザインの問題

解決策:

ブラウザの DevTools で CSS の競合を確認する
テーマ設定が正しいことを確認する
異なる画面サイズでテストする
overlay との z-index の競合がないことを確認する

デジタルウォレットの有効化

Google Pay やその他のデジタルウォレットの設定方法について詳しくは、Digital Wallets ページを参照してください。

Apple Pay は現在、overlay checkout ではサポートされていません。Apple Pay は近日中にサポートされる予定です。

ブラウザのサポート

Dodo Payments Checkout SDK は、次のブラウザをサポートしています:

Chrome (最新)
Firefox (最新)
Safari (最新)
Edge (最新)
IE11+

Overlay Checkout と Inline Checkout の比較

ユースケースに適した checkout タイプを選択してください:

Feature	Overlay Checkout	Inline Checkout
Integration depth	Modal on top of page	Fully embedded in page
Layout control	Limited	Full control
Branding	Separate from page	Seamless
Implementation effort	Lower	Higher
Best for	Quick integration, existing pages	Custom checkout pages, high-conversion flows

既存のページへの変更を最小限に抑えて迅速に統合するには、overlay checkout を使用してください。checkout 体験を最大限に制御し、シームレスなブランディングを実現するには、inline checkout を使用してください。

Inline Checkout

完全に統合された体験を実現するため、checkout をページに直接埋め込みます。

Checkout Sessions API

checkout 体験を実現するための checkout session を作成します。

Webhooks

webhook を使用して、サーバーサイドで支払いイベントを処理します。

Integration Guide

Dodo Payments の統合に関する完全なガイドです。

さらにサポートが必要な場合は、Discord community に参加するか、開発者サポートチームにお問い合わせください。

​Overview

​Demo

Interactive Demo

​Quick Start

​Step-by-Step Integration Guide

​API Reference

​Configuration

​Initialize Options

​Checkout Options

​Methods

​Open Checkout

​チェックアウトを閉じる

​ステータスを確認

​イベント

​実装オプション

​パッケージマネージャーインストール

​CDN 実装

​テーマのカスタマイズ

​基本的なテーマ設定

​完全なテーマ設定

​ライトモードのみ

​ダークモードのみ

​部分的なテーマの上書き

​その他のオプションと組み合わせたテーマ設定

​TypeScript の型

​エラーハンドリング

​ベストプラクティス

​トラブルシューティング

​デジタルウォレットの有効化

​ブラウザのサポート

​Overlay Checkout と Inline Checkout の比較

​関連リソース

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Overview

Demo

Quick Start

Step-by-Step Integration Guide

API Reference

Configuration

Initialize Options

Checkout Options

Methods

Open Checkout

チェックアウトを閉じる

ステータスを確認

イベント

実装オプション

パッケージマネージャーインストール

CDN 実装

テーマのカスタマイズ

基本的なテーマ設定

完全なテーマ設定

ライトモードのみ

ダークモードのみ

部分的なテーマの上書き

その他のオプションと組み合わせたテーマ設定

TypeScript の型

エラーハンドリング

ベストプラクティス

トラブルシューティング

デジタルウォレットの有効化

ブラウザのサポート

Overlay Checkout と Inline Checkout の比較

関連リソース