Create token
Charges a single-use card token and credits the caller's balance.
POST /v1/billing/topup/token
| Address | https://api.hanzo.ai/v1/billing/topup/token |
| Method | POST |
| Operation | post_billing_topup_token |
| Auth | Authorization: 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).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
X-Idempotency-Key | header | string | — | |
amountCents | body | integer | — | AmountCents is how much to charge, in cents of Currency. |
currency | body | string | — | Currency is the ISO-4217 code to charge in. |
paymentMethodId | body | string | — | MethodID names a card the subject already saved, for the saved-card endpoint. |
sourceId | body | string | — | SourceID is a single-use card token from the payment form, for the token endpoint. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | Charged | ok |
200 body — 5 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
balanceCents | body | integer | — | BalanceCents 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. |
processorRef | body | string | — | ProcessorRef is the payment processor's own reference. |
status | body | string | — | Status 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… |
test | body | boolean | — | Test states which bucket was credited — sandbox money or real money — so no reader has to guess whether a receipt is real. |
transactionId | body | string | — | TransactionID is the ledger entry this charge created. |
Failure carries the platform error shape — see Errors.
Examples
hanzo billing topup tokenimport { Configuration, BillingApi } from 'hanzoai';
const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postBillingTopupToken({ amountCents: 0, currency: "<currency>" });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).post_billing_topup_token(amount_cents=0, currency="<currency>")cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.BillingAPI.PostBillingTopupToken(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, billing_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = billing_api::post_billing_topup_token(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new BillingApi(client).postBillingTopupToken();curl -X POST https://api.hanzo.ai/v1/billing/topup/token \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amountCents": 0,
"currency": "<currency>"
}'MCP reaches billing through the billing tool, which names its 9 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "get_billing_balance"
}
}
}'How is this guide?