API reference · BuffMoney Docs

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

POST/api/v1/usage-events

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

Request body

required application/json

See schema: UsageEventBatch

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`

POST/api/v1/invoices/{invoiceId}/checkout

Create 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"`	—

Responses

Status	Description	Body
`200`	Payment order created or reused.	`CheckoutResponse`
`401`	Authentication failure.	`Error`
`403`	Invoice belongs to a different merchant.	`Error`
`404`	Invoice not found.	`Error`
`409`	Invoice already paid / void / refunded.	`Error`
`501`	Channel not yet supported.	`Error`

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`	—

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`	—