Overlay Checkout

オーバーレイ checkout は、ページ上にモーダルウィンドウを開きます。顧客はモーダル内に支払い情報を入力し、ページは背後に表示されたままになります。モーダルを閉じると、操作はページに戻ります。支払いを完了すると、return_url にリダイレクトされます。

Interactive Demo

ライブデモでオーバーレイ checkout の動作を確認できます。

クイックスタート

SDK をインストールして初期化し、create checkout session API の checkout URL を使用して checkout を開きます。

import { DodoPayments } from "dodopayments-checkout";

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

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

統合手順

Install the SDK

npm、yarn、または pnpm でインストールします。

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

アプリの読み込み時に、Initialize を 1 回呼び出します。通常はメインコンポーネントまたはアプリのエントリーポイントで呼び出します。

import { DodoPayments } from "dodopayments-checkout";

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

checkout を開く前に、必ず SDK を初期化してください。アプリケーションの読み込み時に 1 回だけ初期化し、checkout を試行するたびに初期化しないでください。

Create a Checkout Button

checkout モーダルを開くコンポーネントを作成します。

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

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.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 the Button to Your Page

アプリケーションで checkout ボタンコンポーネントを使用します。

// 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 Redirects

支払い後の checkout リダイレクトを処理するページを作成します。

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

開発サーバーを起動します。

npm run dev

checkout フローをテストします。
- checkout ボタンをクリックします
- モーダルが表示されることを確認します
- テスト用認証情報を使用して支払いフローをテストします
- リダイレクトが正しく動作することを確認します

ブラウザコンソールに checkout イベントが記録されることを確認できます。

Go Live

本番環境で使用する準備ができたら、次の手順を実行します。

モードを 'live' に変更します。

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

checkout URL を更新し、バックエンドの本番 checkout session を使用します
本番環境でフロー全体をテストします
イベントとエラーを監視します

API リファレンス

初期化

Initialize を 1 回呼び出して SDK をセットアップします。

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

DodoPayments.Initialize(options);

オプション	Type	必須	説明
`mode`	`"test" \| "live"`	はい	環境モード。開発環境では `"test"`、本番環境では `"live"`
`displayType`	`"overlay" \| "inline"`	いいえ	表示タイプ。モーダル checkout には `"overlay"`（デフォルト）、埋め込み checkout には `"inline"`
`onEvent`	`function`	はい	checkout イベントを処理する Callback function

Checkout を開く

checkout モーダルを開きます。

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

オプション	Type	必須	説明
`checkoutUrl`	`string`	はい	create checkout session API の checkout session URL
`options.showTimer`	`boolean`	いいえ	session timer を表示または非表示にします。デフォルトは `true` です。無効にすると、session の有効期限が切れたときに `checkout.link_expired` event を受信します。
`options.showSecurityBadge`	`boolean`	いいえ	security badge を表示または非表示にします。デフォルトは `true` です
`options.manualRedirect`	`boolean`	いいえ	`true` の場合、自動リダイレクトを無効にします。Checkout は支払い結果を含む `checkout.status` と、開く URL を含む `checkout.redirect_requested` を発行し、ナビゲーションは自身で処理します
`options.themeConfig`	`ThemeConfig`	いいえ	非推奨。 checkout session の作成時に、代わりにサーバー側でテーマを設定してください
`options.payButtonText`	`string`	いいえ	pay button のカスタムテキスト
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	いいえ	checkout の全体的な font size
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	いいえ	checkout の全体的な font weight

Checkout を閉じる

プログラムからモーダルを閉じます。

DodoPayments.Checkout.close();

ステータスを確認する

モーダルが現在開いているか確認します。

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

イベント

Initialize に渡した onEvent callback を使用して checkout イベントを監視します。

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Event	説明
`checkout.opened`	モーダルが開きました
`checkout.form_ready`	フォームがユーザー入力可能になりました。ローディング状態を非表示にするために使用します
`checkout.payment_page_opened`	支払いページが表示されました
`checkout.customer_details_submitted`	顧客情報と請求先情報が送信されました
`checkout.closed`	モーダルが閉じました
`checkout.redirect`	checkout はリダイレクトされます（銀行ページなど）
`checkout.error`	checkout 中にエラーが発生しました
`checkout.link_expired`	checkout session の有効期限が切れました。`showTimer` が `false` に設定されている場合にのみ受信します。

