Express アダプタ - Dodo Payments Documentation

Checkout Handler

ExpressアプリにDodo Paymentsのチェックアウトを統合します。

Customer Portal

顧客がサブスクリプションや詳細を管理できるようにします。

Webhooks

Dodo PaymentsのWebhookイベントを受信し処理します。

インストール

Install the package

プロジェクトのルートで次のコマンドを実行します:

npm install @dodopayments/express

Set up environment variables

プロジェクトのルートに.envファイルを作成します:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

.envファイルやシークレットをバージョン管理にコミットしないでください。

ルートハンドラーの例

Checkout Handler
Customer Portal Handler
Webhook Handler

このハンドラーを使用してDodo PaymentsのチェックアウトをExpressアプリに統合します。静的（GET）、動的（POST）、およびセッション（POST）の各支払いフローに対応しています。

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session"
}))

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "test@example.com",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "test@example.com",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

このハンドラーを使って、Dodo Paymentsのカスタマーポータル経由で顧客がサブスクリプションや詳細を管理できるようにします。

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}))

curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

このハンドラーを使用して、Dodo PaymentsのWebhookイベントをExpressアプリで安全に受信および処理します。

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook',Webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
        // handle the payload
    },
    // ... other event handlers for granular control
}))

チェックアウトルートハンドラー

Dodo Paymentsはウェブサイトへの支払い統合に3種類の支払いフローをサポートしており、このアダプターはすべての支払いフローに対応しています。

静的支払いリンク: すぐに共有可能な URL で、迅速かつコード不要の支払い収集が可能です。
動的支払いリンク: API または SDK を使用してカスタム詳細を持つ支払いリンクをプログラム的に生成します。
チェックアウトセッション: 事前に設定された商品カートと顧客詳細を持つ、安全でカスタマイズ可能なチェックアウト体験を作成します。

Static Checkout (GET)

サポートされているクエリパラメーター

productId

string

必須

製品識別子（例: ?productId=pdt_nZuwz45WAs64n3l07zpQR）。

quantity

integer

製品の数量。

fullName

string

顧客のフルネーム。

firstName

string

顧客の名。

lastName

string

顧客の姓。

string

顧客のメールアドレス。

country

string

顧客の国。

addressLine

string

顧客の住所（番地）。

city

string

顧客の市区町村。

state

string

顧客の州/都道府県。

zipCode

string

顧客の郵便番号。

disableFullName

boolean

フルネームフィールドを無効にします。

disableFirstName

boolean

名フィールドを無効にします。

disableLastName

boolean

姓フィールドを無効にします。

disableEmail

boolean

メールフィールドを無効にします。

disableCountry

boolean

国フィールドを無効にします。

disableAddressLine

boolean

住所フィールドを無効にします。

disableCity

boolean

市区町村フィールドを無効にします。

disableState

boolean

州フィールドを無効にします。

disableZipCode

boolean

郵便番号フィールドを無効にします。

paymentCurrency

string

支払い通貨を指定します（例: USD）。

showCurrencySelector

boolean

通貨セレクターを表示します。

paymentAmount

integer

支払金額を指定します（例: $10.00の場合は1000）。

showDiscounts

boolean

割引フィールドを表示します。

metadata_*

string

metadata_で始まるクエリパラメーターはすべてメタデータとして渡されます。

productIdが欠けている場合、ハンドラーは400レスポンスを返します。無効なクエリパラメーターも400レスポンスになります。

レスポンス形式

静的チェックアウトは、チェックアウト URL を含む JSON レスポンスを返します:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Dynamic Checkout (POST)

POSTリクエストのJSONボディとしてパラメーターを送信します。
一回限りの支払いと定期支払いの両方に対応しています。
サポートされているPOSTボディフィールドの完全な一覧については、以下を参照してください:
- Request body for a One Time Payment Product
- Request body for a Subscription Product

レスポンス形式

動的チェックアウトは、チェックアウト URL を含む JSON レスポンスを返します:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Checkout Sessions (POST)

チェックアウトセッションは、ワンタイム購入とサブスクリプションの両方に対して完全な支払いフローを処理し、カスタマイズ制御も可能な、より安全なホスト型チェックアウト体験を提供します。詳細とサポートされているフィールドの完全なリストについては、チェックアウトセッション統合ガイドを参照してください。

レスポンス形式

チェックアウトセッションは、チェックアウト URL を含む JSON レスポンスを返します:

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

カスタマーポータルルートハンドラー

カスタマーポータルルートハンドラーを使用すると、Dodo Payments のカスタマーポータルを Express アプリケーションにシームレスに統合できます。

クエリパラメーター

customer_id

string

必須

ポータルセッション用の顧客ID（例: ?customer_id=cus_123）。

send_email

boolean

trueに設定すると、ポータルリンクを記載したメールを顧客に送信します。

customer_idが欠けている場合は400を返します。

ウェブフックルートハンドラー

メソッド: POST リクエストのみがサポートされています。他のメソッドは 405 を返します。
署名検証: webhookKey を使用してウェブフックの署名を検証します。検証に失敗した場合は 401 を返します。
ペイロード検証: Zod で検証されます。無効なペイロードには 400 を返します。
エラーハンドリング:
- 401: 無効な署名
- 400: 無効なペイロード
- 500: 検証中の内部エラー
イベントルーティング: ペイロードタイプに基づいて適切なイベントハンドラーを呼び出します。

