Skip to main content

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 .env và khởi động server bằng make 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, internal và 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:
Tạo cả hai key ở test mode trong quá trình phát triển. Để chuyển sang test mode, hãy tắt công tắc Live Mode trong thanh bên của dashboard.
4

Configure Environment Variables

Tạo file .env trong thư mục gốc của dự án từ template:
Thiết lập các giá trị này trong .env:
.env
Server đọc các biến này khi khởi động: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.
Không bao giờ commit file .env vào version control. .gitignore của repository đã loại trừ file 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:
Mở http://localhost:8000 để xem trang định giá.
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ửa internal/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ả
Template trang định giá thêm hậu 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:
Function 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ập localhost. Để nhận webhook trong quá trình phát triển, hãy expose local server bằng tunnel như ngrok:
Trong Dodo Payments Dashboard, thêm endpoint với forwarding URL do ngrok in ra, theo sau là /api/webhook:
Sao chép signing key của endpoint vào 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:
Để build và khởi động binary mà không cần make, hãy chạy:

Triển khai lên Vercel

[ Triển khai bằng Vercel ](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) Sau khi triển khai, hãy thêm các biến từ file .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ạo Dockerfile 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:
Image cuối cùng sao chép templates/ cạnh binary, vì server tải template từ working directory. Build và chạy image:
Container lắng nghe giá trị PORT từ .env, vì vậy hãy giữ PORT=8000 để khớp với port mapping.

Lưu ý cho production

Trước khi triển khai lên production:
  • Đặt DODO_PAYMENTS_ENVIRONMENT thành live_mode.
  • Sử dụng live mode API key từ dashboard.
  • Trỏ webhook endpoint đến production domain và sử dụng signing key của endpoint đó.
  • Đặt DODO_PAYMENTS_RETURN_URL thành một trang trên production domain.
  • Phục vụ mọi endpoint qua HTTPS.

Xử lý sự cố

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:
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_ENVIRONMENT trong .env không đúng. Test mode key cần test_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.
Để 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.
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:
Lần sửa đổi cuối 26 tháng 9, 2026