> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Express アダプタ

> Dodo Payments を Express App Router プロジェクトに統合する方法を学びます。チェックアウト、カスタマーポータル、ウェブフック、および安全な環境設定をカバーします。

<CardGroup cols={2}>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    ExpressアプリにDodo Paymentsのチェックアウトを統合します。
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    顧客がサブスクリプションや詳細を管理できるようにします。
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Dodo PaymentsのWebhookイベントを受信し処理します。
  </Card>
</CardGroup>

## インストール

<Steps>
  <Step title="Install the package">
    プロジェクトのルートで次のコマンドを実行します:

    ```bash theme={null}
    npm install @dodopayments/express
    ```
  </Step>

  <Step title="Set up environment variables">
    プロジェクトのルートに<code>.env</code>ファイルを作成します:

    ```env expandable theme={null}
    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
    ```

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

## ルートハンドラーの例

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

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      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"
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      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
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      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"
      }'
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/express";

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

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      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
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      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
      }))
      ```
    </CodeGroup>
  </Tab>
</Tabs>

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

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

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

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### サポートされているクエリパラメーター

    <ParamField query="productId" type="string" required>
      製品識別子（例: <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>）。
    </ParamField>

    <ParamField query="quantity" type="integer">
      製品の数量。
    </ParamField>

    <ParamField query="fullName" type="string">
      顧客のフルネーム。
    </ParamField>

    <ParamField query="firstName" type="string">
      顧客の名。
    </ParamField>

    <ParamField query="lastName" type="string">
      顧客の姓。
    </ParamField>

    <ParamField query="email" type="string">
      顧客のメールアドレス。
    </ParamField>

    <ParamField query="country" type="string">
      顧客の国。
    </ParamField>

    <ParamField query="addressLine" type="string">
      顧客の住所（番地）。
    </ParamField>

    <ParamField query="city" type="string">
      顧客の市区町村。
    </ParamField>

    <ParamField query="state" type="string">
      顧客の州/都道府県。
    </ParamField>

    <ParamField query="zipCode" type="string">
      顧客の郵便番号。
    </ParamField>

    <ParamField query="disableFullName" type="boolean">
      フルネームフィールドを無効にします。
    </ParamField>

    <ParamField query="disableFirstName" type="boolean">
      名フィールドを無効にします。
    </ParamField>

    <ParamField query="disableLastName" type="boolean">
      姓フィールドを無効にします。
    </ParamField>

    <ParamField query="disableEmail" type="boolean">
      メールフィールドを無効にします。
    </ParamField>

    <ParamField query="disableCountry" type="boolean">
      国フィールドを無効にします。
    </ParamField>

    <ParamField query="disableAddressLine" type="boolean">
      住所フィールドを無効にします。
    </ParamField>

    <ParamField query="disableCity" type="boolean">
      市区町村フィールドを無効にします。
    </ParamField>

    <ParamField query="disableState" type="boolean">
      州フィールドを無効にします。
    </ParamField>

    <ParamField query="disableZipCode" type="boolean">
      郵便番号フィールドを無効にします。
    </ParamField>

    <ParamField query="paymentCurrency" type="string">
      支払い通貨を指定します（例: <code>USD</code>）。
    </ParamField>

    <ParamField query="showCurrencySelector" type="boolean">
      通貨セレクターを表示します。
    </ParamField>

    <ParamField query="paymentAmount" type="integer">
      支払金額を指定します（例: \$10.00の場合は<code>1000</code>）。
    </ParamField>

    <ParamField query="showDiscounts" type="boolean">
      割引フィールドを表示します。
    </ParamField>

    <ParamField query="metadata_*" type="string">
      <code>metadata\_</code>で始まるクエリパラメーターはすべてメタデータとして渡されます。
    </ParamField>

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

    ### レスポンス形式

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

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * POSTリクエストのJSONボディとしてパラメーターを送信します。
    * 一回限りの支払いと定期支払いの両方に対応しています。
    * サポートされているPOSTボディフィールドの完全な一覧については、以下を参照してください:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### レスポンス形式

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

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    チェックアウトセッションは、ワンタイム購入とサブスクリプションの両方に対して完全な支払いフローを処理し、カスタマイズ制御も可能な、より安全なホスト型チェックアウト体験を提供します。

    詳細とサポートされているフィールドの完全なリストについては、[チェックアウトセッション統合ガイド](https://docs.dodopayments.com/developer-resources/checkout-session) を参照してください。

    ### レスポンス形式

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

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

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

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

### クエリパラメーター

<ParamField query="customer_id" type="string" required>
  ポータルセッション用の顧客ID（例: <code>?customer\_id=cus\_123</code>）。
</ParamField>

<ParamField query="send_email" type="boolean">
  <code>true</code>に設定すると、ポータルリンクを記載したメールを顧客に送信します。
</ParamField>

<Warning>
  <code>customer\_id</code>が欠けている場合は400を返します。
</Warning>

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

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

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

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  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>;
  ```
</CodeGroup>

***

## 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 など) を使用してください。
```