Framework Adaptors の概要

フレームワークアダプターを使用すると、各フレームワークのrequestとresponseの型を使って、アプリにDodo Paymentsのcheckout、Customer Portal、webhook handlerを追加できます。各アダプターは@dodopaymentsスコープのnpmパッケージです。パッケージは、checkoutの検証、Dodo Payments APIリクエスト、webhookペイロードの検証、型付きイベントコールバックに@dodopayments/coreを使用します。

各アダプターは、handlerの設定でAPI keyとenvironmentを受け取ります。これらの値はenvironment variablesに保存し、handlerの作成時に渡してください。

coding agentにアダプターを追加させるには、Agent Pluginをインストールしてください。

利用可能なフレームワークアダプター

使用するフレームワークに対応するアダプターを選択してください。

Next.js

App Routerでcheckout、customer portal、webhook用のroute handlerを提供します。

Nuxt

フルスタックVueフレームワークであるNuxt 3用のserver route handlerです。

Express

Node.jsアプリのExpress 5 route用のrequest handlerです。

Fastify

pluginアーキテクチャを備えたNode.jsフレームワーク、Fastify 5用のroute handlerです。

Hono

Cloudflare Workers、その他のedge runtime、Node.js向けのweb frameworkであるHono 4用のroute handlerです。

Astro

コンテンツに重点を置いたweb framework、Astro 4および5用のserver endpoint handlerです。

SvelteKit

フルスタックSvelteフレームワークであるSvelteKit 2用のserver route handlerです。

Remix

フルスタックReactフレームワークであるRemix 2用のloaderおよびaction handlerです。

TanStack Start

型安全なフルスタックReactフレームワークであるTanStack Start用のserver route handlerです。

Better Auth

Better Auth authentication framework用のpluginです。checkout、portal、usage、webhook endpointを追加し、sign-up時にcustomerを作成できます。

Convex

checkoutおよびcustomer portal actionとwebhook HTTP actionを備えたConvex backend用のcomponentです。

Bun

checkout、customer portal、webhook用のネイティブBun.serve() handlerです。

主な機能

route handlerアダプターには、次の機能が共通して備わっています。

機能	説明
Checkout Handler	Static、dynamic、checkout sessionのフロー
Customer Portal	顧客がサブスクリプションと請求情報を管理できるCustomer Portalを開くhandler
Webhook Handler	署名検証と、個別のevent typeに対応した型付きcallback
Environment Config	型付きhandler optionを介して渡されるAPI credentialとenvironment
Type Safety	handler optionとwebhook payload用のTypeScript型

Better Auth pluginとConvex componentは、それぞれ独自のAPIを通じて同じ機能を提供します。違いについては各ページを参照してください。

クイックスタート

route handlerアダプターを3つの手順で設定します。

Install the Adaptor

使用するフレームワークのパッケージをインストールします。

npm install @dodopayments/nextjs

npm install @dodopayments/nuxt

npm install @dodopayments/express

npm install @dodopayments/hono

npm install @dodopayments/astro

npm install @dodopayments/sveltekit

Configure Environment Variables

Dodo Paymentsのcredentialをenvironmentに追加します。dashboardのDeveloper → API KeysでAPI keyを、Developer → Webhooksでwebhook secretを作成します。test modeのAPI keyはtest_modeでのみ機能します。

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
DODO_PAYMENTS_ENVIRONMENT="test_mode" # or "live_mode"

environmentを渡さない場合、アダプターはlive_modeを使用します。

.envファイルやsecretをversion controlにcommitしないでください。

Create Route Handlers

checkout routeを作成します。customer portalとwebhook routeも同じパターンに従います。

Next.js
Express
Hono

// app/checkout/route.ts
import { Checkout } from "@dodopayments/nextjs";

export const GET = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
});

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

const app = 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 as "test_mode" | "live_mode",
}));

import { Hono } from "hono";
import { Checkout } from "@dodopayments/hono";

const app = new Hono();

app.get('/checkout', Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
}));

checkout routeはcheckout URLを返すようになります。各アダプターのページでは、customer portalとwebhook handlerについて説明し、すべてのoptionを一覧表示しています。

Checkout Flowの種類

route handlerアダプターは3種類のcheckout flowをサポートします。Better Auth pluginはcheckout sessionとdeprecated dynamic checkoutをサポートします。Convex componentはcheckout sessionのみをサポートします。

