Billing SDK

Billing SDK là một bộ các component billing React mã nguồn mở, đi kèm CLI kết nối dự án của bạn với Dodo Payments. CLI tạo các route API, React hook và client Dodo Payments cho framework của bạn, đồng thời thêm các component như bảng giá và bộ đo mức sử dụng.

Tổng quan

Billing SDK bao gồm:

React Components: Các component billing React được dựng sẵn và có thể tùy chỉnh cho ứng dụng React.
CLI Tooling: Giao diện dòng lệnh khởi tạo dự án và thêm component.
Framework Support: Template cho Next.js, Express.js, Hono, Fastify, NestJS và React.
Payment Provider: Tích hợp đầy đủ với Dodo Payments.

Bắt đầu nhanh

Để thiết lập Billing SDK trong một dự án hiện có, hãy chạy CLI từ thư mục gốc của dự án:

Install the CLI

Chạy CLI với npx mà không cần cài đặt:

npx @billingsdk/cli --help

Hoặc cài đặt CLI trên toàn hệ thống để sử dụng thường xuyên. Bản cài đặt toàn hệ thống thêm lệnh billingsdk, ví dụ billingsdk init:

npm install -g @billingsdk/cli

Initialize a Project

Chạy thiết lập tương tác để thêm billing vào dự án của bạn:

npx @billingsdk/cli init

CLI sẽ yêu cầu bạn chọn:

Framework của bạn: Next.js, Express.js, React, Hono, Fastify hoặc NestJS. CLI sẽ phát hiện framework của bạn và đánh dấu framework đó là đã được phát hiện.
Payment provider của bạn: chọn Dodo Payments.

Add Components

Thêm các thành phần thanh toán riêng lẻ vào dự án của bạn:

npx @billingsdk/cli add pricing-table-one
npx @billingsdk/cli add subscription-management

Các Framework được hỗ trợ

Billing SDK có template Dodo Payments cho từng framework sau:

Framework	Dodo Payments
Next.js	Yes
Express.js	Yes
Hono	Yes
React	Yes
Fastify	Yes
NestJS	Yes

Lệnh CLI

`@billingsdk/cli init`

init thiết lập billing trong dự án của bạn: lệnh này cài đặt template framework với tích hợp Dodo Payments cùng các dependency mà template yêu cầu. Chức năng:

Framework Selection: Bạn chọn framework và payment provider.
Template Installation: CLI tải template cho framework và provider của bạn từ registry Billing SDK rồi cài đặt các file của template.
Dependency Management: CLI cài đặt các dependency của template, chẳng hạn như dodopayments, standardwebhooks và zod, bằng npm, pnpm, Yarn hoặc Bun.
File Generation: CLI ghi các file cấu hình và mã boilerplate. Với Express.js, Fastify, Hono và NestJS, CLI ghi các file này trong src/.

Ví dụ:

npx @billingsdk/cli init

Để chạy init mà không cần lời nhắc, hãy truyền --framework, --provider và --yes, ví dụ npx @billingsdk/cli init --framework nextjs --provider dodopayments --yes. Thêm --dry-run để liệt kê các file mà không ghi chúng, --no-install để bỏ qua việc cài đặt dependency hoặc --package-manager để chọn npm, pnpm, yarn hoặc bun.

`@billingsdk/cli add`

add cài đặt một billing component vào dự án của bạn thông qua hệ thống registry shadcn/ui. Lệnh này chạy shadcn@latest add @billingsdk/<component> bằng runner của package manager. Ví dụ:

# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle

Điều gì xảy ra:

CLI shadcn tải cấu hình component từ registry.
CLI cài đặt các file component vào thư mục components/billingsdk/.
CLI cập nhật cấu hình dự án nếu cần.
CLI cài đặt mọi dependency bổ sung.

Cấu trúc File Được Tạo

Sau khi chạy init, dự án của bạn sẽ chứa:

API Routes: Các endpoint cho checkout, customer, customer payment, product, subscription và webhook. Template React không có API route.
Hooks: Một React hook useBilling cho các thao tác billing, dành cho React và Next.js.
Library Files: Thiết lập client Dodo Payments và các hàm helper trong lib/dodopayments.ts.
Environment Configuration: File environment mẫu, .env.example.

Cấu trúc Ví dụ Next.js

Đối với Next.js, init ghi các file sau:

