GitHub Repository
概要
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
Webhooks Documentation
Checkout Sessions
API Reference
サポート
boilerplate についてサポートが必要な場合:- Discord community で質問する。
- GitHub repository で問題を報告し、更新情報を確認する。
- support team にメールを送信する。