# Create token

URL: https://docs.hanzo.ai/docs/openapi/billing/post-billing-topup-token

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

`POST /v1/billing/topup/token`

> [Billing →](https://docs.hanzo.ai/docs/openapi/billing) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                               |
| ------------- | --------------------------------------------- |
| **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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo billing topup token
```

**SDK**

**.ts**

```ts
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>" });
```

**.py**

```python
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>")
```

**.go**

```go
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
}
```

**.rs**

```rust
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?;
```

**.java**

```java
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();
```

**HTTP**

```bash
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**

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:

```bash
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](https://docs.hanzo.ai/docs/openapi/billing) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)