Static Checkout (GET)

Static checkoutは1つの商品用のpayment linkを返すため、共有またはredirectできます。query parameterとしてproduct IDを渡します。

/api/checkout?productId=pdt_xxx&quantity=1

handlerはproductが存在することを確認し、linkをcheckout_urlとして返します。オプションのquery parameterを使用して顧客情報を事前入力し、checkout formを制御できます。

Dynamic Checkout (POST)

Dynamic checkoutは、カスタム情報を含むJSON bodyからpayment linkを作成します。billingとcustomerは必須です。

{
  "product_id": "pdt_xxx",
  "quantity": 1,
  "billing": {
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "street": "123 Main St",
    "zipcode": "94102"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  }
}

one-time paymentとsubscriptionの両方をサポートします。product typeに応じてdeprecatedなPOST /paymentsまたはPOST /subscriptions endpointを呼び出すため、新しい統合にはcheckout sessionを使用してください。

Checkout Sessions (POST)

Checkout sessionが推奨されるflowです。最も多くのoptionを提供し、複数の商品を含むcartを受け付けます。

{
  "product_cart": [
    { "product_id": "pdt_xxx", "quantity": 1 },
    { "product_id": "pdt_yyy", "quantity": 2 }
  ],
  "customer": {
    "email": "customer@example.com"
  }
}

サポートされているすべてのfieldについては、Checkout Sessions Guideを参照してください。

Webhook Eventの処理

すべてのroute handlerアダプターはWebhooks handlerをexportします。これはwebhook secretと、個別のevent type用のオプションの型付きcallbackを受け取ります。onPayloadはすべてのeventで実行されます。

Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!,
  onPayload: async (payload) => {
    // Handle any webhook event
  },
  onPaymentSucceeded: async (payload) => {
    // Handle successful payments
  },
  onSubscriptionActive: async (payload) => {
    // Handle new subscriptions
  },
  // ...more than 40 optional event callbacks in total
});

callbackは、payment、refund、dispute、subscription、license key、abandoned checkout、dunning、credit、entitlement grant、payout eventを対象とします。Better Auth pluginはwebhooks()で同じcallbackを受け付け、Convex componentはcreateDodoWebhookHandlerで受け付けます。

各webhook handlerはStandard Webhooks libraryを使用してwebhook-id、webhook-signature、webhook-timestamp headerを検証し、その後Zod schemaでpayloadを検証します。無効なrequestは、callbackが実行される前にerror statusで拒否されます。

適切なアダプターの選択

フレームワーク	適した用途	Runtime
Next.js	App Routerを使用するフルスタックReactアプリ	Node.js、Edge
Nuxt	フルスタックVue.jsアプリケーション	Node.js
Express	REST APIと従来型のNode.jsアプリ	Node.js
Fastify	高性能API	Node.js
Hono	Edgeデプロイ、Cloudflare Workers	Edge、Node.js
Astro	server endpointを備えたコンテンツサイト	Node.js、Edge
SvelteKit	フルスタックSvelteアプリケーション	Node.js
Remix	nested routingを備えたフルスタックReact	Node.js
TanStack Start	型安全なフルスタックReact	Node.js
Better Auth	すでにBetter Authを使用しているアプリ	Various
Convex	backendにConvexを使用しているアプリ	Convex Runtime
Bun	ネイティブBun server application	Bun

ヘルプを受ける

framework adaptor に関するヘルプ：

Discord：コミュニティサーバーで質問してください。
Email：support@dodopayments.com までお問い合わせください。
GitHub：すべての adaptor を収録している dodo-adapters リポジトリで issue を作成してください。
Documentation：API リファレンスをご覧ください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

利用可能なフレームワークアダプター

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

主な機能

クイックスタート

Checkout Flowの種類

Webhook Eventの処理

適切なアダプターの選択

ヘルプを受ける

​利用可能なフレームワークアダプター

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

​主な機能

​クイックスタート

​Checkout Flowの種類

​Webhook Eventの処理

​適切なアダプターの選択

​ヘルプを受ける

利用可能なフレームワークアダプター

主な機能

クイックスタート

Checkout Flowの種類

Webhook Eventの処理

適切なアダプターの選択

ヘルプを受ける