API reference · Billing
Start a top-up: returns a payment with the checkout URL to send the customer to
/v1/orgs/{org_id}/billing/top-upsCredit is added only when the payment processor confirms the payment (webhook), never by the return page. With the development driver, credit is added at once and the payment is marked development.
Console session only: no API key can be granted the billing:manage permission it needs. Requires the billing:manage permission (a key's scope, or a role that includes it).
Request
| Header | Required | Description |
|---|---|---|
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Path parameters
org_idstringYour organization. The SDKs and the CLI fill it in from the API key.
ID with prefix org_
Body
JSON (application/json): CreateTopUpRequest.
amountstringrequiredCredit to buy, nano-USD; a whole number of cents
pattern ^[1-9][0-9]{0,18}$
save_payment_methodbooleanSave the card for auto-recharge
Response
201 Payment — The payment
objectstringrequiredAlways `payment`: the type of this object
One of
paymentidstringrequiredUnique ID (`pay_…`)
ID with prefix pay_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
driverstringrequired`development` payments are test credit granted without taking money
One of
stripedevelopmentdevelopmentbooleanrequiredTrue for test credit granted without taking money
purposestringrequired`top_up` (started by you) or `auto_recharge` (charged automatically)
One of
top_upauto_rechargestatusstringrequired`pending` (waiting for payment), `requires_action` (the card holder must authenticate), `succeeded` (credit added), `failed`, `canceled`, or `needs_review` (the amount received did not match; held for review, no credit added yet)
One of
pendingrequires_actionsucceededfailedcanceledneeds_reviewamountstringrequiredCredit added (excludes tax)
pattern ^-?[0-9]+$
taxstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
refundedstringrequiredAmount refunded to the card (credit and tax)
pattern ^-?[0-9]+$
currencystringrequiredAlways `usd`
One of
usdcheckout_urlstring | nullrequiredWhere to send the customer to pay (pending top-ups)
receipt_urlstring | nullrequiredReceipt from the payment processor; null until one exists
cardobject | nullrequiredThe card charged; null until it is known
ShowHide 2 fields of
cardbrandstring | nullrequiredCard brand, for example `visa`; null when unknown
last4string | nullrequiredLast four digits of the card; null when unknown
three_d_secureobjectrequiredCard authentication (3-D Secure) for this payment
ShowHide 2 fields of
three_d_securerequestedbooleanrequiredWhether card authentication (3-D Secure) was asked for
resultstring | nullrequiredOutcome of card authentication as reported by the payment processor; null when none took place
failure_codestring | nullrequiredMachine-readable reason the payment did not succeed or needs review; null otherwise
failure_messagestring | nullrequiredThe same reason, for people; null otherwise
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
succeeded_atstring (date-time) | nullrequiredTime succeeded (ISO 8601, UTC)
Example response
{
"object": "payment",
"id": "pay_01jc5zq4m8k3v6x9t2w7r0b1e4",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"driver": "stripe",
"development": true,
"purpose": "top_up",
"status": "pending",
"amount": "1500000000",
"tax": "1500000000",
"refunded": "1500000000",
"currency": "usd",
"checkout_url": "string",
"receipt_url": "string",
"card": {
"brand": "string",
"last4": "string"
},
"three_d_secure": {
"requested": true,
"result": "string"
},
"failure_code": "string",
"failure_message": "string",
"created_at": "2026-01-01T00:00:00.000Z",
"succeeded_at": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |