メインコンテンツへスキップ

​
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

​
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

1

Install the SDK

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

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.
3

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

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

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

Test 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
You should see checkout events logged in your browser console.
7

Go Live

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

​
API Reference

​
Configuration

​
Initialize Options

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
OptionTypeRequiredDescription
mode"test" | "live"YesEnvironment mode: 'test' for development, 'live' for production
displayType"overlay" | "inline"NoDisplay type: 'overlay' for modal checkout (default), 'inline' for embedded checkout
onEventfunctionYesCallback function for handling checkout events

​
Checkout Options

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}
OptionTypeRequiredDescription
checkoutUrlstringYescreate checkout session API からのチェックアウトセッションURL
options.showTimerbooleanNoチェックアウトタイマーを表示または非表示にする。デフォルトは true。無効にすると、セッションが切れると checkout.link_expired イベントを受け取ります。
options.showSecurityBadgebooleanNoセキュリティバッジを表示または非表示にする。デフォルトは 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 オブジェクトを渡すことで、チェックアウトの外観をカスタマイズできます。テーマ設定はライトモードとダークモードの両方をサポートしており、色、ボーダー、テキスト、ボタン、ボーダー半径をカスタマイズできます。
このセクションでは、チェックアウトSDKを使用したクライアントサイドのテーマ設定について説明します。API を介してチェックアウトセッションを作成する際に、パラメータ theme_config を使用してサーバーサイドでテーマを設定することもできます。APIレベルの設定についてはチェックアウトテーマのカスタマイズを参照するか、ダッシュボードのデザインページを使用してライブプレビューでテーマを視覚的に設定してください。

​
基本的なテーマ設定

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

​
部分的テーマオーバーライド

特定のプロパティのみをオーバーライドできます。指定しないプロパティにはデフォルト値が使用されます。 
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
    },
  },
});

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

テーマ設定を他のチェックアウトオプションと組み合わせることができます。 
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 イベントを常に処理してください。

​
ベストプラクティス

  1. 一度初期化する: アプリケーションが読み込まれたときに SDK を一度初期化し、各チェックアウト試行時に行わない
  2. エラーハンドリング: イベントコールバックで適切なエラーハンドリングを常に実装する
  3. テストモード: 開発中は test モードを使用し、プロダクションの準備が整ったときにだけ live に切り替える
  4. イベントハンドリング: 完全なユーザーエクスペリエンスのためにすべての関連するイベントを処理する
  5. 有効な URL: 作成されたチェックアウトセッションAPIから有効なチェックアウト URL を常に使用する
  6. TypeScript: より良い型安全性と開発者体験のためにTypeScriptを使用する
  7. ローディング状態: チェックアウトが開かれる間、UXを改善するためにローディング状態を表示する
  8. タイマー管理: セッション期限切れを手動で処理したい場合は、タイマー (showTimer: false) を無効にする

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

可能性のある原因：
  • open() を呼び出す前に SDK が初期化されていない
  • 無効なチェックアウトURL
  • コンソールへのJavaScriptエラー
  • ネットワーク接続の問題
解決策：
  • チェックアウトを開く前に SDK の初期化が行われていることを確認する
  • コンソールエラーを確認する
  • チェックアウト URL が有効であり、チェックアウトセッションAPIからのものであることを確認する
  • ネットワーク接続を確認する
可能性のある原因：
  • イベントハンドラが正しく設定されていない
  • イベントの伝播を妨げるJavaScriptエラー
  • SDKが正しく初期化されていない
解決策：
  • Initialize() でイベントハンドラが適切に構成されていることを確認する
  • ブラウザコンソールでJavaScriptエラーを確認する
  • SDK の初期化が正常に完了していることを確認する
  • 最初に単純なイベントハンドラでテストする
可能性のある原因：
  • アプリケーションスタイルとのCSSの競合
  • テーマ設定が適用されていない
  • レスポンシブデザインの問題
解決策：
  • ブラウザのDevToolsでCSSの競合を確認する
  • テーマ設定が正しいことを確認する
  • 異なる画面サイズでテストする
  • オーバーレイとの z-index 競合がないことを確認する

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

Google Pay やその他のデジタルウォレットのセットアップに関する詳細情報については、デジタルウォレットページをご覧ください。
アップルペイはオーバーレイチェックアウトではまだサポートされていません。アップルペイのサポートは近日提供予定です。

​
ブラウザサポート

Dodo Payments チェックアウト SDK は以下のブラウザをサポートしています。
  • Chrome (最新)
  • Firefox (最新)
  • Safari (最新)
  • Edge (最新)
  • IE11 以上

​
オーバーレイ vs インラインチェックアウト

ユースケースに合ったチェックアウトタイプを選択してください。
機能オーバーレイチェックアウトインラインチェックアウト
統合の深さページ上部のモーダルページに完全に埋め込まれる
レイアウト制御限定完全な制御
ブランディングページと別のものシームレス
実装の労力低い高い
最適は既存ページの迅速な統合カスタムチェックアウトページ、高変換フロー
オーバーレイチェックアウトを使用して、既存のページに最小限の変更で迅速に統合します。インラインチェックアウトを使用する場合は、チェックアウトエクスペリエンスに最大限のコントロールを持ち、シームレスなブランディングが可能です。

​
関連リソース

Inline Checkout

ページにチェックアウトを直接埋め込んで、完全に統合されたエクスペリエンスを提供します。

Checkout Sessions API

チェックアウトセッションを作成し、チェックアウトエクスペリエンスを強化します。

Webhooks

サーバーサイドで支払いイベントをウェブフックで処理します。

Integration Guide

Dodo Payments を統合するための完全ガイド。
詳細なヘルプについては、Discord コミュニティを訪問するか、弊社の開発者サポートチームにお問い合わせください。
Last modified on April 20, 2026