> ## 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.