GitHub Repository
完整的 FastAPI + Dodo Payments 样板
该样板使用 FastAPI 的 async/await 模式，Pydantic 进行验证，以及 dodopayments Python SDK 实现无缝 API 集成。
- 快速设置 - 在 5 分钟内开始
- 异步支持 - 使用 FastAPI 的原生 async/await 模式构建
- 结账会话 - 使用 Python SDK 预配置的结账流程
- Webhook 处理 - 带有签名验证的安全 Webhook 端点
- 客户门户 - 轻松创建客户门户会话
- 类型安全 - 完整的 Pydantic 验证和类型提示
- 环境配置 - 准备使用的环境变量设置
先决条件
在开始之前，请确保您拥有：
- Python 3.9+（推荐：Python 3.11+）
- pip 或 uv 进行包管理
- Dodo Payments 账户（以从仪表板访问 API 和 Webhook 密钥）
快速开始
Clone the Repository
git clone https://github.com/dodopayments/fastapi-boilerplate.git
cd fastapi-boilerplate
Create Virtual Environment
设置独立的 Python 环境：python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
uv venv
source .venv/bin/activate
Install Dependencies
pip install -r requirements.txt
uv pip install -r requirements.txt
Configure Environment Variables
在根目录创建一个 .env 文件：用您的 Dodo Payments 凭证更新值：DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
切勿将 .env 文件提交到版本控制。它已经包含在 .gitignore 中。
Run the Development Server
项目结构
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 端点
该模板包括以下预配置的端点：
| 端点 | 方法 | 描述 |
|---|
/checkout | POST | 创建新的结账会话 |
/webhook | POST | 处理 Dodo Payments 的 webhook |
/customer-portal | POST | 生成客户门户 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
对于本地开发，使用 ngrok 来暴露您的本地服务器：
在您的 Dodo Payments 仪表板 中更新 Webhook URL：
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
故障排除
Import errors or missing modules
确保你的虚拟环境已激活且依赖项已安装：source venv/bin/activate
pip install -r requirements.txt
Checkout session creation fails
常见原因：
- 无效的产品 ID —— 在你的 Dodo 仪表板中验证其存在
.env 中的 API 密钥或环境设置错误- 查看 FastAPI 日志以获取详细错误信息
Webhooks not receiving events
对于本地测试，使用 ngrok 暴露你的服务器：在 Dodo dashboard 中将 webhook URL 更新为 ngrok URL。确保在 .env 文件中使用正确的 webhook 验证密钥。 Webhook signature verification fails
- 确保
DODO_PAYMENTS_WEBHOOK_KEY 在 .env 中被正确设置
- 验证你使用的是原始请求体进行签名验证
- 检查你是否正确读取了
webhook-signature 头
了解更多
Python SDK
包含异步支持的完整 Python SDK 文档
Webhooks Documentation
了解所有 webhook 事件及最佳实践
Checkout Sessions
深入了解结账会话配置
API Reference
完整的 Dodo Payments API 文档
