> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建充值结账会话

> 生成一个托管结账链接，为你的个人余额或团队共享的信用额度池添加信用额度。

为调用方的个人余额或组织的共享团队计费池充值。返回一个托管结账链接，
你的应用可以在新标签页中打开该链接，或将用户重定向到该链接。

## 认证

需要具有 `billing` 权限范围的 Bearer 令牌。参见
[认证](/api-reference/authentication)。

## 请求体

<ParamField body="amount_cents" type="integer" required>
  要添加的金额，单位为美分。最低 `500`（$5.00），最高 `100000`（$1,000.00）。
</ParamField>

<ParamField body="scope" type="string">
  `"user"`（个人场景下的默认值）或 `"org"`（当调用方位于某个团队内且拥有
  `manageBilling` 权限时的默认值）。当取值为 `"org"` 时，充值将计入该团队在
  `organizations.polar_customer_id` 上的共享信用额度池，此后所有团队范围内的
  API 用量都将从该额度池中扣除，直至耗尽。
</ParamField>

<ParamField body="success_url" type="string">
  可选。结账成功后将用户重定向到的 URL。默认值为
  `/dashboard/billing?topup=success`（当 `scope: "org"` 时为
  `/dashboard/billing?topup=success&scope=team`）。
</ParamField>

## 示例：个人充值

```bash curl theme={null}
curl -X POST "https://api.hitheo.ai/api/v1/billing/checkout" \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 2500 }'
```

## 示例：团队充值

```bash curl theme={null}
curl -X POST "https://api.hitheo.ai/api/v1/billing/checkout" \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 10000, "scope": "org" }'
```

```typescript SDK theme={null}
// 为团队额度池充值。拥有 `manageBilling` 权限的管理员可以调用此接口；
// 其他权限范围的调用将返回 403。
const { checkout_url } = await theo.billingCheckout({
  amount_cents: 10_000,
  scope: "org",
});
window.open(checkout_url, "_blank");
```

## 响应

```json theme={null}
{
  "checkout_url": "https://checkout.hitheo.ai/...",
  "scope": "org"
}
```

## 错误

| 状态码 | 错误码 | 含义 |
| - | - | - |
| 400 | `missing_amount` | 缺少 `amount_cents` 或其值不是整数。 |
| 400 | `amount_too_low` | 低于 \$5.00 的最低限额。 |
| 400 | `amount_too_high` | 超过 \$1,000.00 的最高限额。 |
| 400 | `org_context_required` | 请求了 `scope: "org"`，但当前没有活跃的团队。 |
| 402 | `team_payment_method_required` | 团队尚未完成计费充值，暂时无法创建团队密钥。请在完成一次结账后重试。 |
| 403 | `permission_denied` | 调用方在当前活跃团队中不具备 `manageBilling` 权限。 |
| 503 | `billing_unavailable` | 此部署环境尚未配置计费功能。 |

## 生命周期

1. 客户端调用此端点，传入 `amount_cents` 及可选的 `scope`。
2. 计费服务确定正确的客户对象（个人或团队），创建结账会话，并返回
   `checkout_url`。
3. 用户完成结账。
4. 后台 webhook 将此次充值路由到正确的信用额度池（个人或团队），
   并将该客户标记为已绑定支付方式。
5. 后续的 API 用量将从已充值的额度池中扣除。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.