Create token

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

POST /v1/billing/topup/token

Billing → · All API references → · Get started →

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 (int64)	—	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`	billing.Charged	ok
`default`	problem-details	refused

200 body — 5 fields.

Field	In	Type	Always	Description
`balanceCents`	body	integer (int64)	—	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.
`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

CLI

SDK

HTTP

MCP

hanzo billing topup token

.ts

.py

.go

.rs

.java

import { 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 := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.BillingAPI.PostBillingTopupToken(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::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.setBearerToken(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 39 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": "list_billing_accounts"
         }
       }
     }'

Billing API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate card NextCreate topup