Hanzo AI
OpenapiBilling

Create token

Charges a single-use card token and credits the caller's balance.

POST /v1/billing/topup/token

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

Charges a single-use card token and credits the caller's balance.

The token comes from the payment form and is vaulted as part of the charge, so no card number reaches this service and none is stored here. The receipt names the ledger entry, the new balance, and the PROCESSOR's own reference — which is the only field that proves money moved at the gateway rather than only in our ledger.

Retry-safe on X-Idempotency-Key: the same key settles one charge and returns the first receipt.

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 token

Billing API · All Hanzo APIs · Interactive reference

How is this guide?

On this page