基础 URL
https://www.buffmoney.com
认证
所有 endpoint 都需要 Bearer token 认证。在 /merchant/developer 创建 API key 后，token 格式如下，放进 Authorization 头：
Authorization: Bearer bm_<env>_<keyId>.<secret>
env 是 sandbox 或 live。沙箱 key 注册后立即可用；生产 key 需 KYB 审核通过。
Endpoints
POST
/api/v1/usage-eventsIngest usage events
Batch up to 500 usage events at a time. Events are deduped by `(merchantId, idempotencyKey)`. The optional `Idempotency-Key` request header (different from per-event idempotency) caches the whole-response for 24h so retries replay safely.
参数
| 字段 | 位于 | 类型 | 说明 |
|---|---|---|---|
Idempotency-Key 可选 | header | string | Optional. Caches the full HTTP response for 24h so duplicate requests with the same body produce the same response. |
响应
| Status | Description | Body |
|---|---|---|
200 | Batch processed (mixed accept / duplicate / reject possible). | — |
401 | Missing or invalid API key. | Error |
403 | Scope or merchant status check failed. | Error |
409 | Idempotency replay with a different body. | Error |
413 | Batch exceeds 500 events. | Error |
422 | Validation failure or all events rejected. | Error |
POST
/api/v1/invoices/{invoiceId}/checkoutCreate or reuse a payment order for an invoice
参数
| 字段 | 位于 | 类型 | 说明 |
|---|---|---|---|
invoiceId 必填 | path | string | — |
请求体
可选 application/json
(inline)
object| 字段 | 类型 | 说明 |
|---|---|---|
channel 可选 | "wechat" | "alipay" | — |
对象 Schema
UsageEventInput
object| 字段 | 类型 | 说明 |
|---|---|---|
customerExternalId 必填 | string | The merchant's own customer identifier. |
idempotencyKey 必填 | string | Per-event idempotency key, unique within the merchant. |
metric 必填 | "tokens_input" | "tokens_output" | "image_generation" | "agent_run" | "storage_gb" | — |
quantity 必填 | string | Non-negative integer encoded as a decimal string. |
occurredAt 必填 | string (date-time) | — |
dimensions 可选 | object | — |
UsageEventBatch
object| 字段 | 类型 | 说明 |
|---|---|---|
events 必填 | array<UsageEventInput> | — |
UsageEventResult
object| 字段 | 类型 | 说明 |
|---|---|---|
idempotencyKey 可选 | string | — |
status 可选 | "accepted" | "duplicate" | "rejected" | — |
eventId 可选 | string | — |
reason 可选 | string | — |
Invoice
object| 字段 | 类型 | 说明 |
|---|---|---|
_id 可选 | string | — |
invoiceNumber 可选 | string | — |
status 可选 | "draft" | "finalized" | "payment_pending" | "paid" | "void" | "refunded" | — |
pricingCurrency 可选 | string | — |
collectionCurrency 可选 | string | — |
settlementCurrency 可选 | string | — |
subtotalMinor 可选 | string | — |
collectionAmountMinor 可选 | string | — |
platformFeeMinor 可选 | string | — |
netSettlementMinor 可选 | string | — |
periodStart 可选 | string (date-time) | — |
periodEnd 可选 | string (date-time) | — |
CheckoutResponse
object| 字段 | 类型 | 说明 |
|---|---|---|
paymentOrderId 可选 | string | — |
channel 可选 | "wechat" | "alipay" | — |
status 可选 | string | — |
amountMinor 可选 | string | — |
currency 可选 | string | — |
expiresAt 可选 | string (date-time) | — |
checkout 可选 | object | — |
Error
object| 字段 | 类型 | 说明 |
|---|---|---|
ok 可选 | boolean | — |
error 可选 | string | — |
message 可选 | string | — |