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

概要

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>

TypeScriptサポート

SDKはTypeScriptで記述されており、包括的な型定義が含まれています。すべての公開APIは、より良い開発者体験とIntelliSenseサポートのために完全に型付けされています。

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

エラーハンドリング

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が有効であり、チェックアウトセッション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の有効化をリクエスト

以下の情報を含めて [email protected] にメールを送信します:

あなたの本番ドメイン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は、以下のブラウザをサポートしています:

Chrome（最新）
Firefox（最新）
Safari（最新）
Edge（最新）
IE11+

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

ユースケースに適したチェックアウトタイプを選択してください:

機能	オーバーレイチェックアウト	インラインチェックアウト
統合の深さ	ページの上にモーダル	ページに完全に埋め込まれる
レイアウト制御	限定的	完全な制御
ブランド化	ページから分離	シームレス
実装の手間	低い	高い
最適	迅速な統合、既存のページ	カスタムチェックアウトページ、高コンバージョンフロー

オーバーレイチェックアウトを使用して、既存のページに最小限の変更で迅速に統合します。インラインチェックアウトは、チェックアウト体験を最大限に制御し、シームレスなブランド化を望む場合に使用します。

インラインチェックアウト

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

チェックアウトセッションAPI

チェックアウト体験を強化するためにチェックアウトセッションを作成します。

Webhooks

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

統合ガイド

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

さらなるサポートが必要な場合は、Discordコミュニティを訪れるか、開発者サポートチームにお問い合わせください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

概要

デモ

インタラクティブデモ

クイックスタート

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

APIリファレンス

設定

初期化オプション

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

メソッド

チェックアウトを開く

チェックアウトを閉じる

ステータスを確認

イベント

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

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

実装オプション

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

CDN実装

TypeScriptサポート

エラーハンドリング

ベストプラクティス

トラブルシューティング

Apple Payの有効化

ブラウザサポート

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

関連リソース

インラインチェックアウト

チェックアウトセッションAPI

Webhooks

統合ガイド

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​概要

​デモ

インタラクティブデモ

​クイックスタート

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

​APIリファレンス

​設定

​初期化オプション

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

​メソッド

​チェックアウトを開く

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

​ステータスを確認

​イベント

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

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

​実装オプション

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

​CDN実装

​TypeScriptサポート

​エラーハンドリング

​ベストプラクティス

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

​Apple Payの有効化

​ブラウザサポート

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

​関連リソース

インラインチェックアウト

チェックアウトセッションAPI

Webhooks

統合ガイド

概要

デモ

クイックスタート

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

APIリファレンス

設定

初期化オプション

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

メソッド

チェックアウトを開く

チェックアウトを閉じる

ステータスを確認

イベント

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

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

実装オプション

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

CDN実装

TypeScriptサポート

エラーハンドリング

ベストプラクティス

トラブルシューティング

Apple Payの有効化

ブラウザサポート

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

関連リソース