サポートされているWebhookイベントハンドラー

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

LLM へのプロンプト

あなたは Express.js のエキスパート開発者アシスタントです。あなたのタスクは、ユーザーが既存の Express.js プロジェクトに @dodopayments/express アダプタを統合する手助けをすることです。

@dodopayments/express アダプタは、Dodo Payments のチェックアウト、カスタマーポータル、およびウェブフック機能のためのルートハンドラーを提供し、Express アプリに直接プラグインできるように設計されています。

まず、必要なパッケージをインストールします。ユーザーのプロジェクトに適したパッケージマネージャー (npm、yarn、または bun) を使用してください:

npm install @dodopayments/express

---

以下のように応答を構成してください:

1. ユーザーに統合したい機能を尋ねます。

"@dodopayments/express アダプタのどの部分をプロジェクトに統合したいですか？次の中から 1 つ以上を選択できます:

- チェックアウトルートハンドラー (商品チェックアウトの処理用)
- カスタマーポータルルートハンドラー (顧客のサブスクリプション/詳細の管理用)
- ウェブフックルートハンドラー (Dodo Payments のウェブフックイベントの受信用)
- すべて (3 つすべてを統合)"

---

2. ユーザーの選択に基づいて、各選択された機能の詳細な統合手順を提供します。

---

**チェックアウトルートハンドラーが選択された場合:**

**目的**: このハンドラーは、さまざまなタイプのチェックアウトフローを管理します。すべてのチェックアウトタイプ (静的、動的、セッション) は、プログラム的に処理するためのチェックアウト URL を含む JSON レスポンスを返します。

**統合**:
Express アプリに静的 (GET)、動的 (POST)、およびチェックアウトセッション (POST) のルートを作成します。

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// チェックアウトセッション用
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

設定オプション:

    bearerToken: Dodo Payments API キー (DODO_PAYMENTS_API_KEY 環境変数に保存することを推奨)。

    returnUrl (オプション): チェックアウト成功後にユーザーをリダイレクトする URL。

    environment: "test_mode" または "live_mode"

    type: "static" (GET)、"dynamic" (POST)、または "session" (POST)

GET (静的チェックアウト) は、次のクエリパラメータを期待します:

    productId (必須)

    quantity、顧客フィールド (fullName、email など)、およびメタデータ (metadata_*) はオプションです。

    戻り値: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (動的チェックアウト) は、支払い詳細 (一回限りまたはサブスクリプション) を含む JSON ボディを期待します。完全な POST スキーマについては、ドキュメントを参照してください:

    一回限りの支払い: https://docs.dodopayments.com/api-reference/payments/post-payments

    サブスクリプション: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    戻り値: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (チェックアウトセッション) - (推奨) よりカスタマイズ可能なチェックアウト体験。JSON で checkout_url を返します: パラメータは JSON ボディとして送信されます。一回限りの支払いと定期的な支払いの両方をサポートします。戻り値: {"checkout_url": "https://checkout.dodopayments.com/session/..."}。サポートされているフィールドの完全なリストについては、

  チェックアウトセッション統合ガイド: https://docs.dodopayments.com/developer-resources/checkout-session

カスタマーポータルルートハンドラーが選択された場合:

目的: このルートは、顧客が Dodo Payments ポータルを通じてサブスクリプションを管理できるようにします。

統合:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

クエリパラメータ:

    customer_id (必須): 例: ?customer_id=cus_123

    send_email (オプション): true の場合、顧客にポータルリンクがメールされます。

customer_id が欠けている場合、400 を返します。

ウェブフックルートハンドラーが選択された場合:

目的: Dodo Payments からの受信ウェブフックイベントを処理して、アプリ内のイベントをトリガーします。

統合:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // 一般的なペイロードを処理
  },
  // 以下の各イベントタイプに対して詳細なハンドラーを提供することもできます
}));

機能:

    POST メソッドのみが許可されます — 他は 405 を返します。

    署名検証は webhookKey を使用して行われます。無効な場合は 401 を返します。

    Zod ベースのペイロード検証。無効なスキーマの場合は 400 を返します。

    すべてのハンドラーは非同期関数です。

サポートされているウェブフックイベントハンドラー:

次のハンドラーのいずれかを渡すことができます:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

環境変数の設定:

プロジェクトで次の環境変数を定義してください:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" または "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

これらをコード内で以下のように使用します:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

セキュリティノート: 秘密情報をバージョン管理にコミットしないでください。ローカルでは.envファイルを使用し、デプロイ環境ではシークレットマネージャー (例: AWS, Vercel, Heroku など) を使用してください。

Checkout Handler

Customer Portal

Webhooks

​インストール

​ルートハンドラーの例

​チェックアウトルートハンドラー

​サポートされているクエリパラメーター

​レスポンス形式

​レスポンス形式

​レスポンス形式

​カスタマーポータルルートハンドラー

​クエリパラメーター

​ウェブフックルートハンドラー

​サポートされているWebhookイベントハンドラー

​LLM へのプロンプト

インストール

ルートハンドラーの例

チェックアウトルートハンドラー

サポートされているクエリパラメーター

レスポンス形式

レスポンス形式

レスポンス形式

カスタマーポータルルートハンドラー

クエリパラメーター

ウェブフックルートハンドラー

サポートされているWebhookイベントハンドラー

LLM へのプロンプト