@dodopayments/bunパッケージは、Bunサーバーに3つのリクエストハンドラーを提供します。Checkoutはcheckout URLを返し、CustomerPortalは顧客をCustomer Portalに移動させ、Webhooksはwebhookイベントを検証してコードにルーティングします。各ハンドラーは標準のRequestを受け取り、Responseを返すため、Bun.serve()のfetchハンドラーから呼び出せます。
Checkout Handler
静的、動的、checkout sessionのフローでcheckout URLを作成します。
Customer Portal
顧客がサブスクリプションと詳細情報を管理できるようにします。
Webhooks
Dodo Payments webhookイベントを受信して処理します。
インストール
1
Install the Package
このコマンドをプロジェクトのルートで実行します:このパッケージには
zod 3.25以降も必要で、peer dependencyとして指定されています。2
Set Up Environment Variables
プロジェクトのルートにBunは
.envファイルを作成します。Developer → API KeysでAPI keyを作成します。Developer → Webhooksでwebhook endpointを追加し、そのSigning secretをDODO_PAYMENTS_WEBHOOK_KEYにコピーします:.envファイルを自動的に読み込むため、例ではprocess.envからこれらの値を読み取ります。DODO_PAYMENTS_RETURN_URLはcheckout後に顧客が移動する場所です。environmentを渡さない場合、ハンドラーはlive_modeを使用します。test modeのAPI keyはtest_modeでのみ機能します。Route Handlerの例
すべての例ではBunのネイティブサーバー
Bun.serve()を使用し、fetchハンドラーでpathとmethodによってリクエストをルーティングします。- Checkout Handler
- Customer Portal Handler
- Webhook Handler
このハンドラーを使用して、BunサーバーにDodo Payments checkoutを追加します。静的ハンドラーは
GETリクエストを処理します。sessionおよびdynamicハンドラーはPOSTリクエストを処理します。dynamic checkoutの例では、サーバーがPOSTリクエストに対してdynamicCheckoutHandler(request)を返すことを前提としています。Checkout Route Handler
checkoutハンドラーは、Dodo Paymentsで支払いを受け付ける次の3つの方法すべてに対応しています:- 静的Payment Links: コードなしで支払いを受け付ける共有可能なURL。
- 動的Payment Links: カスタム詳細情報を指定して生成するpayment link。非推奨のendpointを使用します。
- Checkout Sessions: 商品カート、顧客情報、カスタマイズオプションを備えたホスト型checkout。推奨されるフローです。
Checkoutは次のoptionsを受け取ります:
このハンドラーは
GETリクエストに対して静的checkoutを提供します。POSTリクエストの場合、typeがdynamicならdynamic payment linkを作成し、それ以外の場合はcheckout sessionを作成します。
Static Checkout (GET)
Static Checkout (GET)
Dynamic Checkout (POST)
Dynamic Checkout (POST)
- パラメーターをPOST requestのJSON bodyとして送信します。
- 一回限りの支払いと継続支払いの両方に対応します。ハンドラーは商品を取得し、商品がrecurringならsubscriptionを、それ以外なら一回限りのpaymentを作成します。
- bodyには
billing(street、city、state、country、zipcodeを含む)とcustomerに加えて、product_idまたはproduct_cartが必要です。subscriptionにはproduct_idが必要です。 - 対応するbody fieldはすべて次を参照してください:
Response Format
Dynamic checkoutは、payment linkをcheckout URLとして含むJSON responseを返します:Checkout Sessions (POST)
Checkout Sessions (POST)
Checkout sessionsは、一回限りの購入とsubscription向けに、カスタマイズを完全に制御できるホスト型checkoutを作成します。必須フィールドは
product_cartのみで、少なくとも1つの商品が必要です。bodyにreturn_urlがない場合、ハンドラーはconfigのreturnUrlを使用します。各checkout_urlは1回だけ使用でき、24時間後に期限切れになります。confirm: trueを渡した場合は15分後に期限切れになります。payment_method_idで作成したsessionはcheckout_urlを返さないため、ハンドラーは400を返します。詳細および対応するすべてのfieldについては、Checkout Sessions Integration Guideを参照してください。Response Format
Checkout sessionsはcheckout URLを含むJSON responseを返します:Customer Portal Route Handler
Customer Portal route handlerは、指定された顧客のCustomer Portal sessionを作成し、ブラウザーをそこへリダイレクトします。CustomerPortalは、Checkoutと同じbearerTokenおよびenvironment optionsを受け取ります。
Query Parameters
customer_idがない場合、ハンドラーは400を返し、portal sessionを作成できない場合は500を返します。
Webhook Route Handler
webhook route handlerは、コードを実行する前に、webhookKeyとして渡されたwebhook secretで各リクエストを検証します:
- Method: POST requestのみ対応しています。その他のmethodは405を返します。
- Signature Verification:
webhookKeyを使用し、Standard Webhooks仕様に従ってwebhook-id、webhook-timestamp、webhook-signatureheadersを検証します。検証に失敗すると401を返します。 - Payload Validation: bodyをJSONとしてparseし、Zodで検証します。無効なJSONまたはpayloadには400を返します。
- Error Handling:
- 401: 無効なsignature
- 400: 無効なpayload
- 500: 検証中の内部エラー
- Event Routing: すべてのeventに対して
onPayloadを呼び出し、その後eventのtypeに対応するhandlerを呼び出して200を返します。
Bun.serve()に伝播し、requestは失敗します。