- Tạo custom credit entitlement cho tokens và một meter để trừ từ entitlement đó.
- Gắn credits vào subscription plans, có hoặc không có overage, và vào một sản phẩm top-up dùng một lần.
- Gọi OpenAI từ một endpoint tính phí tokens thông qua Dodo Payments.
- Đọc số dư credits hiện tại của khách hàng bằng SDK.
- Xác minh webhook signatures và định tuyến các credit events của Dodo Payments.
Điều Chúng Ta Đang Xây Dựng
NeuralAPI bán ba sản phẩm:- Một tài khoản Dodo Payments. Hãy thực hiện mọi thao tác trong test mode.
- Một OpenAI API key.
- Node.js 22 trở lên và kiến thức sử dụng TypeScript và Node.js.
Bước 1: Tạo Token Credit Entitlement
Tạo credit entitlement mà cả hai plans và top-up pack sẽ dùng chung. Entitlement này xác định đơn vị token mà NeuralAPI bán.
The Credits tab under Products shows all your credit entitlements.
Navigate to Credits
- Đăng nhập vào dashboard Dodo Payments.
- Nhấp Products trong sidebar.
- Chọn tab Credits.
- Nhấp Create Credit.
Configure the Credit Unit
API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. Số lượng token là số nguyên.Credit Expiry: 30 days. Credits hết hạn 30 ngày sau khi được cấp, phù hợp với chu kỳ billing hàng tháng.Skip Overage at the Credit Level
Save and Copy the Credit ID
cde_.API Tokens đã sẵn sàng. Tiếp theo, hãy tạo một meter để usage events trừ credits.Bước 2: Tạo Meter cho Token Usage
Meter tổng hợp các usage events đến. Khi liên kết meter với một credit, usage đã tổng hợp sẽ được trừ khỏi số dư credit của khách hàng. Hãy tạo meter trước các plan products, vì bạn sẽ gắn meter này trong lúc tạo chúng ở Step 3.Open the Meters Section
- Trong sidebar của dashboard, đi tới Products → Meters.
- Nhấp Create Meter.
Configure the Meter
Token Usage MeterEvent Name: api.tokens_used. Giá trị này phải khớp với event_name mà ứng dụng của bạn gửi.Aggregation Type: Sum, để cộng tổng số token từ mỗi event.Over Property: tokens, metadata key có giá trị được cộng tổng.Measurement Unit: tokensTạo meter. Bạn sẽ chọn meter theo tên khi gắn vào các sản phẩm.Bước 3: Tạo Plan Products
Tạo cả hai plans với pricing type Usage Based Billing, không dùng Subscription thông thường. Meters được gắn vào Usage Based Billing products, và meter sẽ trừ credits khi khách hàng gọi API của bạn. Usage Based Billing product vẫn tính một khoản phí cơ bản định kỳ ($29 hoặc $99), còn usage phát sinh thêm sẽ được tính bằng credits.
Usage Based Billing pricing type with meter configuration.
Starter Plan ($29/tháng — 10M Tokens, Không có Overage)
Create the Starter Product
- Đi tới Products và nhấp Add Product.
- Trong Pricing Type, chọn Usage Based Billing.
- Nhập các giá trị sau:
NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Đây là phí cơ bản định kỳ, được tính mỗi tháng ngay cả khi chưa phát sinh usage.Repeat payment every: 1 thángCurrency: USDAttach the Meter
Token Usage Meter. Sau đó cấu hình meter:- Bật Bill usage in credits.
- Select credit:
API Tokens - Meter units per credit:
1. Mỗi token trong một event sẽ trừ một credit. - Free Threshold:
0. Free threshold chỉ áp dụng khi meter tính phí bằng tiền. Khi meter tính phí bằng credits, mọi unit đều được trừ khỏi số dư.

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.
api.tokens_used đến trừ khỏi số dư của khách hàng.Configure Credit Issuance for Starter
10000000Import Default Credit Settings: bật, để sản phẩm sử dụng thời hạn 30 ngày từ credit entitlement.Allow Overage: tắt. Giá trị mặc định từ Step 1 giữ overage ở trạng thái tắt, vì vậy khách hàng Starter sẽ dừng khi số dư về 0.
Configure credit issuance per cycle on the UBB product.
pdt_.Pro Plan ($99/tháng — 40M Tokens, Bật Overage)
Create the Pro Product
NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 thángCurrency: USDAttach the Meter
Token Usage Meter, bật Bill usage in credits, chọn API Tokens và đặt Meter units per credit thành 1 तथा Free Threshold thành 0.Configure Credit Issuance with Overage
40000000Import Default Credit Settings: tắt, để bạn có thể đặt overage cho sản phẩm này.Allow Overage: bậtPrice Per Unit: 0.000005 USD mỗi token. Tương đương $0.005 mỗi 1K tokens hoặc $5 mỗi 1M tokens, cao hơn mức giá hiệu dụng trên mỗi token của plan và hạn chế overage.Overage Behavior: Bill overage at billing. Overage được tính trên invoice tiếp theo, sau đó số dư được reset.Lưu sản phẩm và sao chép ID của nó.Bước 4: Tạo Token Top-Up Pack
Top-up pack là giao dịch mua một lần, bổ sung 5,000,000 tokens vào số dư hiện có của khách hàng.
One-time pricing selected for a credit product.
Create a One-Time Product
- Đi tới Products và nhấp Add Product.
- Trong Pricing Type, chọn One Time.
- Nhập các giá trị sau:
Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USDAttach the Token Credit
- Trong phần Entitlements, nhấp Attach bên cạnh Credits.
- Chọn
API Tokens. - Đặt No of credits issued thành
5000000. - Tắt Import Default Credit Settings để ghi đè thời hạn 30 ngày mặc định.
- Đặt Credit Expiry thành Custom và nhập
365ngày. - Lưu sản phẩm.
Bước 5: Xây dựng Backend
Xây dựng Express server. Server tạo subscription và top-up checkouts, gọi OpenAI và tính phí tokens, đọc số dư và nhận các credit webhook events.Set Up Your Project
tsconfig.json:package.json:Set Up Environment Variables
.env bằng test mode API key từ Developer → API Keys và các IDs từ các bước trước:DODO_PAYMENTS_WEBHOOK_KEY ở Step 7, sau khi đăng ký webhook endpoint.Implement the Server
src/server.ts. Completion endpoint gọi model gpt-6-luna của OpenAI, phù hợp với các request có lưu lượng lớn. Tab package.json hiển thị danh sách dependency đầy đủ:How Deductions Happen
- Handler của bạn gọi OpenAI và đọc
usage.total_tokens, chẳng hạn 1532. - Bạn ingest một usage event với
event_name: api.tokens_usedvàmetadata: { tokens: 1532 }. Token Usage Metertổng hợp các event theo từng khách hàng. Background worker xử lý các event mới mỗi phút.- Vì meter tính phí
API Tokenscredit thông qua Bill usage in credits, Dodo Payments khấu trừ 1532 credit, bắt đầu từ grant của khách hàng hết hạn trước (FIFO). - Nếu overage được bật và số dư cạn kiệt, phần thiếu sẽ được theo dõi và tính phí trên invoice tiếp theo.
Bước 6: Thêm Demo Frontend
Tạopublic/index.html để kiểm thử mọi flow trong browser. Trang lưu customer ID trong localStorage, vì vậy các thao tác subscribe, generate và top-up dùng chung một identity, giống như trong một app đã đăng nhập:
Bước 7: Kết nối Webhook
Webhook cho phép server phản hồi với các thay đổi về số dư, chẳng hạn gửi email cho khách hàng khi số dư của họ sắp cạn.Expose Your Local Server
ngrok-free.app.Register the Webhook in Dodo Payments
- Trong dashboard, đi tới Developer → Webhooks và nhấp Add endpoint.
- Nhập URL
https://your-tunnel.ngrok-free.app/webhooks/dodo, sử dụng tunnel host của riêng bạn. - Chọn ít nhất các event sau:
credit.addedcredit.deductedcredit.overage_charged
- Nhấp Create endpoint, sau đó sao chép signing secret từ tab Overview của endpoint.
- Dán secret vào
.envdưới dạngDODO_PAYMENTS_WEBHOOK_KEY, sau đó khởi động lạinpm run dev.
Bước 8: Kiểm thử Flow Đầy đủ
Subscribe a Test Customer
- Chạy
npm run dev. - Mở
http://localhost:3000. - Chọn Pro, nhập email và tên dùng để kiểm thử, rồi nhấp Get Checkout Link. Hoàn tất checkout bằng thông tin thẻ kiểm thử.
- Trong dashboard, đi tới Customers, mở customer mới nhất và sao chép ID của customer đó, bắt đầu bằng
cus_. - Dán ID vào trường Logged-in customer ID trên demo rồi nhấp Save.
Generate an AI Response
total_tokens thực tế, ingest một usage event và trả về response.Test the Top-Up Flow
credit.added.Khắc phục sự cố
Credits not deducting after usage events
Credits not deducting after usage events
- Tên event của meter không khớp với
event_namemà bạn gửi.api.tokens_usedphân biệt chữ hoa chữ thường. - Meter chưa được liên kết với credit
API Tokenstrên product. Mở cấu hình meter của product và xác nhận Bill usage in credits đã được bật. - Key
metadata.tokenskhông khớp với Over Property của meter. - Grant của customer đã hết hạn. Kiểm tra credit history của customer.
- Trong Products → Meters, mở meter và xác nhận product attachment hiển thị tên credit được liên kết.
- Mở tab Events của meter. Các event đã ingest sẽ xuất hiện ở đó ngay cả trước khi có khấu trừ.
- Mở customer trong Customers và chọn tab Credits. Các mục trong ledger sẽ xuất hiện trong vòng một hoặc hai phút.
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- Customer chưa hoàn tất checkout. Credit chỉ được cấp sau khi thanh toán thành công.
- Bạn đang query bằng
customer_idkhông đúng. Hãy dùng ID bắt đầu bằngcus_trong dashboard, không phải ID từ database riêng của bạn. CREDIT_ENTITLEMENT_IDtrong.envkhông khớp với credit được gắn vào product.
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- Overage chưa được bật trên credit attachment của product Pro. Cài đặt trên credit chỉ là giá trị mặc định.
- Customer đang dùng Starter, không phải Pro.
- Overage Limit được đặt thành 0.
0.000005 ($5 cho mỗi triệu token). Kiểm tra các số 0 ở đầu: trường này nhận giá trên mỗi token, không phải trên mỗi 1K token.Webhook verification failed in logs
Webhook verification failed in logs
- Thứ tự phân tích body:
express.json()đã chạy trên/webhooks/dodotrướcexpress.raw(). SDK cần raw bytes của request, không phải JSON đã được phân tích. DODO_PAYMENTS_WEBHOOK_KEYchứa signing secret không đúng.- Reverse proxy đã ghi đè các request header.
app.use('/webhooks/dodo', express.raw(...)) đứng trước app.use(express.json()) trong server.ts.Cần trợ giúp?
Chúc mừng! Bạn đã xây dựng hệ thống thanh toán dựa trên credit cho NeuralAPI
NeuralAPI giờ đây tính phí bằng credit từ checkout đến khấu trừ:Token Credit Entitlement
API Tokens có thể tái sử dụng, hết hạn sau 30 ngày và được dùng chung cho cả hai plan cùng gói nạp thêm.Tiered Plans, One Credit
One-Time Top-Up Pack
Deduction Through a Meter
Live Balance API
Verified Webhook Pipeline
credit.added, credit.deducted, credit.overage_charged) được chuyển qua một handler xác minh signature bằng helper Standard Webhooks của SDK.- Thêm authentication cho
/credits/:customerIdvà/api/generate. Với cách viết hiện tại, bất kỳ ai cũng có thể gọi chúng bằng bất kỳ customer ID nào. Hãy xác thực người dùng và tra cứu customer ID của họ trên server. - Sử dụng các giá trị
event_idổn định. Ví dụ sử dụngDate.now()cộng với một chuỗi ngẫu nhiên. Trong production, hãy dùng request ID để các lần retry có tính idempotent: Dodo Payments bỏ qua event cóevent_idmà hệ thống đã ingest trước đó. - Lưu mapping customer-to-user. Lưu
customer_idvào database sau lần checkout đầu tiên để người dùng không phải dán thủ công. - Quyết định điều gì xảy ra khi thuê bao kết thúc. Credit của plan vẫn nằm trong ledger của customer cho đến khi hết hạn 30 ngày sau khi được cấp, còn credit nạp thêm vẫn có hiệu lực trong 365 ngày.
/api/generatetrong tutorial chỉ kiểm tra số dư, không kiểm tra trạng thái thuê bao, vì vậy customer đã hủy vẫn có thể sử dụng token còn lại. Đây là giá trị mặc định thân thiện với customer. Để kiểm soát quyền truy cập chặt chẽ hơn, hãy (a) lắng nghe webhooksubscription.cancelledvà giới hạn/api/generatedựa trên trạng thái thuê bao, hoặc (b) khi hủy, ghi nợ credit plan chưa sử dụng bằng ledger API. Các khoản ghi nợ lấy từ grant hết hạn trước, vì vậy credit plan 30 ngày sẽ được dùng trước credit nạp thêm 365 ngày. - Theo dõi dashboard Usage Billing để sớm phát hiện các bất thường trong metering.