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 オブジェクトを渡すことで、チェックアウトの外観をカスタマイズできます。テーマ設定はライトモードとダークモードの両方をサポートしており、色、ボーダー、テキスト、ボタン、ボーダー半径をカスタマイズできます。

このセクションでは、チェックアウト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 イベントを常に処理してください。

ベストプラクティス

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

トラブルシューティング

Checkout not opening

可能性のある原因：

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

解決策：

チェックアウトを開く前に SDK の初期化が行われていることを確認する
コンソールエラーを確認する
チェックアウト URL が有効であり、チェックアウトセッションAPIからのものであることを確認する
ネットワーク接続を確認する

Events not firing

可能性のある原因：

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

解決策：

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

Styling issues

可能性のある原因：

アプリケーションスタイルとの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 コミュニティを訪問するか、弊社の開発者サポートチームにお問い合わせください。

​Overview

​Demo

Interactive Demo

​Quick Start

​Step-by-Step Integration Guide

​API Reference

​Configuration

​Initialize Options

​Checkout Options

​Methods

​Open Checkout

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

​ステータスを確認

​イベント

​実装オプション

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

​CDN 実装

​テーマのカスタマイズ

​基本的なテーマ設定

​完全なテーマ設定

​ライトモードのみ

​ダークモードのみ

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

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

​TypeScript タイプ

​エラーハンドリング

​ベストプラクティス

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

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

​ブラウザサポート

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

​関連リソース

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 タイプ

エラーハンドリング

ベストプラクティス

トラブルシューティング

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

ブラウザサポート

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

関連リソース