GitHub Repository
FastAPIおよびDodo Payments boilerplateのソースコード。
概要
FastAPI boilerplateは、Dodo Paymentsがすでに接続されたPythonバックエンドです。チェックアウトセッションとCustomer Portalセッションを作成するエンドポイント、署名を検証するwebhookエンドポイント、Jinja2テンプレートからレンダリングされる価格ページが含まれています。このboilerplateは、ルートハンドラーにFastAPI
async、検証と設定にPydantic、Python SDKにdodopaymentsを使用します。ハンドラーは同期DodoPaymentsクライアントを呼び出します。イベントループのブロックを避けるには、AsyncDodoPaymentsに切り替え、その呼び出しをawaitしてください。特徴
boilerplateには次の機能が含まれています。- Quick Setup: クローンからサーバーの起動まで約5分です。
- Async Handlers: ルートハンドラーはFastAPI
async def関数です。 - Checkout Sessions: Python SDKを使用する、事前設定済みのチェックアウトエンドポイント。
- Webhook Handling: SDKの
unwrapメソッドで各署名を検証するwebhookエンドポイント。 - Customer Portal: Customer Portalセッションを作成するエンドポイント。
- Type Safety: Pydanticモデルでrequest bodyを検証し、コードではtype hintsを使用します。
- Environment Configuration:
pydantic-settingsが.envから設定を読み込み、検証します。
前提条件
始める前に、次のものが必要です。- Python 3.9以降。
dodopaymentsSDKで必要です。Python 3.11以降を推奨します。 - パッケージ管理用のpipまたはuv。
- Dodo Paymentsアカウント。ダッシュボードでAPI keyとwebhook signing secretを作成するために使用します。
クイックスタート
1
Clone the Repository
2
Create Virtual Environment
分離されたPython環境を設定します。または、依存関係をより高速に管理するためにuvを使用します。
3
Install Dependencies
4
Get API Credentials
Dodo Paymentsでサインアップし、ダッシュボードから認証情報を取得します。
- API Key: Dashboard → Developer → API Keysでキーを作成します。
- Webhook Key: Dashboard → Developer → Webhooksでエンドポイントを追加し、そのsigning secretをコピーします。エンドポイントURLは公開されており、HTTPSを使用する必要があります。マシンでイベントを受信するには、ローカルでのWebhookのテストを参照してください。
5
Configure Environment Variables
サンプルファイルをコピーして、ルートディレクトリに値にDodo Paymentsの認証情報を設定します。4つすべての変数が必須です。
.envファイルを作成します。.env
app/core/config.pyはpydantic-settingsで値を読み込み、1つでも不足または空の場合、アプリは起動に失敗します。DODO_PAYMENTS_RETURN_URLは、支払い後にチェックアウトから顧客を送る場所です。6
Add Your Products
app/lib/products.py内のサンプル商品を独自の商品に置き換えます。各product_idには、ダッシュボードのProductsにある商品のIDを設定します。価格ページにこれらの商品が表示されます。7
Run the Development Server
Swagger UIには
/api/checkout/、/api/webhook/、/api/customer-portal/エンドポイントが一覧表示され、すぐにテストできます。http://localhost:8000 は、料金ページを提供します。プロジェクト構成
API エンドポイント
app/main.py は、各 router を /api プレフィックスの下にマウントします。
各パスはスラッシュで終わります。FastAPI は、スラッシュなしのパスへのリクエストに対して
307 リダイレクトを返すため、特に webhook URL では正確なパスを使用してください。
コード例
これらの例は、app/api/ 内のファイルを簡略化したものです。
Checkout Session の作成
app/api/checkout.py は checkout session を作成し、その checkout_url を返します。リクエストボディには product_id、オプションの quantity、および name と email を含むオプションの customer オブジェクトを指定します。
Webhook の処理
app/api/webhook.py は SDK の unwrap メソッドでシグネチャを検証し、その後イベントタイプに応じて分岐します。
Customer Portal 統合
app/api/portal.py は customer ID 用の Customer Portal session を作成し、ポータルリンクを url として返します。
app/templates/index.html の料金ページは、ハードコードされた customer ID(cus_001)をこのエンドポイントに送信し、ハードコードされた名前とメールアドレスを checkout エンドポイントに送信します。これらをログイン中のユーザーの値に置き換えてください。
Webhook イベント
app/api/webhook.py の handler は、次のイベントに応じて分岐します。
別のイベントを処理するには、そのタイプ用の分岐を追加します。たとえば、正常に処理された返金には
refund.succeeded を使用します。すべてのイベントタイプについては、Webhook Event Guide を参照してください。
Webhook handler 内にビジネスロジックを追加して、次の処理を行います。
- データベース内のユーザー権限を更新する
- 確認メールを送信する
- デジタル製品へのアクセスをプロビジョニングする
- 分析データとメトリクスを追跡する
Webhook のローカルテスト
Dodo Payments からlocalhost にアクセスすることはできません。ローカル開発では、ngrok などのツールを使用してローカルサーバーを公開します。
/api/webhook/ を続けた URL を、Dodo Payments Dashboard のエンドポイントとして追加します。
.env 内の DODO_PAYMENTS_WEBHOOK_KEY にコピーし、サーバーを再起動します。アプリは .env を起動時にのみ読み込みます。
デプロイ
Docker
リポジトリにはDockerfile が含まれていません。コンテナでアプリを実行するには、この Dockerfile をリポジトリのルートに追加します。
COPY . . は、.env を含む、build context 内のすべてのファイルをコピーします。キーをイメージに含めないようにするには、.env を一覧にした .dockerignore ファイルを追加します。その後、イメージをビルドし、環境ファイルを指定して実行します。
Production に関する考慮事項
トラブルシューティング
Import errors or missing modules
Import errors or missing modules
仮想環境が有効化され、依存関係がインストールされていることを確認します。
Server fails to start with Directory 'app/static' does not exist
Server fails to start with Directory 'app/static' does not exist
app/main.py は app/static から静的ファイルを提供しますが、リポジトリにはそのディレクトリが含まれていません。mkdir app/static で作成し、サーバーを再度起動してください。Checkout session creation fails
Checkout session creation fails
次の一般的な原因を確認してください。
- Dodo Payments dashboard に product ID が存在しない。
.env内の API key またはDODO_PAYMENTS_ENVIRONMENTが正しくない。test mode key はtest_modeでのみ機能します。
400 response で SDK error を返します。詳細なエラーメッセージについては FastAPI logs を確認してください。Webhooks not receiving events
Webhooks not receiving events
ローカルテストでは、ngrok を使用してサーバーを公開します。Dodo dashboard で、ngrok URL に
/api/webhook/ を続けた URL を、末尾のスラッシュを含むエンドポイントとして追加します。そのエンドポイントの signing secret を、.env file 内の DODO_PAYMENTS_WEBHOOK_KEY にコピーしてください。Webhook signature verification fails
Webhook signature verification fails
.env内のDODO_PAYMENTS_WEBHOOK_KEYが、エンドポイントの signing secret と一致していることを確認します。- JSON として parse する前に、raw request body に対して signature を検証します。
webhook-id、webhook-timestamp、webhook-signatureの 3 つすべての headers をclient.webhooks.unwrap()に渡します。Standard Webhooks の signature は body だけでなくid.timestamp.bodyを対象とします。
詳細情報
Python SDK
async support 対応の Python SDK 完全ドキュメント
Webhooks Documentation
すべての webhook events とベストプラクティスについて学ぶ
Checkout Sessions
checkout session configuration の詳細を確認する
API Reference
Dodo Payments API 完全ドキュメント
サポート
boilerplate についてサポートが必要な場合:- Discord community で質問する。
- GitHub repository で問題を報告し、更新情報を確認する。
- support team にメールを送信する。