your-project/
├── app/api/
│   ├── checkout/route.ts
│   ├── customer/route.ts
│   ├── customer/payments/route.ts
│   ├── customer/subscriptions/route.ts
│   ├── product/route.ts
│   ├── products/route.ts
│   └── webhook/route.ts
├── hooks/
│   └── useBilling.ts
├── lib/
│   └── dodopayments.ts
└── .env.example

Cấu hình Environment

Sau khi khởi tạo, hãy thiết lập các biến environment. Lấy API key từ Developer → API Keys và webhook key từ Developer → Webhooks trong dashboard:

# DodoPayments
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

Đặt DODO_PAYMENTS_ENVIRONMENT thành test_mode hoặc live_mode. Client Dodo Payments được tạo sẽ báo lỗi với mọi giá trị khác.

Lưu API key trong các biến environment. Không bao giờ commit chúng vào hệ thống kiểm soát phiên bản.

Các Component Có Sẵn

Billing SDK cung cấp các component React trong những nhóm sau:

Pricing Tables: Tám biến thể, từ pricing-table-one đến pricing-table-eight, dùng để hiển thị giá sản phẩm.
Subscription Management: subscription-management, cùng các card và dialog để hủy subscription hoặc cập nhật plan.
Usage Monitoring: Các bộ đo mức sử dụng dạng tròn và dạng tuyến tính, cùng các bảng mức sử dụng cho billing dựa trên mức sử dụng.
Checkout Components: Bộ chọn payment method, các form payment details và card payment failure.
Customer Portal: Cài đặt billing, màn hình billing, lịch sử invoice và các khoản phí sắp tới, hỗ trợ customer tự phục vụ.

Để duyệt qua mọi component với bản xem trước trực tiếp, hãy xem thư viện component.

Mã Nguồn Mở

Billing SDK là mã nguồn mở:

Tính minh bạch: Bạn có thể đọc cách mọi component hoạt động.
Cộng đồng: Các developer xây dựng sản phẩm này cho những developer khác.
Bảo mật: Bất kỳ ai cũng có thể xem xét mã nguồn để tìm vấn đề bảo mật.
Đổi mới: Đóng góp từ cộng đồng giúp đẩy nhanh quá trình phát triển.

Billing SDK được phát hành theo GNU General Public License v3.0 (GPL-3.0), giúp dự án luôn mở và miễn phí.

Nhận Trợ Giúp

Để được trợ giúp về Billing SDK, hãy sử dụng các tài nguyên sau:

GitHub Issues: Mở issue
Documentation: Truy cập billingsdk.com/docs
LLMs Full Documentation: billingsdk.com/llms-full.txt

Đóng Góp

Billing SDK hoan nghênh các đóng góp. Hướng dẫn đóng góp giải thích cách bạn có thể:

Báo cáo lỗi
Yêu cầu tính năng
Gửi pull request
Thêm component mới
Cải thiện tài liệu

Tìm Hiểu Thêm

Full Documentation

Hướng dẫn đầy đủ về Billing SDK cùng các ví dụ và best practice

CLI Reference

Tài liệu CLI chi tiết cho mọi lệnh và tùy chọn

Component Library

Duyệt qua mọi component có sẵn với các ví dụ trực tiếp

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Tổng quan

Bắt đầu nhanh

Các Framework được hỗ trợ

Lệnh CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Cấu trúc File Được Tạo

Cấu trúc Ví dụ Next.js

Cấu hình Environment

Các Component Có Sẵn

Mã Nguồn Mở

Nhận Trợ Giúp

Đóng Góp

Tìm Hiểu Thêm

Full Documentation

CLI Reference

Component Library

​Tổng quan

​Bắt đầu nhanh

​Các Framework được hỗ trợ

​Lệnh CLI

​@billingsdk/cli init

​@billingsdk/cli add

​Cấu trúc File Được Tạo

​Cấu trúc Ví dụ Next.js

​Cấu hình Environment

​Các Component Có Sẵn

​Mã Nguồn Mở

​Nhận Trợ Giúp

​Đóng Góp

​Tìm Hiểu Thêm

Full Documentation

CLI Reference

Component Library

Tổng quan

Bắt đầu nhanh

Các Framework được hỗ trợ

Lệnh CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Cấu trúc File Được Tạo

Cấu trúc Ví dụ Next.js

Cấu hình Environment

Các Component Có Sẵn

Mã Nguồn Mở

Nhận Trợ Giúp

Đóng Góp

Tìm Hiểu Thêm