Skip to main content
Để coding agent viết integration cho bạn, hãy cài đặt Dodo Agent Plugin. Plugin này bổ sung các kỹ năng và MCP servers của Dodo Payments vào Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro và OpenCode.
Bạn sẽ xây dựng NeuralAPI, một AI API phân tầng trong đó mỗi subscription plan bao gồm một hạn mức token credits hàng tháng. Khi sắp dùng hết, khách hàng sẽ mua một gói nạp thêm, còn backend của bạn báo cáo số token mà mỗi request OpenAI sử dụng để Dodo Payments trừ chúng khỏi số dư của khách hàng.
Tutorial này sử dụng Node.js, Express và OpenAI SDK. Các khái niệm của Dodo Payments (credits, meters và webhooks) hoạt động tương tự với mọi framework hoặc AI provider.
Sau khi hoàn tất, bạn sẽ biết cách:
  • 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: Trước khi bắt đầu, bạn cần:
  • 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.
Credits listing page showing created credit entitlements

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. Đăng nhập vào dashboard Dodo Payments.
  2. Nhấp Products trong sidebar.
  3. Chọn tab Credits.
  4. Nhấp Create Credit.
2

Configure the Credit Unit

Nhập các giá trị sau:Credit Name: 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.
Không thể thay đổi precision sau khi tạo credit. Với số lượng token, hãy sử dụng 0.
3

Skip Overage at the Credit Level

Để overage ở trạng thái disabled trên credit. Bạn cấu hình tùy chọn này cho từng plan khi gắn credit vào mỗi sản phẩm, để Starter plan có thể chặn việc sử dụng khi về 0 trong khi Pro plan cho phép overage.
Các cài đặt overage trên credit là giá trị mặc định. Mỗi product attachment có thể ghi đè các cài đặt này; Step 3 sẽ thực hiện điều đó cho Pro plan.
4

Save and Copy the Credit ID

Nhấp Create Credit. Mở credit đã lưu và sao chép ID của nó; ID bắt đầu bằng cde_.
Credit entitlement 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.
1

Open the Meters Section

  1. Trong sidebar của dashboard, đi tới Products → Meters.
  2. Nhấp Create Meter.
2

Configure the Meter

Nhập các giá trị sau:Meter Name: 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: tokens
Event names phân biệt chữ hoa chữ thường: api.tokens_used và Api.Tokens.Used là các events khác nhau. Bạn không thể chỉnh sửa meter sau khi tạo, vì vậy hãy kiểm tra mọi giá trị trước khi xác nhận.
Tạo meter. Bạn sẽ chọn meter theo tên khi gắn vào các sản phẩm.
Meter đã được tạo. Tiếp theo, hãy liên kết meter với credit trên mỗi plan product.

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 configuration

Usage Based Billing pricing type with meter configuration.

Starter Plan ($29/tháng — 10M Tokens, Không có Overage)

1

Create the Starter Product

  1. Đi tới Products và nhấp Add Product.
  2. Trong Pricing Type, chọn Usage Based Billing.
  3. Nhập các giá trị sau:
Product Name: 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: USD
2

Attach the Meter

Trong phần Select meter, nhấp + và thêm Token Usage Meter. Sau đó cấu hình meter:
  1. Bật Bill usage in credits.
  2. Select credit: API Tokens
  3. Meter units per credit: 1. Mỗi token trong một event sẽ trừ một credit.
  4. 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ư.
Meter with Bill usage in Credits enabled and API Tokens selected

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.

Liên kết này khiến các events api.tokens_used đến trừ khỏi số dư của khách hàng.
3

Configure Credit Issuance for Starter

Sau khi gắn một credit-billed meter, sản phẩm sẽ hiển thị phần cấu hình credit. Nhập:Credits issued per billing cycle: 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.
Credit configuration form with per-cycle amount and overage settings

Configure credit issuance per cycle on the UBB product.

Lưu sản phẩm và sao chép ID của nó; ID bắt đầu bằng pdt_.
Starter Plan: phí cơ bản $29/tháng, 10M tokens mỗi chu kỳ, bị chặn khi về 0 và được trừ thông qua meter.

Pro Plan ($99/tháng — 40M Tokens, Bật Overage)

1

Create the Pro Product

Thực hiện quy trình như Starter với các giá trị sau:Product Name: NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 thángCurrency: USD
2

Attach the Meter