CDN 実装

ビルド手順なしで簡単に統合するには、CDN から SDK を読み込みます。

<!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>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      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://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

テーマのカスタマイズ

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

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

クライアント側でテーマを設定する必要がある場合は、options パラメーターに themeConfig を渡します。

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

テーマプロパティ

ライトモードとダークモードで使用できるすべてのテーマプロパティです。

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

エラー処理

onEvent callback には、必ずエラー処理を実装してください。

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

エラー発生時に優れたユーザーエクスペリエンスを提供できるよう、必ず checkout.error event を処理してください。

ベストプラクティス

1 回だけ初期化: アプリの読み込み時に Initialize を 1 回呼び出し、checkout ごとに呼び出さないでください
エラー処理: event callback に適切なエラー処理を実装します
テストモード: 開発中は "test" mode を使用し、本番環境の準備ができた場合にのみ "live" に切り替えます
イベント処理: 完全なユーザーエクスペリエンスを実現するため、関連するすべてのイベントを処理します
有効な URL: create checkout session API から取得した有効な checkout URL を必ず使用します
TypeScript: より優れた型安全性と開発者エクスペリエンスのために TypeScript を使用します
ローディング状態: UX を向上させるため、checkout が開いている間はローディング状態を表示します
タイマー管理: session の有効期限切れを手動で処理する場合は、タイマー（showTimer: false）を無効にします

トラブルシューティング

Events not firing

考えられる原因:

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

解決策:

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

Styling issues

考えられる原因:

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

解決策:

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

Digital Wallets

Google Pay やその他の digital wallets の設定方法について詳しくは、Digital Wallets ページを参照してください。

Apple Pay は現在、オーバーレイ checkout ではサポートされていません。

ブラウザのサポート

Dodo Payments Checkout SDK は次をサポートしています。

Chrome（最新版）
Firefox（最新版）
Safari（最新版）
Edge（最新版）
IE11 以降

オーバーレイ checkout と Inline Checkout の比較

用途に合った checkout タイプを選択してください。

Feature	Overlay	Inline
統合の深さ	ページ上のモーダル	ページに完全に埋め込み
レイアウトの制御	限定的	完全に制御可能
ブランディング	ページとは分離	ページに一致
実装の手間	少ない	多い
適している用途	迅速な統合、既存ページ	カスタム checkout ページ、高コンバージョンフロー

既存ページへの変更を最小限に抑え、より迅速に統合したい場合はオーバーレイ checkout を使用します。checkout エクスペリエンスを最大限に制御し、一貫したブランディングを実現したい場合は inline checkout を使用します。

Inline Checkout

完全に統合されたエクスペリエンスを実現するため、checkout をページに直接埋め込みます。

Checkout Sessions API

checkout エクスペリエンスを実現する checkout session を作成します。

Webhooks

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

Integration Guide

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

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

クイックスタート

統合手順

API リファレンス

初期化

Checkout を開く

Checkout を閉じる

ステータスを確認する

イベント

CDN 実装

テーマのカスタマイズ

テーマプロパティ

エラー処理

ベストプラクティス

トラブルシューティング

Digital Wallets

ブラウザのサポート

オーバーレイ checkout と Inline Checkout の比較

関連リソース

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​クイックスタート

​統合手順

​API リファレンス

​初期化

​Checkout を開く

​Checkout を閉じる

​ステータスを確認する

​イベント

​CDN 実装

​テーマのカスタマイズ

​テーマプロパティ

​エラー処理

​ベストプラクティス

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

​Digital Wallets

​ブラウザのサポート

​オーバーレイ checkout と Inline Checkout の比較

​関連リソース

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

クイックスタート

統合手順

API リファレンス

初期化

Checkout を開く

Checkout を閉じる

ステータスを確認する

イベント

CDN 実装

テーマのカスタマイズ

テーマプロパティ

エラー処理

ベストプラクティス

トラブルシューティング

Digital Wallets

ブラウザのサポート

オーバーレイ checkout と Inline Checkout の比較

関連リソース