Trong hướng dẫn này, bạn sẽ xây dựng NeuralAPI — một nền tảng AI theo tầng, mỗi gói đăng ký đi kèm với hạn mức tín dụng token hàng tháng, khách hàng có thể mua gói nạp tiền khi gần hết, và backend của bạn tự động trừ tín dụng khi các yêu cầu được xử lý bởi OpenAI.Documentation Index
Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
Use this file to discover all available pages before exploring further.
- Tạo chế độ cấp phát tín dụng tùy chỉnh (token) và meter tự động trừ từ đó
- Gắn tín dụng cho các gói đăng ký (có và không có quá hạn) và sản phẩm nạp tiền một lần
- Kết nối điểm kết thúc hoàn thành thực OpenAI mà tính tiền token thông qua Dodo Payments
- Truy vấn số dư tín dụng trực tiếp của khách hàng qua SDK
- Xác minh chữ ký webhook và điều hướng sự kiện tín dụng Dodo Payments
Điều Chúng Ta Đang Xây Dựng
Đây là mô hình giá cho NeuralAPI:| Sản phẩm | Giá | Token | Quá hạn |
|---|---|---|---|
| Gói Khởi Đầu | 29$/tháng | 10,000,000 token/chu kỳ | Chặn tại không |
| Gói Chuyên Nghiệp | 99$/tháng | 40,000,000 token/chu kỳ | 0,005$ mỗi 1K token |
| Gói Nạp Token | 19$ một lần | +5,000,000 token | — |
- Tài khoản Dodo Payments (chế độ kiểm tra là ổn)
- Khóa API OpenAI
- Node.js 18+
- Kiến thức cơ bản về TypeScript/Node.js
Bước 1: Tạo Quyền Tín dụng Token của Bạn
Đầu tiên, tạo quyền tín dụng mà cả hai gói đăng ký và gói nạp sẽ chia sẻ. Hãy xem đây là việc định nghĩa đơn vị “token” mà nền tảng của bạn sử dụng.
Navigate to Credits
- Đăng nhập vào bảng điều khiển Dodo Payments của bạn
- Nhấp vào Sản phẩm trong thanh bên trái
- Chọn tab Tín dụng
- Nhấp vào Tạo Tín dụng
Configure the credit unit
API TokensLoại Tín dụng: Chọn Đơn vị Tùy chỉnhTên Đơn vị: tokenĐộ chính xác: 0 (token luôn là số nguyên)Hạn Tín dụng: 30 days (tín dụng được làm mới mỗi chu kỳ thanh toán)Skip overage at the credit level
Bước 2: Tạo một Meter cho Việc Sử dụng Token
Một meter tổng hợp các sự kiện sử dụng đến và chuyển đổi chúng thành các khoản trừ tín dụng. Bạn cần điều này trước khi tạo các sản phẩm gói, vì bạn sẽ gắn nó trong quá trình tạo sản phẩm ở Bước 3.Open the Meters section
- Trong thanh bên của bảng điều khiển, đi đến Sản phẩm → Meter
- Nhấp vào Tạo Meter
Configure the meter
Token Usage MeterTên Sự kiện: api.tokens_used (điều này phải khớp chính xác với những gì ứng dụng của bạn gửi)Loại Tổng hợp: Sum — chúng tôi tính tổng số lượng token từ mỗi sự kiệnThuộc tính Over: tokens — khóa metadata trên mỗi sự kiện mà giá trị sẽ được tính tổngĐơn vị Đo lường: tokensLưu meter và sao chép ID của nó — bạn sẽ tham chiếu nó khi gắn vào các sản phẩm.Bước 3: Tạo Các Sản phẩm Gói
Cả hai gói cần phải là sản phẩm Thanh toán Dựa trên Sử dụng, không phải là Đăng ký đơn giản — meter chỉ có thể gắn vào sản phẩm UBB, và bạn cần meter để tự động trừ tín dụng khi khách hàng gọi API của bạn. Sản phẩm UBB vẫn hỗ trợ phí cơ bản định kỳ ($29 / $99); sử dụng trên đó được tính bằng tín dụng.