Cấu hình meter như với Starter: thêm 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.
3

Configure Credit Issuance with Overage

Cấu hình việc cấp credits, lần này bật overage:Credits issued per billing cycle: 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ó.
Pro Plan: phí cơ bản $99/tháng, 40M tokens mỗi chu kỳ, overage ở mức $0.005 mỗi 1K tokens và được trừ thông qua meter.

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.
Product pricing section with Single Payment selected

One-time pricing selected for a credit product.

1

Create a One-Time Product

  1. Đi tới Products và nhấp Add Product.
  2. Trong Pricing Type, chọn One Time.
  3. Nhập các giá trị sau:
Product Name: Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USD
2

Attach the Token Credit

  1. Trong phần Entitlements, nhấp Attach bên cạnh Credits.
  2. Chọn API Tokens.
  3. Đặt No of credits issued thành 5000000.
  4. Tắt Import Default Credit Settings để ghi đè thời hạn 30 ngày mặc định.
  5. Đặt Credit Expiry thành Custom và nhập 365 ngày.
  6. Lưu sản phẩm.
Sao chép product ID.
Tại sao thời hạn hết hạn của các gói nạp thêm lại dài hơn? Credit thuê bao hết hạn sau 30 ngày vì đó là chu kỳ thanh toán. Gói nạp thêm là một giao dịch mua trả trước: khách hàng đã thanh toán trước $19 và kỳ vọng token có thời hạn lâu hơn một tháng. Thời hạn 365 ngày phù hợp với cách credit API trả trước hoạt động tại OpenAI và Anthropic, nơi credit đã mua hết hạn một năm sau ngày mua, đồng thời vẫn giới hạn trách nhiệm của bạn để khách hàng không thể tích trữ credit vô thời hạn.
Top-Up Pack đã được cấu hình. Khi mua, khách hàng nhận 5,000,000 tokens có hiệu lực trong 365 ngày.

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.
1

Set Up Your Project

Tạo một tsconfig.json:
tsconfig.json
Cập nhật các scripts của package.json:
package.json
2

Set Up Environment Variables

Tạo .env bằng test mode API key từ Developer → API Keys và các IDs từ các bước trước:
.env
Không bao giờ commit .env vào version control. Hãy thêm nó vào .gitignore trước commit đầu tiên.
Bạn sẽ điền DODO_PAYMENTS_WEBHOOK_KEY ở Step 7, sau khi đăng ký webhook endpoint.
3

Implement the Server

Tạo 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 đủ:
Phần backend đã hoàn tất: checkout thuê bao, checkout gói nạp thêm, completion của OpenAI với tính phí token theo mức sử dụng, đọc số dư và handler webhook đã được xác minh.
@dodopayments/ingestion-blueprints cung cấp các tracker để thực hiện lệnh gọi usageEvents.ingest thay bạn, bao gồm usage của LLM Blueprint, API gateway, object storage, streams và time-range.
4

How Deductions Happen

Server không bao giờ gọi endpoint “deduct N credits”. Meter thực hiện việc khấu trừ:
  1. Handler của bạn gọi OpenAI và đọc usage.total_tokens, chẳng hạn 1532.
  2. Bạn ingest một usage event với event_name: api.tokens_used và metadata: { tokens: 1532 }.
  3. Token Usage Meter tổ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.
  4. Vì meter tính phí API Tokens credit 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).
  5. 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.
Code của bạn chỉ ingest các event.

Bước 6: Thêm Demo Frontend

Tạo public/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.
1

Expose Your Local Server

Webhook cần một URL public. Để phát triển trên local, hãy dùng ngrok hoặc một tunnel khác:
Sao chép HTTPS forwarding URL, kết thúc bằng ngrok-free.app.
2

Register the Webhook in Dodo Payments

  1. Trong dashboard, đi tới Developer → Webhooks và nhấp Add endpoint.
  2. Nhập URL https://your-tunnel.ngrok-free.app/webhooks/dodo, sử dụng tunnel host của riêng bạn.
  3. Chọn ít nhất các event sau:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Nhấp Create endpoint, sau đó sao chép signing secret từ tab Overview của endpoint.
  5. Dán secret vào .env dưới dạng DODO_PAYMENTS_WEBHOOK_KEY, sau đó khởi động lại npm run dev.
