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

GitHub リポジトリ

完全な FastAPI + Dodo Payments ボイラープレート

​
概要

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

リポジトリをクローン

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

仮想環境を作成

隔離された Python 環境を設定します：
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
または、依存関係管理を高速化するために uv を使用：
uv venv
source .venv/bin/activate
3

依存関係をインストール

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

API 認証情報を取得

Dodo Payments にサインアップし、ダッシュボードから認証情報を取得します：
開発中は テストモード にいることを確認してください！
5

環境変数を設定

ルートディレクトリに .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

開発サーバーを実行

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 Webhook を処理
/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
Webhook URL を Dodo ダッシュボード で ngrok URL に更新します。正しい Webhook 検証キーで .env ファイルを更新することを忘れないでください。
  • DODO_PAYMENTS_WEBHOOK_KEY が .env に正しく設定されていることを確認
  • 署名検証のために生のリクエストボディを使用していることを確認
  • webhook-signature ヘッダーを正しく読み取っていることを確認

​
詳細を学ぶ

Python SDK

非同期サポートを備えた完全な Python SDK ドキュメント

Webhook ドキュメント

すべての Webhook イベントとベストプラクティスについて学ぶ

チェックアウトセッション

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

API リファレンス

完全な Dodo Payments API ドキュメント

​
サポート

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