1. Sign up and complete KYB
Sign up at /signup — you land in a sandbox dashboard immediately. Sandbox supports all APIs and dashboard surfaces. When you're ready for live CNY collection, go to /merchant/activate to submit KYB (company registration, owner ID, bank proof) and enroll 2FA. ePayments reviews within 1–3 business days.
2. Create an API key
Create one at /merchant/developer. Start sandbox, move to live after testing. Scopes: usage:write (ingest events), invoice:read (read invoices), checkout:write (mint checkout URLs).
BUFFMONEY_API_KEY=bm_sandbox_AbCd1234.efGH56789longSecret
3. Define product, rate card, customer, contract
Four dashboard pages, also available via API:
/merchant/products— Define a product (e.g. chat_api) + publish a rate card. Prices in minor units./merchant/customers— One row per end-customer, referenced by your own externalId./merchant/contracts— Bind customer to rate card with a billing cycle (monthly_calendar etc.).
4. Stream usage events
Each metered action POSTs one event — tokens / agent runs / images / storage GB.
POST /api/v1/usage-events
Authorization: Bearer bm_sandbox_AbCd1234.efGH56789longSecret
Idempotency-Key: batch-2026-05-25-001
Content-Type: application/json
{
"events": [
{
"customerExternalId": "user_42",
"idempotencyKey": "evt_abc_1234",
"metric": "tokens_input",
"quantity": "12500",
"occurredAt": "2026-05-25T10:00:00Z",
"dimensions": { "model": "gpt-5", "region": "us-east-1" }
}
]
}Per-event idempotencyKey dedupes within the merchant. The Idempotency-Key header caches the full response 24h for safe retries. Full schema in API reference。
5. Generate invoices
A monthly cron generates one invoice per active contract — locks rate card + FX snapshot, sums period usage. The invoice records pricing-currency subtotal, CNY collection amount, platform fee, net settlement. Admins can manually trigger for testing.
6. CNY collection
Call:
POST /api/v1/invoices/{invoiceId}/checkout
Authorization: Bearer bm_sandbox_...
Content-Type: application/json
{ "channel": "wechat" }Returns a payment order ID and the payload to render WeChat / Alipay QR. After payment, the channel calls back to /api/webhooks/wechat or /api/webhooks/alipay; we verify the signature, mark invoice paid, and post to the append-only ledger.
7. Settlement payout
Each calendar month, finance closes a settlement batch per settlement currency. Two-admin approval required. Approval triggers an FX-cleared ledger transaction and produces a payout CSV. Net amount wired to your bank within 5 business days.
8. Subscribe to webhooks
Register a webhook URL in settings, subscribe to invoice.paid / invoice.refunded / payout.completed events. Full signature verification example in Webhooks docs.
9. SDK (roadmap)
npm install @buffmoney/sdk # coming soon
import BuffMoneyClient from "@buffmoney/sdk";
const client = new BuffMoneyClient({ apiKey: process.env.BUFFMONEY_API_KEY! });
await client.usageEvents.ingest([{ /* ... */ }]);SDK in development. Calling the REST API via fetch is the supported path today.
10. Machine-readable spec
The OpenAPI 3.1 JSON is served at /api/openapi. Use it to generate clients in any language.