メインコンテンツへスキップ

GitHub Repository

FastAPI + Dodo Payments のボイラープレートを完成させる

​
概要

FastAPI ボイラープレートは、Dodo Payments を Python バックエンドに統合するための生産準備が整った出発点を提供します。このテンプレートには、チェックアウトセッションの処理、Webhook の検証、カスタマーポータルの統合、非同期 API パターンが含まれており、迅速に支払いを受け入れることができます。
このボイラープレートでは、非同期/await パターンの FastAPI、検証には Pydantic、シームレスな API 統合には dodopayments Python SDK を使用しています。

​
特徴

  • クイックセットアップ - 5 分以内に始められます
  • 非同期サポート - FastAPI のネイティブな非同期/待機パターンで構築
  • チェックアウトセッション - Python SDK を使用した事前設定されたチェックアウトフロー
  • Webhook 処理 - 署名検証付きの安全な Webhook エンドポイント
  • カスタマーポータル - 簡単なカスタマーポータルセッションの作成
  • 型安全性 - 完全な Pydantic 検証と型ヒント
  • 環境設定 - すぐに使用できる環境変数のセットアップ

​
前提条件

始める前に、次のものを用意してください：
  • Python 3.9+（推奨：Python 3.11+）
  • pip または uv パッケージ管理用
  • Dodo Payments アカウント（ダッシュボードから API および Webhook キーにアクセスするため）

​
クイックスタート

1

Clone the Repository

git clone https://github.com/dodopayments/fastapi-boilerplate.git
cd fastapi-boilerplate
2

Create Virtual Environment

独立した Python 環境をセットアップします:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
または、依存関係管理を高速化するために uv を使用：
uv venv
source .venv/bin/activate
3

Install Dependencies

pip install -r requirements.txt
または uv を使用：
uv pip install -r requirements.txt
4

Get API Credentials

Dodo Payments にサインアップし、ダッシュボードから資格情報を取得します:
開発中は Test Mode にしておいてください！
5

Configure Environment Variables

ルートディレクトリに .env ファイルを作成します:
cp .env.example .env
Dodo Payments の認証情報で値を更新します：
.env
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
.env ファイルをバージョン管理にコミットしないでください。.gitignore にすでに含まれています。
6

Run the Development Server

uvicorn main:app --reload
http://localhost:8000/docs を開いて、インタラクティブな API ドキュメントを確認してください！
利用可能なすべてのエンドポイントがテスト可能な状態で FastAPI の Swagger UI が表示されているはずです。

​
プロジェクト構造

fastapi-boilerplate/
├── main.py                 # FastAPI application entry point
├── routers/
│   ├── checkout.py         # Checkout session endpoints
│   ├── webhook.py          # Webhook handler endpoint
│   └── customer_portal.py  # Customer portal endpoints
├── config.py               # Environment configuration
├── requirements.txt        # Python dependencies
├── .env.example            # Environment template
└── README.md

​
API エンドポイント

ボイラープレートには、次の事前設定されたエンドポイントが含まれています：
エンドポイントメソッド説明
/checkoutPOST新しいチェックアウトセッションを作成する
/webhookPOSTDodo Payments のウェブフックを処理する
/customer-portalPOSTカスタマーポータル URL を生成する

​
コード例

​
チェックアウトセッションの作成

from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings

router = APIRouter()
dodo = AsyncDodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT
)

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int = 1
    customer_email: str | None = None
    customer_name: str | None = None

@router.post("/checkout")
async def create_checkout(request: CheckoutRequest):
    try:
        session = await dodo.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity
            }],
            customer={
                "email": request.customer_email,
                "name": request.customer_name
            } if request.customer_email else None,
            return_url="http://localhost:8000/success"
        )
        return {"checkout_url": session.url, "session_id": session.session_id}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

​
Webhook の処理

from fastapi import APIRouter, Request, HTTPException
import hmac
import hashlib
from config import settings

router = APIRouter()

def verify_webhook_signature(payload: bytes, signature: str) -> bool:
    expected = hmac.new(
        settings.DODO_PAYMENTS_WEBHOOK_KEY.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@router.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("webhook-signature", "")
    
    if not verify_webhook_signature(payload, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")
    
    event = await request.json()
    event_type = event.get("type")
    
    match event_type:
        case "payment.succeeded":
            # Handle successful payment
            payment_id = event["data"]["payment_id"]
            print(f"Payment succeeded: {payment_id}")
            
        case "subscription.active":
            # Handle subscription activation
            subscription_id = event["data"]["subscription_id"]
            print(f"Subscription activated: {subscription_id}")
            
        case "refund.succeeded":
            # Handle refund
            refund_id = event["data"]["refund_id"]
            print(f"Refund processed: {refund_id}")
    
    return {"status": "received"}

​
カスタマーポータルの統合

from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings

router = APIRouter()
dodo = AsyncDodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT
)

class PortalRequest(BaseModel):
    customer_id: str

@router.post("/customer-portal")
async def create_portal_session(request: PortalRequest):
    try:
        session = await dodo.customers.create_customer_portal(
            customer_id=request.customer_id
        )
        return {"portal_url": session.url}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

​
Webhook イベント

ボイラープレートは、一般的な Webhook イベントの処理を示しています：
イベント説明
payment.succeeded支払いが正常に完了しました
payment.failed支払いの試行に失敗しました
subscription.activeサブスクリプションが有効になりました
subscription.cancelledサブスクリプションがキャンセルされました
refund.succeeded返金が正常に処理されました
Webhook ハンドラー内にビジネスロジックを追加して：
  • データベース内のユーザー権限を更新
  • 確認メールを送信
  • デジタル製品へのアクセスを提供
  • 分析とメトリクスを追跡

​
Webhook をローカルでテスト

ローカル開発には、ngrok のようなツールを使用してローカルサーバーを公開します： 
ngrok http 8000
Webhook URL を Dodo Payments ダッシュボード で更新します： 
https://your-ngrok-url.ngrok.io/webhook

​
デプロイメント

​
Docker

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
ビルドして実行： 
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo

​
本番環境での考慮事項

本番環境にデプロイする前に:
  • DODO_PAYMENTS_ENVIRONMENT を live_mode に切り替える
  • ダッシュボードの本番用 API キーを使用する
  • Webhook URL を本番ドメインに更新する
  • 全てのエンドポイントで HTTPS を有効化する

​
トラブルシューティング

仮想環境がアクティブ化され、依存関係がインストールされていることを確認してください:
source venv/bin/activate
pip install -r requirements.txt
一般的な原因:
  • 無効な商品 ID - Dodo ダッシュボードに存在することを確認してください
  • .env に誤った API キーまたは環境設定がある
  • 詳細なエラーメッセージは FastAPI のログを確認してください
ローカルテストには ngrok を使用してサーバーを公開します:
ngrok http 8000
ウェブフック URL を Dodo ダッシュボード で ngrok URL に更新し、.env ファイルを正しいウェブフック検証キーで更新してください。
  • .env 内の DODO_PAYMENTS_WEBHOOK_KEY が正しく設定されていることを確認する
  • 署名検証には生のリクエストボディを使用していることを確認する
  • webhook-signature ヘッダーを正しく読み取っているか確認する

​
詳細を学ぶ

Python SDK

非同期対応の Python SDK ドキュメントを完成させる

Webhooks Documentation

すべてのウェブフックイベントとベストプラクティスについて学ぶ

Checkout Sessions

チェックアウトセッションの設定を詳細に掘り下げる

API Reference

Dodo Payments API ドキュメントを完成させる

​
サポート

ボイラープレートに関して助けが必要ですか？