Gói Khởi Đầu (29$/tháng — 10M token, không quá hạn)
Create the Starter UBB product
- Đi đến Sản phẩm → Tạo Sản phẩm
- Chọn Thanh toán Dựa trên Sử dụng làm loại giá
- Điền vào:
NeuralAPI StarterMiêu tả: 10 million API tokens per month. Perfect for individual developers and small projects.Giá Cố định: 29.00 (phí cơ bản định kỳ — tính hàng tháng ngay cả trước khi sử dụng)Chu kỳ Thanh toán: MonthlyTiền tệ: USDAttach the meter
Token Usage Meter. Sau đó trên meter:- Chuyển Tính tiền sử dụng bằng Tín dụng sang
- Quyền Tín dụng: chọn
API Tokens - Đơn vị meter trên mỗi tín dụng:
1— mỗi token trong sự kiện tương ứng với 1 tín dụng bị trừ - Ngưỡng Miễn phí:
0— sự phân bổ tín dụng tự nó là “tầng miễn phí” của khách hàng; chúng tôi không cần thêm một lớp miễn phí khác

api.tokens_used đến thực sự trừ từ số dư của khách hàng.Configure credit issuance for Starter
10000000Cho phép Quá hạn: Vô hiệu — Khách hàng Gói Khởi Đầu bị chặn khi hết tokenNhập Cài đặt Tín dụng Mặc định: Bật — sử dụng hạn 30 ngày từ quyền tín dụng
Gói Chuyên Nghiệp (99$/tháng — 40M token, quá hạn được bật)
Create the Pro UBB product
NeuralAPI ProMiêu tả: 40 million API tokens per month with overage. Built for production applications.Giá Cố định: 99.00Chu kỳ Thanh toán: MonthlyTiền tệ: USDAttach the meter
Token Usage Meter, chuyển Tính tiền sử dụng bằng Tín dụng sang, chọn API Tokens, Đơn vị meter trên mỗi tín dụng 1, Ngưỡng Miễn phí 0.Configure credit issuance with overage
40000000Nhập Cài đặt Tín dụng Mặc định: Vô hiệu — chúng ta cần tùy chỉnh cài đặt quá hạn cho từng sản phẩmCho phép Quá hạn: BậtGiá mỗi đơn vị: 0.000005 USD mỗi token (tức là, 0,005 mỗi 1M token — cao hơn tỷ lệ token hiệu quả của gói để hạn chế tràn)Hành vi Quá hạn: Bill overage at billing — quá hạn được tính trên hóa đơn tiếp theo, sau đó số dư được làm mớiLưu sản phẩm và sao chép ID sản phẩm.Bước 4: Tạo Gói Nạp Token
Gói nạp là một giao dịch mua một lần cấp 5,000,000 token vào số dư hiện có của khách hàng.
Create a one-time product
- Đi đến Sản phẩm → Tạo Sản phẩm
- Chọn Thanh toán Đơn là loại giá
- Điền vào:
Token Top-Up PackMiêu tả: Instantly add 5 million tokens to your NeuralAPI balance.Giá: 19.00Tiền tệ: USDAttach the token credit
- Trong phần Quyền lợi, nhấp vào Gắn bên cạnh Tín dụng
- Chọn
API Tokens - Đặt Tín dụng xuất hiện:
5000000 - Vô hiệu Nhập Cài đặt Tín dụng Mặc định — chúng tôi muốn ghi đè hạn mặc định 30 ngày
- Đặt Hạn Tín dụng:
365 days - Lưu sản phẩm
Bước 5: Xây dựng Backend
Bây giờ hãy xây dựng máy chủ Express xử lý thanh toán đăng ký, thanh toán nạp, hoàn thành OpenAI thực với tính tiền token, truy vấn số dư, và sự kiện webhook tín dụng.Set up environment variables
.env với thông tin đăng nhập của bạn và các ID từ các bước trước:DODO_PAYMENTS_WEBHOOK_KEY ở Bước 7 sau khi đăng ký điểm kết thúc webhook của bạn.Implement the server
src/server.ts:A note on how deductions actually happen
- Trình xử lý của bạn gọi OpenAI và nhận lại
usage.total_tokens(ví dụ: 1532). - Bạn lấy một sự kiện sử dụng duy nhất:
event_name: api.tokens_used,metadata: { tokens: 1532 }. Token Usage Metertổng hợp sự kiện theo khách hàng.- Vì meter được kết nối với tín dụng
API Tokensvới Tính tiền sử dụng bằng Tín dụng, Dodo Payments trừ 1532 tín dụng từ khoản cấp phát không hết hạn cũ nhất của khách hàng (FIFO). - Nếu quá hạn được bật và khách hàng giảm dưới không, thiếu hụt được đo lường và tính trên hóa đơn tiếp theo.
Bước 6: Thêm Một Giao Diện Demo
Tạopublic/index.html để kiểm tra tất cả các luồng trong trình duyệt của bạn. Chúng tôi giữ ID khách hàng vào localStorage để đăng ký → tạo → nạp đều chia sẻ cùng một danh tính, giả lập một ứng dụng đã đăng nhập:
Bước 7: Kết Nối Webhook
Webhook cho phép máy chủ của bạn phản ứng với thay đổi số dư — bạn sẽ dùng chúng để gửi email “gần hết” trước khi khách hàng đạt không.Expose your local server
https://...ngrok-free.app.Register the webhook in Dodo Payments
- Trong bảng điều khiển, đi đến Nhà phát triển → Webhook → Thêm Điểm kết thúc
- URL:
https://your-tunnel.ngrok-free.app/webhooks/dodo - Đăng ký ít nhất với:
credit.addedcredit.deductedcredit.overage_charged
- Lưu và sao chép Bí mật Chữ ký
- Dán vào
.envdưới dạngDODO_PAYMENTS_WEBHOOK_KEY, sau đó khởi động lạinpm run dev
Bước 8: Kiểm tra Luồng Đầy Đủ
Subscribe a test customer
- Chạy
npm run dev - Mở
http://localhost:3000 - Chọn Gói Pro, nhập email + tên thử nghiệm, nhấp vào Nhận Liên kết Thanh toán, hoàn tất thanh toán bằng chi tiết thẻ thử nghiệm
- Trong bảng điều khiển, đi đến Khách hàng → mới nhất và sao chép ID
cus_... - Dán vào trường “ID khách hàng đã đăng nhập” trên bản demo và nhấp vào Lưu
Generate a real AI response
total_tokens thực tế, lấy một sự kiện sử dụng, và trả kết quả.Khắc phục sự cố
Credits not deducting after usage events
Credits not deducting after usage events
- Tên sự kiện của meter không khớp với
event_namebạn đang gửi (api.tokens_usedlà phân biệt chữ hoa chữ thường) - Meter không được liên kết với tín dụng
API Tokenstrên sản phẩm — đi tới cấu hình meter của sản phẩm và xác nhận Tính tiền sử dụng bằng Tín dụng được bật - Khóa
metadata.tokenskhông khớp với trường “Thuộc tính Over” của meter - Quyền của khách hàng đã hết hạn (kiểm tra lịch sử tín dụng của khách hàng)
- Sản phẩm → Meter: mở meter và xác nhận nó hiển thị tên tín dụng liên kết trên sản phẩm đã đính kèm
- Tab Sự kiện trên meter — các sự kiện đã lấy nên xuất hiện ở đó ngay cả trước khi trừ
- Khách hàng → [Khách hàng] → Tín dụng: mục nhập sổ sách nên xuất hiện trong vòng một hai phút
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- Khách hàng chưa hoàn tất thanh toán — tín dụng chỉ được cấp phát sau khi thanh toán thành công
- Bạn đang truy vấn với
customer_idsai (sử dụng IDcus_...từ bảng điều khiển, không phải ID DB của bạn) CREDIT_ENTITLEMENT_IDtrong.envkhông khớp với tín dụng được đính kèm vào sản phẩm
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- Quá hạn chưa được bật trên Cấu hình tín dụng của sản phẩm Pro (cài đặt cấp tín dụng chỉ là mặc định)
- Khách hàng thực sự đang dùng Gói Khởi Đầu, không phải Pro
- Giới hạn quá hạn được đặt thành 0
0.000005 (= $5 mỗi triệu token; kiểm tra lại các số không đứng đầu — trường nhận giá per-token, không phải per-1K).`Webhook verification failed` in logs
`Webhook verification failed` in logs
- Thứ tự phân tích thân:
express.json()đã được áp dụng cho/webhooks/dodotrướcexpress.raw()— SDK cần byte thô của yêu cầu, không phải JSON đã phân tích - Bí mật chữ ký sai trong
DODO_PAYMENTS_WEBHOOK_KEY - Proxy ngược đang viết lại các tiêu đề
app.use('/webhooks/dodo', express.raw(...)) xuất hiện trước app.use(express.json()) trong server.ts.Cần hỗ trợ?
Chúc mừng! Bạn Đã Xây Dựng Hệ thống Thanh toán Dựa trên Tín dụng cho NeuralAPI
Nền tảng của bạn bây giờ đã có hệ thống thanh toán tín dụng hoàn chỉnh và sẵn sàng sản xuất:Token Credit Entitlement
API Tokens dùng lại với hạn 30 ngày, được chia sẻ qua tất cả các gói và gói nạpTiered Plans, One Credit
One-Time Top-Up Pack
Auto-Deduction via Meter
Live Balance API
Verified Webhook Pipeline
credit.added, credit.deducted, credit.overage_charged) được điều hướng thông qua trình xử lý xác minh chữ ký sử dụng trợ giúp Standard Webhooks của SDK- Xác thực trên
/credits/:customerIdvà/api/generate— hiện tại ai cũng có thể truy cập chúng với bất kỳ ID khách hàng nào. Xác thực người dùng và tra cứu ID khách hàng của họ từ phía máy chủ. - Các ID yêu cầu ổn định
event_id— ví dụ này sử dụngDate.now() + random. Trong sản xuất, sử dụng ID yêu cầu của bạn để đảm bảo các thử lại là idempotent (Dodo Payments loại trừ theoevent_id). - Lưu trữ ánh xạ khách hàng↔người dùng — lưu
customer_idvào DB của bạn sau lần thanh toán đầu tiên để bạn không cần bước dán thủ công. - Quyết định điều gì xảy ra khi một đăng ký kết thúc. Các tín dụng gói vẫn ở trong sổ cái của khách hàng cho đến khi hết hạn tự nhiên của chúng (30 ngày kể từ khi cấp phát) và tín dụng nạp vẫn có giá trị trong 365 ngày — nhưng
/api/generatecủa công thức chỉ kiểm tra số dư, không kiểm tra trạng thái đăng ký. Vì vậy, một khách hàng bị hủy bỏ vẫn có thể tiêu thụ số token còn lại. Đó là mặc định thân thiện với người tiêu dùng. Nếu bạn muốn kiểm soát truy cập chặt chẽ hơn, hoặc (a) lắng nghe webhooksubscription.cancelledvà kiểm soát/api/generatedựa trên trạng thái đăng ký, hoặc (b) gọi API sổ cái của Dodo để trừ các tín dụng gói chưa sử dụng khi hủy trong khi để lại tín dụng nạp nguyên vẹn. - Giám sát bảng điều khiển Thanh toán Sử dụng để phát hiện các bất thường trong đo lường sớm.