Chuyển đến nội dung chính

​
Tổng quan

Bộ khởi động tối thiểu Next.js cung cấp một điểm khởi đầu sẵn sàng để tích hợp Dodo Payments với ứng dụng Next.js của bạn. Mẫu này bao gồm các phiên thanh toán, xử lý webhook, cổng khách hàng và các thành phần UI hiện đại để giúp bạn bắt đầu chấp nhận thanh toán nhanh chóng.
Boilerplate này sử dụng Next.js 16 App Router với TypeScript, Tailwind CSS 4 và bộ điều hợp @dodopayments/nextjs.

​
Tính năng

  • Quick Setup - Bắt đầu trong chưa đầy 5 phút
  • Payment Integration - Luồng thanh toán được cấu hình sẵn sử dụng @dodopayments/nextjs
  • Modern UI - Trang giá sạch sẽ theo chủ đề tối với Tailwind CSS
  • Webhook Handler - Điểm cuối webhook sẵn sàng để xử lý sự kiện thanh toán
  • Customer Portal - Quản lý đăng ký một lần nhấp
  • TypeScript - Được viết kiểu đầy đủ với các kiểu tối giản, tập trung
  • Pre-filled Checkout - Minh họa cách truyền dữ liệu khách hàng để cải thiện trải nghiệm người dùng

​
Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn đã có:
  • Node.js 20.9+ (cần thiết cho Next.js 16)
  • Tài khoản Dodo Payments (để truy cập API và Webhook Keys từ bảng điều khiển)

​
Bắt đầu nhanh

1

Clone the Repository

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate
2

Install Dependencies

npm install
3

Get API Credentials

Đăng ký tại Dodo Payments và lấy thông tin xác thực của bạn từ bảng điều khiển:
Đảm bảo bạn đang ở Chế độ Kiểm thử trong khi phát triển!
4

Configure Environment Variables

Tạo một tệp .env trong thư mục gốc:
cp .env.example .env
Cập nhật các giá trị với thông tin xác thực Dodo Payments của bạn:
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:3000
DODO_PAYMENTS_ENVIRONMENT=test_mode
Không bao giờ cam kết tệp .env vào hệ thống kiểm soát phiên bản. Nó đã được bao gồm trong .gitignore.
5

Add Your Products

Cập nhật src/lib/products.ts với các ID sản phẩm thực tế từ Dodo Payments:
export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];
6

Run the Development Server

npm run dev
Mở http://localhost:3000 để xem trang giá của bạn!

​
Cấu trúc dự án

src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions

​
Tùy chỉnh

​
Cập nhật thông tin sản phẩm

Chỉnh sửa src/lib/products.ts để thay đổi:
  • ID sản phẩm (từ bảng điều khiển Dodo của bạn)
  • Giá cả
  • Tính năng
  • Mô tả

​
Điền trước dữ liệu khách hàng

Trong src/app/components/ProductCard.tsx, thay thế các giá trị cố định bằng dữ liệu người dùng thực tế của bạn: 
customer: {
  name: "John Doe",
  email: "john@example.com",
},

​
Cập nhật cổng khách hàng

Trong src/app/components/Header.tsx, thay thế ID khách hàng cố định bằng: 
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
Bạn có thể hoàn thành một giao dịch thử nghiệm để lấy ID khách hàng cho việc thử nghiệm.

​
Sự kiện Webhook

Boilerplate này minh họa cách xử lý hai sự kiện webhook trong src/app/api/webhook/route.ts:
  • onSubscriptionActive - Được kích hoạt khi một đăng ký trở nên hoạt động
  • onPaymentSucceeded - Được kích hoạt khi một khoản thanh toán thành công
Thêm logic kinh doanh của bạn vào bên trong các trình xử lý này: 
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
Thêm nhiều sự kiện webhook nếu cần. Đối với phát triển cục bộ, bạn có thể sử dụng các công cụ như ngrok để tạo một đường hầm bảo mật đến máy chủ cục bộ của bạn và sử dụng nó làm URL webhook của bạn.

​
Triển khai

​
Xây dựng cho sản xuất

npm run build
npm start

​
Triển khai lên Vercel

[ Triển khai với Vercel ](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Đừng quên thêm các biến môi trường của bạn trong bảng điều khiển Vercel!

​
Cập nhật URL Webhook

Sau khi triển khai, cập nhật URL webhook của bạn trong Bảng điều khiển Dodo Payments: 
https://example.com/api/webhook

​
Khắc phục sự cố

Xóa node_modules và cài đặt lại các phụ thuộc:
rm -rf node_modules package-lock.json
npm install
Nguyên nhân phổ biến:
  • ID sản phẩm không hợp lệ - xác minh rằng nó tồn tại trong bảng điều khiển Dodo của bạn
  • Sai khóa API hoặc cài đặt môi trường trong .env
  • Kiểm tra bảng điều khiển trình duyệt và terminal để tìm lỗi
Đối với kiểm thử cục bộ, sử dụng ngrok để mở máy chủ của bạn lên mạng:
ngrok http 3000
Cập nhật URL webhook trong bảng điều khiển Dodo của bạn thành URL ngrok. Hãy nhớ cập nhật tệp .env của bạn với khóa xác minh webhook chính xác.

​
Tìm hiểu thêm

​
Hỗ trợ

Cần giúp đỡ với bộ khởi động?