GitHub Repository
Mã nguồn cho boilerplate FastAPI và Dodo Payments.
Tổng quan
Boilerplate FastAPI là một backend Python đã được kết nối với Dodo Payments. Boilerplate này có các endpoint để tạo checkout sessions và Customer Portal sessions, một webhook endpoint để xác minh chữ ký, cùng một trang pricing được render từ các template Jinja2.Boilerplate này sử dụng FastAPI với các route handler
async, Pydantic để xác thực và quản lý settings, cùng Python SDK dodopayments. Các handler gọi synchronous DodoPayments client. Để tránh chặn event loop, hãy chuyển sang AsyncDodoPayments và await các lệnh gọi của nó.Tính năng
Boilerplate bao gồm:- Thiết lập nhanh: Từ lúc clone đến khi server chạy chỉ mất khoảng năm phút.
- Async Handlers: Các route handler là các hàm FastAPI
async def. - Checkout Sessions: Một checkout endpoint được cấu hình sẵn và sử dụng Python SDK.
- Webhook Handling: Một webhook endpoint xác minh từng chữ ký bằng method
unwrapcủa SDK. - Customer Portal: Một endpoint tạo các Customer Portal sessions.
- Type Safety: Các model Pydantic xác thực request body và mã nguồn sử dụng type hints.
- Cấu hình môi trường:
pydantic-settingstải và xác thực cấu hình từ.env.
Điều kiện tiên quyết
Trước khi bắt đầu, bạn cần:- Python 3.9 trở lên, phiên bản mà
dodopaymentsSDK yêu cầu. Khuyến nghị sử dụng Python 3.11 trở lên. - pip hoặc uv để quản lý package.
- Tài khoản Dodo Payments, để tạo API key và webhook signing secret trong dashboard.
Bắt đầu nhanh
1
Clone the Repository
2
Create Virtual Environment
Thiết lập một môi trường Python độc lập:Hoặc sử dụng uv để quản lý dependency nhanh hơn:
3
Install Dependencies
4
Get API Credentials
Đăng ký tại Dodo Payments, sau đó lấy thông tin xác thực từ dashboard:
- API Key: Tạo key trong Dashboard → Developer → API Keys.
- Webhook Key: Thêm endpoint trong Dashboard → Developer → Webhooks, sau đó sao chép signing secret của endpoint đó. URL của endpoint phải ở chế độ public và sử dụng HTTPS. Để nhận events trên máy của bạn, hãy xem Kiểm thử Webhooks trên máy cục bộ.
5
Configure Environment Variables
Sao chép file mẫu để tạo file Đặt các giá trị thành thông tin xác thực Dodo Payments của bạn:Cả bốn biến đều bắt buộc.
.env trong thư mục gốc:.env
app/core/config.py tải chúng bằng pydantic-settings và ứng dụng sẽ không khởi động nếu một biến bị thiếu hoặc để trống. DODO_PAYMENTS_RETURN_URL là nơi checkout chuyển khách hàng đến sau khi thanh toán.6
Add Your Products
Thay thế các sản phẩm mẫu trong
app/lib/products.py bằng sản phẩm của bạn. Đặt mỗi product_id thành ID của một sản phẩm trong mục Products trên dashboard. Trang pricing sẽ hiển thị các sản phẩm này.7
Run the Development Server
Swagger UI liệt kê các endpoint
/api/checkout/, /api/webhook/ và /api/customer-portal/, sẵn sàng để kiểm thử.http://localhost:8000, hiển thị trang pricing.Cấu trúc dự án
API Endpoints
app/main.py mount từng router dưới tiền tố /api:
Mỗi path đều kết thúc bằng dấu gạch chéo. FastAPI trả về redirect
307 cho request đến path không có dấu gạch chéo, vì vậy hãy sử dụng path chính xác, đặc biệt là trong webhook URL của bạn.
Ví dụ mã
Các ví dụ này được rút gọn từ những file trongapp/api/.
Tạo Checkout Session
app/api/checkout.py tạo checkout session và trả về checkout_url. Request body nhận một product_id, một quantity tùy chọn và một object customer tùy chọn có name và email:
Xử lý Webhook
app/api/webhook.py xác minh chữ ký bằng method unwrap của SDK, sau đó phân nhánh dựa trên event type:
Tích hợp Customer Portal
app/api/portal.py tạo Customer Portal session cho customer ID và trả về liên kết portal dưới dạng url:
app/templates/index.html gửi một customer ID được hardcode (cus_001) đến endpoint này, cùng một name và email được hardcode đến checkout endpoint. Hãy thay thế chúng bằng các giá trị của người dùng đã đăng nhập.
Webhook Events
Handler trongapp/api/webhook.py phân nhánh dựa trên các event sau:
Để xử lý một event khác, hãy thêm một nhánh cho type tương ứng, chẳng hạn như
refund.succeeded cho refund đã được xử lý thành công. Xem Webhook Event Guide để biết mọi event type.
Thêm business logic của bạn bên trong webhook handler để:
- Cập nhật quyền của người dùng trong database
- Gửi email xác nhận
- Cấp quyền truy cập vào các sản phẩm kỹ thuật số
- Theo dõi analytics và metrics
Kiểm thử Webhook trên môi trường local
Dodo Payments không thể truy cậplocalhost. Để phát triển local, hãy sử dụng công cụ như ngrok để public local server của bạn:
/api/webhook/, làm endpoint trong Dodo Payments Dashboard của bạn:
DODO_PAYMENTS_WEBHOOK_KEY trong .env, sau đó khởi động lại server. Ứng dụng chỉ đọc .env khi khởi động.
Triển khai
Docker
Repository không bao gồm mộtDockerfile. Để chạy ứng dụng trong container, hãy thêm Dockerfile này vào thư mục gốc của repository:
COPY . . sao chép mọi file trong build context, bao gồm cả .env. Để giữ các key bên ngoài image, hãy thêm một file .dockerignore liệt kê .env. Sau đó build image và chạy image bằng environment file của bạn:
Lưu ý cho Production
Khắc phục sự cố
Import errors or missing modules
Import errors or missing modules
Đảm bảo virtual environment của bạn đã được kích hoạt và các dependency đã được cài đặt:
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 phục vụ các static file từ app/static, nhưng repository không bao gồm directory đó. Hãy tạo directory bằng mkdir app/static, sau đó khởi động lại server.Checkout session creation fails
Checkout session creation fails
Kiểm tra các nguyên nhân phổ biến sau:
- Product ID không tồn tại trong Dodo Payments dashboard của bạn.
- API key hoặc
DODO_PAYMENTS_ENVIRONMENTtrong.envkhông đúng. Test mode key chỉ hoạt động vớitest_mode.
400. Kiểm tra log FastAPI để xem thông báo lỗi chi tiết.Webhooks not receiving events
Webhooks not receiving events
Để kiểm thử local, hãy sử dụng ngrok để public server của bạn:Trong Dodo dashboard của bạn, hãy thêm một endpoint với ngrok URL theo sau bởi
/api/webhook/, bao gồm cả dấu gạch chéo ở cuối. Sao chép signing secret của endpoint đó vào DODO_PAYMENTS_WEBHOOK_KEY trong file .env của bạn.Webhook signature verification fails
Webhook signature verification fails
- Đảm bảo
DODO_PAYMENTS_WEBHOOK_KEYtrong.envkhớp với signing secret của endpoint. - Xác minh chữ ký dựa trên raw request body trước khi parse body thành JSON.
- Truyền cả ba header
webhook-id,webhook-timestampvàwebhook-signaturevàoclient.webhooks.unwrap(). Chữ ký Standard Webhooks bao phủid.timestamp.body, không chỉ riêng body.
Tìm hiểu thêm
Python SDK
Tài liệu Python SDK đầy đủ với hỗ trợ async
Webhooks Documentation
Tìm hiểu về tất cả webhook event và các best practice
Checkout Sessions
Tìm hiểu chuyên sâu về cấu hình checkout session
API Reference
Tài liệu Dodo Payments API đầy đủ
Hỗ trợ
Để được trợ giúp về boilerplate:- Đặt câu hỏi trong cộng đồng Discord.
- Báo cáo issue và theo dõi cập nhật trong GitHub repository.
- Gửi email cho đội ngũ hỗ trợ.