Hanzo AI
OpenapiBilling

Create topup

Charges a card the caller already saved and credits the balance.

POST /v1/billing/topup

Addresshttps://api.hanzo.ai/v1/billing/topup
MethodPOST
Operationpost_billing_topup
AuthAuthorization: Bearer $HANZO_API_KEY

Charges a card the caller already saved and credits the balance. Same receipt and the same retry safety as the token endpoint; the only difference is which card, so a caller topping up from a saved method never re-enters one.

Request

5 fields, body application/json (required).

FieldInTypeRequiredDescription
X-Idempotency-Keyheaderstring
amountCentsbodyintegerAmountCents is how much to charge, in cents of Currency.
currencybodystringCurrency is the ISO-4217 code to charge in.
paymentMethodIdbodystringMethodID names a card the subject already saved, for the saved-card endpoint.
sourceIdbodystringSourceID is a single-use card token from the payment form, for the token endpoint.

Response

StatusBodyMeaning
200Chargedok

200 body — 5 fields.

FieldInTypeAlwaysDescription
balanceCentsbodyintegerBalanceCents is the subject's balance AFTER the charge settled, in cents, so a caller does not have to re-read to show the new number.
processorRefbodystringProcessorRef is the payment processor's own reference.
statusbodystringStatus is how the charge ended. Read it rather than inferring success from the HTTP status: the call succeeded whenever this field is present, and what the…
testbodybooleanTest states which bucket was credited — sandbox money or real money — so no reader has to guess whether a receipt is real.
transactionIdbodystringTransactionID is the ledger entry this charge created.

Failure carries the platform error shape — see Errors.

Examples

hanzo billing topup create

Billing API · All Hanzo APIs · Interactive reference

How is this guide?

On this page