Base URL
https://www.buffmoney.com
Authentication
All endpoints require a Bearer token. Create an API key at /merchant/developer; place the token in the Authorization header:
Authorization: Bearer bm_<env>_<keyId>.<secret>
env is sandbox or live. Sandbox keys work right after signup; live keys unlock after KYB approval.
Endpoints
/api/v1/customersCreate or update customers
Upsert end-customers from your backend before sending usage events. This is the production path for customer sync; the dashboard form is intended for sandbox tests and one-off corrections.
/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.
Parameters
| Field | in | Type | Notes |
|---|---|---|---|
Idempotency-Key optional | header | string | Optional. Caches the full HTTP response for 24h so duplicate requests with the same body produce the same response. |
Responses
| 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 |
/api/v1/invoices/{invoiceId}/checkoutCreate or reuse a payment order for an invoice
Parameters
| Field | in | Type | Notes |
|---|---|---|---|
invoiceId required | path | string | — |
Request body
optional application/json
(inline)
object| Field | Type | Notes |
|---|---|---|
channel optional | "wechat" | "alipay" | — |
Object schemas
UsageEventInput
object| Field | Type | Notes |
|---|---|---|
customerExternalId required | string | The merchant's own customer identifier. |
idempotencyKey required | string | Per-event idempotency key, unique within the merchant. |
metric required | "tokens_input" | "tokens_output" | "image_generation" | "agent_run" | "storage_gb" | — |
quantity required | string | Non-negative integer encoded as a decimal string. |
occurredAt required | string (date-time) | — |
dimensions optional | object | — |
CustomerUpsertInput
object| Field | Type | Notes |
|---|---|---|
externalId required | string | The merchant's own stable customer identifier. |
customerExternalId optional | string | Alias for externalId. |
name optional | string | Optional display name. Defaults to externalId when omitted. |
email optional | string (email) | — |
status optional | "active" | "paused" | "closed" | — |
CustomerUpsertBatch
object| Field | Type | Notes |
|---|---|---|
customers optional | array<CustomerUpsertInput> | — |
UsageEventBatch
object| Field | Type | Notes |
|---|---|---|
events required | array<UsageEventInput> | — |
UsageEventResult
object| Field | Type | Notes |
|---|---|---|
idempotencyKey optional | string | — |
status optional | "accepted" | "duplicate" | "rejected" | — |
eventId optional | string | — |
reason optional | string | — |
Invoice
object| Field | Type | Notes |
|---|---|---|
_id optional | string | — |
invoiceNumber optional | string | — |
status optional | "draft" | "finalized" | "payment_pending" | "paid" | "void" | "refunded" | — |
pricingCurrency optional | string | — |
collectionCurrency optional | string | — |
settlementCurrency optional | string | — |
subtotalMinor optional | string | — |
collectionAmountMinor optional | string | — |
platformFeeMinor optional | string | — |
netSettlementMinor optional | string | — |
periodStart optional | string (date-time) | — |
periodEnd optional | string (date-time) | — |
CheckoutResponse
object| Field | Type | Notes |
|---|---|---|
paymentOrderId optional | string | — |
channel optional | "wechat" | "alipay" | — |
status optional | string | — |
amountMinor optional | string | — |
currency optional | string | — |
expiresAt optional | string (date-time) | — |
checkout optional | object | — |
Error
object| Field | Type | Notes |
|---|---|---|
ok optional | boolean | — |
error optional | string | — |
message optional | string | — |