Skip to main content

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 unwrap củ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-settings tả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à dodopayments SDK 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

Hoặc với uv:
4

Get API Credentials

Đăng ký tại Dodo Payments, sau đó lấy thông tin xác thực từ dashboard:
Tạo cả hai khi công tắc Live Mode trong sidebar đang tắt. Key ở test mode chỉ hoạt động với DODO_PAYMENTS_ENVIRONMENT=test_mode và các khoản thanh toán ở test mode không chuyển tiền thật.
5

Configure Environment Variables

Sao chép file mẫu để tạo file .env trong thư mục gốc:
Đặt các giá trị thành thông tin xác thực Dodo Payments của bạn:
.env
Cả bốn biến đều bắt buộc. 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.
Đừng commit file .env vào version control. .gitignore của repository đã loại trừ file này.
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

Mở http://localhost:8000/docs để xem tài liệu API tương tác.
Swagger UI liệt kê các endpoint /api/checkout/, /api/webhook/ và /api/customer-portal/, sẵn sàng để kiểm thử.
URL gốc, http://localhost:8000, hiển thị trang pricing.
app/main.py gọi INLINE_CODE_PLACEHOLDER_fd4869eef4784ce_END, một chữ ký mà Starlette 1.x không còn chấp nhận, vì vậy trang pricing trả về lỗi 500 trên bản cài đặt mới. Để khắc phục, hãy thay đổi lệnh gọi thành templates.TemplateResponse(request, "index.html", {"products": products}).

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 trong app/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:
Trang pricing trong 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 trong app/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ập localhost. Để phát triển local, hãy sử dụng công cụ như ngrok để public local server của bạn:
Thêm ngrok HTTPS URL, theo sau bởi /api/webhook/, làm endpoint trong Dodo Payments Dashboard của bạn:
Sao chép signing secret của endpoint vào 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ột Dockerfile. Để 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

Trước khi triển khai lên production:
  • Chuyển DODO_PAYMENTS_ENVIRONMENT sang live_mode.
  • Sử dụng live mode API key từ dashboard.
  • Thêm webhook endpoint cho production domain của bạn và đặt DODO_PAYMENTS_WEBHOOK_KEY thành signing secret của endpoint đó.
  • Đặt DODO_PAYMENTS_RETURN_URL thành production URL của bạn.
  • Bật HTTPS cho tất cả endpoint.

Khắc phục sự cố

Đảm bảo virtual environment của bạn đã được kích hoạt và các dependency đã được cài đặt:
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.
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_ENVIRONMENT trong .env không đúng. Test mode key chỉ hoạt động với test_mode.
Endpoint trả về lỗi SDK trong response 400. Kiểm tra log FastAPI để xem thông báo lỗi chi tiết.
Để 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.
  • Đảm bảo DODO_PAYMENTS_WEBHOOK_KEY trong .env khớ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-timestamp và webhook-signature vào client.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:
Lần sửa đổi cuối 26 tháng 9, 2026