dodo.webhooks.unwrap() của SDK kiểm tra các header webhook-id, webhook-timestamp và webhook-signature bằng signing secret của bạn, sau đó phân tích payload. Đừng tự viết kiểm tra HMAC: Dodo Payments tuân theo Standard Webhooks, ký id.timestamp.body chứ không chỉ riêng body.

Bước 8: Kiểm thử Flow Đầy đủ

1

Subscribe a Test Customer

  1. Chạy npm run dev.
  2. Mở http://localhost:3000.
  3. 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ử.
  4. 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_.
  5. Dán ID vào trường Logged-in customer ID trên demo rồi nhấp Save.
Customer có 40.000.000 token. Nhấp Refresh Balance để xác nhận.
2

Generate an AI Response

Nhập prompt rồi nhấp Generate. Server gọi OpenAI, đọc total_tokens thực tế, ingest một usage event và trả về response.
Background worker xử lý các usage event mỗi phút, vì vậy số dư không giảm ngay lập tức. Chờ một hoặc hai phút, sau đó nhấp Refresh Balance lần nữa. Số dư không thay đổi ở lần refresh đầu tiên không có nghĩa là metering đã thất bại.
3

Test the Top-Up Flow

Nhấp Buy 5M Tokens — $19 và hoàn tất checkout. Sau khi thanh toán thành công, refresh số dư: số dư sẽ tăng thêm 5.000.000 token và log của server hiển thị một event credit.added.

Khắc phục sự cố

Nguyên nhân có thể xảy ra:
  • Tên event của meter không khớp với event_name mà bạn gửi. api.tokens_used phân biệt chữ hoa chữ thường.
  • Meter chưa được liên kết với credit API Tokens trê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.tokens khô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.
Cần kiểm tra:
  1. Trong Products → Meters, mở meter và xác nhận product attachment hiển thị tên credit được liên kết.
  2. Mở tab Events của meter. Các event đã ingest sẽ xuất hiện ở đó ngay cả trước khi có khấu trừ.
  3. 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.
Nguyên nhân có thể xảy ra:
  • 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_id không đúng. Hãy dùng ID bắt đầu bằng cus_ trong dashboard, không phải ID từ database riêng của bạn.
  • CREDIT_ENTITLEMENT_ID trong .env không khớp với credit được gắn vào product.
Cần kiểm tra: Mở customer trong Customers và chọn tab Credits. Nếu không có credit nào xuất hiện, credit chưa được gắn vào product hoặc thanh toán chưa hoàn tất.
Nguyên nhân có thể xảy ra:
  • 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.
Cần kiểm tra: Chỉnh sửa product Pro, mở credit trong Entitlements và xác nhận Allow Overage đã được bật, còn Price Per Unit là 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.
Nguyên nhân có thể xảy ra:
  • Thứ tự phân tích body: express.json() đã chạy trên /webhooks/dodo trước express.raw(). SDK cần raw bytes của request, không phải JSON đã được phân tích.
  • DODO_PAYMENTS_WEBHOOK_KEY chứa signing secret không đúng.
  • Reverse proxy đã ghi đè các request header.
Cần kiểm tra: Xác nhận dòng 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

Một credit 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

Starter (10M token, giới hạn cứng) và Pro (40M token cộng overage), được cấu hình theo từng product mà không cần nhân bản credit.

One-Time Top-Up Pack

Customer có thể thêm 5M token với giá $19 mà không thay đổi thuê bao.

Deduction Through a Meter

Số lượng token OpenAI thực tế được ingest dưới dạng event, còn meter khấu trừ credit theo FIFO mà không cần theo dõi thủ công.

Live Balance API

Số dư hiện tại được đọc thông qua SDK để giới hạn quyền truy cập, hiển thị usage hoặc cảnh báo customer trong app của bạn.

Verified Webhook Pipeline

Các event trong credit ledger (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.
Đang chuẩn bị đưa vào production? Hãy siết chặt các điểm sau:
  • Thêm authentication cho /credits/:customerId và /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ụng Date.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_id mà hệ thống đã ingest trước đó.
  • Lưu mapping customer-to-user. Lưu customer_id và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/generate trong 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 webhook subscription.cancelled và giới hạn /api/generate dự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.

Credit-Based Billing Reference

Rollover, các chế độ overage, quản lý ledger và mọi credit API endpoint.

Credit Webhook Events

Payload schema cho mọi credit event mà server của bạn có thể nhận.
Lần sửa đổi cuối 26 tháng 9, 2026