GitHub Repository
Boilerplate Go + Dodo Payments tối giản
Tổng quan
Go boilerplate là một Go server tối giản, giúp bán các sản phẩm Dodo Payments từ trang định giá. Server tạo checkout session, xác minh và xử lý webhook, đồng thời mở Customer Portal. Hãy clone repository này để làm điểm khởi đầu cho backend Go của riêng bạn.Boilerplate yêu cầu Go 1.24.4 trở lên, là phiên bản được thiết lập trong
go.mod. Dự án sử dụng bố cục cmd, internal và templates, hiển thị trang định giá bằng Go HTML templates và gọi Dodo Payments API thông qua SDK dodopayments-go.Tính năng
- Thiết lập nhanh: Clone repository, thêm API key vào
.envvà khởi động server bằngmake run. - Tích hợp thanh toán: Luồng checkout tạo checkout session bằng SDK
dodopayments-go. - UI hiện đại: Trang định giá sử dụng giao diện tối, được xây dựng bằng Go HTML templates và Tailwind CSS.
- Xử lý webhook: Xác minh chữ ký của từng webhook trước khi xử lý event.
- Customer Portal: Quản lý subscription tự phục vụ thông qua Customer Portal.
- Các phương pháp tốt nhất của Go: Bố cục dự án rõ ràng với
cmd,internalvàtemplates. - Checkout điền sẵn thông tin: Truyền tên và email của customer vào checkout để customer không phải nhập lại.
Điều kiện tiên quyết
Trước khi bắt đầu, bạn cần:- Go 1.24.4 trở lên. Kiểm tra phiên bản bằng
go version. - Tài khoản Dodo Payments, để tạo API key và webhook signing key trong dashboard.
- Ít nhất một product, được tạo trong mục Products của dashboard.
Bắt đầu nhanh
1
Clone the Repository
2
Install Dependencies
make install chạy go mod download rồi go mod tidy. Để tải các module mà không cần make, hãy chạy:3
Get API Credentials
Đăng ký tại Dodo Payments, sau đó sao chép cả hai key từ dashboard:
- API Key: Developer → API Keys
- Webhook Key: Developer → Webhooks. Mỗi webhook endpoint có signing key riêng. Để tạo endpoint kết nối đến local server, hãy xem Kiểm thử webhook trên local.
4
Configure Environment Variables
Tạo file Thiết lập các giá trị này trong Server đọc các biến này khi khởi động:
.env trong thư mục gốc của dự án từ template:.env:.env
Server sẽ thoát khi khởi động nếu thiếu một trong hai key bắt buộc.
.env.example thiết lập PORT và DODO_PAYMENTS_RETURN_URL thành port 8080. Trang này sử dụng port 8000, vì vậy hãy thiết lập cả hai thành 8000 như minh họa, hoặc thay 8000 bằng 8080 trong các command trên trang này.5
Add Your Products
Thay product mẫu trong
internal/lib/products.go bằng các product của bạn. Sao chép từng product ID từ Products trong dashboard:Price chỉ thiết lập giá được hiển thị trên trang định giá, theo đơn vị tiền tệ nhỏ nhất: 9999 được hiển thị là $99.99. Checkout tính giá của product trong Dodo Payments.6
Run the Development Server
make run build server thành bin/server rồi khởi động server. Để chạy server mà không build binary trước, hãy chạy:Bạn sẽ thấy một trang định giá với giao diện tối, liệt kê các product và sẵn sàng để mua.
Cấu trúc dự án
Repository có bố cục như sau:API endpoint
Boilerplate bao gồm các endpoint được cấu hình sẵn sau:Tùy chỉnh
Cập nhật thông tin product
Chỉnh sửainternal/lib/products.go để thay đổi:
- Product ID (từ Products trong dashboard Dodo Payments của bạn)
- Tên
- Giá hiển thị trên trang định giá
- Tính năng
- Mô tả
/mo vào mọi giá và hiển thị Custom thay vì giá khi Price bằng hoặc lớn hơn 100000. Để thay đổi, hãy chỉnh sửa templates/index.html.
Điền sẵn dữ liệu customer
Trong.env, function handleCheckout gửi dữ liệu customer được hardcode đến /api/checkout. Hãy thay bằng dữ liệu của user đã đăng nhập:
handlePortal sử dụng lại dữ liệu customer này và fallback về cùng tên và email mẫu. Trong app production, hãy truyền các giá trị này từ hệ thống authentication của bạn vào cả hai function.
Webhook event
internal/api/webhook.go xác minh từng request bằng client.Webhooks.Unwrap và key trong DODO_PAYMENTS_WEBHOOK_KEY, sau đó định tuyến event theo type. Các event này có handler và mỗi handler đều ghi log dữ liệu event:
Handler cũng chấp nhận
subscription.on_hold, subscription.failed, subscription.expired và subscription.plan_changed mà không thực hiện hành động nào, đồng thời ghi log mọi event type khác là chưa được xử lý. Handler phản hồi 200 cho mọi event đã được xác minh. Để xem tất cả event type, hãy xem Hướng dẫn webhook event.
Thêm business logic vào các function handler để:
- Cập nhật quyền của user trong database
- Gửi email xác nhận
- Cấp quyền truy cập vào digital product
- Theo dõi analytics và metrics
Kiểm thử webhook trên local
Dodo Payments không thể truy cậplocalhost. Để nhận webhook trong quá trình phát triển, hãy expose local server bằng tunnel như ngrok:
/api/webhook:
DODO_PAYMENTS_WEBHOOK_KEY, sau đó khởi động lại server.
Triển khai
Build cho production
make build biên dịch server thành bin/server:
make, hãy chạy:
Triển khai lên Vercel
[.env vào cài đặt project Vercel, vì .env không nằm trong repository. Sau đó thiết lập webhook endpoint trong dashboard thành https://yourdomain.com/api/webhook.
Docker
TạoDockerfile trong thư mục gốc của dự án. Build stage phải sử dụng Go 1.24.4 trở lên để khớp với go.mod:
templates/ cạnh binary, vì server tải template từ working directory. Build và chạy image:
PORT từ .env, vì vậy hãy giữ PORT=8000 để khớp với port mapping.
Lưu ý cho production
Xử lý sự cố
Build errors or missing dependencies
Build errors or missing dependencies
Kiểm tra để đảm bảo
go version báo cáo Go 1.24.4 trở lên, sau đó tải lại các module:Checkout session creation fails
Checkout session creation fails
Nguyên nhân thường gặp:
- Product ID không hợp lệ. Kiểm tra product đó tồn tại trong Products ở cùng mode với API key của bạn.
- API key hoặc
DODO_PAYMENTS_ENVIRONMENTtrong.envkhông đúng. Test mode key cầntest_mode. - Để xem lỗi chính xác, hãy kiểm tra server log. Handler ghi log mọi request thất bại trước khi trả về
500.
Webhooks not receiving events
Webhooks not receiving events
Để kiểm thử local, hãy expose server bằng ngrok:Đặt webhook URL trong dashboard Dodo Payments thành URL ngrok. Sau đó đặt
DODO_PAYMENTS_WEBHOOK_KEY trong .env thành signing key của endpoint đó. Nếu server ghi log webhook verification failed, key không khớp với endpoint.Templates not loading
Templates not loading
Server tải
templates/base.html và templates/index.html từ working directory. Khởi động server từ thư mục gốc của dự án hoặc thay đổi đường dẫn template trong cmd/server/main.go.Tìm hiểu thêm
Go SDK
Tài liệu Go SDK đầy đủ
Webhooks Documentation
Tìm hiểu về tất cả webhook event và các phương pháp tốt nhất
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 hỗ trợ về boilerplate:- Đặt câu hỏi trong cộng đồng Discord.
- Kiểm tra repository GitHub để xem issue và cập nhật.
- Liên hệ đội ngũ hỗ trợ.