1. 注册并通过审核
在 /signup 注册——立即进入沙箱后台。沙箱模式可调全部 API + 后台页。准备好走真实 CNY 收款时，在 /merchant/activate 提交 KYB（公司证件、法人 ID、银行证明）+ 启用 2FA。ePayments 审核 1-3 个工作日。
2. 创建 API key
在 /merchant/developer 创建 key。建议先 sandbox 测通，再开 live。Scopes: usage:write（上报事件）、invoice:read（查账单）、checkout:write（生成收银台 URL）。
BUFFMONEY_API_KEY=bm_sandbox_AbCd1234.efGH56789longSecret
3. 定义产品、价格表、客户、合同
在后台 4 个独立页完成，也可以通过 API：
/merchant/products— 定义产品（如 chat_api）+ 发布 rate card。价格 minor 单位计。/merchant/customers— 为每个终端用户创建一行，用自己的 externalId 引用。/merchant/contracts— 把客户绑到 rate card 上，设置账期（monthly_calendar 等）。
4. 上报 usage events
每次计量动作 POST 一条事件——按 token / 调用 / 图片 / 存储 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" }
}
]
}事件级 idempotencyKey 在商户内去重。HTTP 头 Idempotency-Key 缓存整条响应 24h，重试安全。完整字段在 API reference。
5. 生成账单
月度 cron 按 active 合同自动生成账单——锁定 rate card + FX snapshot 汇总周期用量。账单上记录标价币种小计、CNY 收款额、平台费、净结算。测试阶段管理员可手动触发。
6. CNY 收款
调用：
POST /api/v1/invoices/{invoiceId}/checkout
Authorization: Bearer bm_sandbox_...
Content-Type: application/json
{ "channel": "wechat" }返回 payment order ID + 渲染 WeChat / Alipay QR 所需的 payload。消费者付款后，渠道回调到 /api/webhooks/wechat 或 /api/webhooks/alipay；我们校验签名、标账单已付、写入 append-only ledger。
7. 结算到账
每个自然月，财务按结算币种关闭一批结算 batch，需两位管理员审批。审批触发 FX 清算 ledger 分录 + 生成 CSV 出款文件。净额 5 个工作日内电汇到你的银行账户。
8. 订阅 Webhooks
在商户设置里注册 webhook URL，订阅 invoice.paid / invoice.refunded / payout.completed 等事件。 完整签名校验示例见 Webhooks 文档。
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 正在开发中。当前用 fetch 直接调 REST API 是受支持的路径。
10. 机器可读 spec
OpenAPI 3.1 JSON 在 /api/openapi 提供。可生成任意语言的客户端。