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

概要

Dodo Payments Checkout SDKは、私たちの支払いオーバーレイをあなたのウェブアプリケーションにシームレスに統合する方法を提供します。TypeScriptとモダンなウェブ標準で構築されており、リアルタイムイベント処理とカスタマイズ可能なテーマを備えた堅牢な決済ソリューションを提供します。

デモ

インタラクティブデモ

ライブデモでオーバーレイチェックアウトの動作を確認してください。

クイックスタート

Dodo Payments Checkout SDKを数行のコードで始めましょう：

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

チェックアウトセッション作成APIからチェックアウトURLを取得してください。

ステップバイステップの統合ガイド

SDKをインストール

お好みのパッケージマネージャーを使用してDodo Payments Checkout SDKをインストールします：

npm install dodopayments-checkout

SDKを初期化

アプリケーション内でSDKを初期化します。通常はメインコンポーネントまたはアプリのエントリポイントで行います：

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

チェックアウトを開く前に必ずSDKを初期化してください。初期化はアプリケーションが読み込まれるときに一度行う必要があります。

チェックアウトボタンコンポーネントを作成

チェックアウトオーバーレイを開くコンポーネントを作成します：

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

ページにチェックアウトを追加

アプリケーション内でチェックアウトボタンコンポーネントを使用します：

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

成功ページと失敗ページを処理

チェックアウトリダイレクトを処理するページを作成します：

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

統合をテスト

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

npm run dev

チェックアウトフローをテストします：
- チェックアウトボタンをクリック
- オーバーレイが表示されることを確認
- テストクレデンシャルを使用して決済フローをテスト
- リダイレクトが正しく機能することを確認

ブラウザのコンソールにチェックアウトイベントが記録されているのを確認する必要があります。

本番環境に移行

本番環境の準備ができたら：

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

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

バックエンドからライブチェックアウトセッションを使用するようにチェックアウトURLを更新します
本番環境で完全なフローをテストします
イベントとエラーを監視します

APIリファレンス

設定

初期化オプション

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

オプション	タイプ	必須	説明
`mode`	`"test" \| "live"`	はい	環境モード: `'test'`は開発用、`'live'`は本番用
`displayType`	`"overlay" \| "inline"`	いいえ	表示タイプ: `'overlay'`はモーダルチェックアウト（デフォルト）、`'inline'`は埋め込みチェックアウト
`onEvent`	`function`	はい	チェックアウトイベントを処理するためのコールバック関数

チェックアウトオプション

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

オプション	タイプ	必須	説明
`checkoutUrl`	`string`	はい	チェックアウトセッションAPIからのチェックアウトセッションURL
`options.showTimer`	`boolean`	いいえ	チェックアウトタイマーを表示または非表示にします。デフォルトは`true`です。無効にすると、セッションが期限切れになると`checkout.link_expired`イベントが受信されます。
`options.showSecurityBadge`	`boolean`	いいえ	セキュリティバッジを表示または非表示にします。デフォルトは`true`です。
`options.manualRedirect`	`boolean`	いいえ	有効にすると、チェックアウトは完了後に自動的にリダイレクトされません。代わりに、`checkout.status`および`checkout.redirect_requested`イベントを受信して、リダイレクトを自分で処理します。

メソッド

チェックアウトを開く

指定されたチェックアウトセッションURLでチェックアウトオーバーレイを開きます。

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

チェックアウトの動作をカスタマイズするために追加のオプションを渡すこともできます:

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

manualRedirectを使用する場合、チェックアウト完了をonEventコールバックで処理します:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

チェックアウトを閉じる

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

DodoPayments.Checkout.close();

ステータスを確認

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

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

イベント

SDKは、onEventコールバックを通じてリスンできるリアルタイムイベントを提供します:

チェックアウトステータスイベントデータ

manualRedirectが有効な場合、次のデータを持つcheckout.statusイベントを受信します:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

チェックアウトリダイレクト要求イベントデータ

manualRedirectが有効な場合、次のデータを持つcheckout.redirect_requestedイベントを受信します:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

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
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

イベントタイプ	説明
`checkout.opened`	チェックアウトオーバーレイが開かれました
`checkout.payment_page_opened`	支払いページが表示されました
`checkout.customer_details_submitted`	顧客および請求情報が送信されました
`checkout.closed`	チェックアウトオーバーレイが閉じられました
`checkout.redirect`	チェックアウトがリダイレクトを実行します
`checkout.error`	チェックアウト中にエラーが発生しました
`checkout.link_expired`	チェックアウトセッションが期限切れになったときに発火します。`showTimer`が`false`に設定されている場合のみ受信されます。
`checkout.status`	`manualRedirect`が有効な場合に発火します。チェックアウトのステータス（`succeeded`、`failed`、または`processing`）を含みます。
`checkout.redirect_requested`	`manualRedirect`が有効な場合に発火します。顧客をリダイレクトするためのURLを含みます。

実装オプション

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

ステップバイステップの統合ガイドに示されているように、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オブジェクトを渡すことでカスタマイズできます。テーマ設定は、ライトモードとダークモードの両方をサポートしており、色、境界線、テキスト、ボタン、境界半径をカスタマイズできます。

基本テーマ設定

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,
    manualRedirect: false,
    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を向上させてください
手動リダイレクト: チェックアウト後のナビゲーションをカスタム制御する必要がある場合はmanualRedirectを使用してください
タイマー管理: セッションの期限切れを手動で処理したい場合はタイマー（showTimer: false）を無効にしてください

トラブルシューティング

チェックアウトが開かない

考えられる原因:

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

解決策:

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

イベントが発火しない

考えられる原因:

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

解決策:

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

スタイリングの問題

考えられる原因:

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

解決策:

ブラウザの DevTools で CSS の競合を確認してください。
テーマ設定が正しいことを確認してください。
異なる画面サイズでテストしてください。
オーバーレイとの z-index の競合がないことを確認してください。

Apple Pay の有効化

Apple Pay を使用すると、顧客は保存された支払い方法を使用して迅速かつ安全に支払いを完了できます。有効にすると、顧客はサポートされているデバイスのチェックアウトオーバーレイから直接 Apple Pay モーダルを起動できます。

Apple Pay は iOS 17+、iPadOS 17+、macOS の Safari 17+ でサポートされています。

本番環境でドメインの Apple Pay を有効にするには、次の手順に従ってください：

Apple Pay ドメイン関連ファイルをダウンロードしてアップロード

Apple Pay ドメイン関連ファイルをダウンロードします。ファイルをあなたのウェブサーバーの/.well-known/apple-developer-merchantid-domain-associationにアップロードします。例えば、あなたのウェブサイトがexample.comの場合、ファイルをhttps://example.com/well-known/apple-developer-merchantid-domain-associationで利用可能にします。

Apple Pay の有効化をリクエスト

以下の情報を含めて support@dodopayments.com にメールを送信してください：

あなたの本番ドメインURL（例: https://example.com）
あなたのドメインでApple Payを有効にするリクエスト

Apple Pay があなたのドメインに対して有効になったら、1-2 営業日以内に確認の連絡が届きます。

Apple Pay の利用可能性を確認

確認の連絡を受け取った後、チェックアウトで Apple Pay をテストします：

サポートされているデバイス (iOS 17+、iPadOS 17+、または macOS の Safari 17+) でチェックアウトを開きます。
Apple Pay ボタンが支払いオプションとして表示されることを確認します。
完全な支払いフローをテストします。

Apple Pay は本番環境で支払いオプションとして表示される前に、あなたのドメインに対して有効にする必要があります。Apple Pay を提供する予定がある場合は、ライブにする前にサポートに連絡してください。

ブラウザサポート

Dodo Payments Checkout SDK は以下のブラウザをサポートしています：

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

概要

デモ

インタラクティブデモ

クイックスタート

ステップバイステップの統合ガイド

APIリファレンス

設定

初期化オプション

チェックアウトオプション

メソッド

チェックアウトを開く

チェックアウトを閉じる

ステータスを確認

イベント

チェックアウトステータスイベントデータ

チェックアウトリダイレクト要求イベントデータ

実装オプション

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

CDN実装

テーマのカスタマイズ

基本テーマ設定

完全なテーマ設定

ライトモードのみ

ダークモードのみ

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

他のオプションとのテーマ設定

TypeScript タイプ

エラーハンドリング

ベストプラクティス

トラブルシューティング

Apple Pay の有効化

ブラウザサポート

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​概要

​デモ

インタラクティブデモ

​クイックスタート

​ステップバイステップの統合ガイド

​APIリファレンス

​設定

​初期化オプション

​チェックアウトオプション

​メソッド

​チェックアウトを開く

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

​ステータスを確認

​イベント

​チェックアウトステータスイベントデータ

​チェックアウトリダイレクト要求イベントデータ

​実装オプション

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

​CDN実装

​テーマのカスタマイズ

​基本テーマ設定

​完全なテーマ設定

​ライトモードのみ

​ダークモードのみ

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

​他のオプションとのテーマ設定

​TypeScript タイプ

​エラーハンドリング

​ベストプラクティス

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

​Apple Pay の有効化

​ブラウザサポート

概要

デモ

クイックスタート

ステップバイステップの統合ガイド

APIリファレンス

設定

初期化オプション

チェックアウトオプション

メソッド

チェックアウトを開く

チェックアウトを閉じる

ステータスを確認

イベント

チェックアウトステータスイベントデータ

チェックアウトリダイレクト要求イベントデータ

実装オプション

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

CDN実装

テーマのカスタマイズ

基本テーマ設定

完全なテーマ設定

ライトモードのみ

ダークモードのみ

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

他のオプションとのテーマ設定

TypeScript タイプ

エラーハンドリング

ベストプラクティス

トラブルシューティング

Apple Pay の有効化

ブラウザサポート