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

# 余额与账单

> 以编程方式检查你的信用余额并购买充值。

使用用户账单端点读取你的团队信用余额，并使用已保存的支付方式购买充值。两个端点都需要使用你的[API 密钥](/get-started/authentication)进行身份验证。无效的密钥将返回 **402**。

## 检查信用余额

`GET /user/credits/info` 返回经过身份验证的团队的信用余额、每批次的详细信息、活跃订阅详情，以及是否允许使用。

使用此端点为账单小部件、使用仪表板或在运行大型作业前进行预检。

有关 API 详细信息，请参阅[获取信用信息](/api-reference/billing/credits-info)。

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.olostep.com/user/credits/info",
      headers={"Authorization": "Bearer <API-TOKEN>"},
  )
  print(response.json())
  ```

  ```js Node theme={null}
  const res = await fetch("https://api.olostep.com/user/credits/info", {
    headers: { Authorization: "Bearer <API-TOKEN>" },
  })
  console.log(await res.json())
  ```

  ```bash cURL theme={null}
  curl -s "https://api.olostep.com/user/credits/info" \
    -H "Authorization: Bearer <API-TOKEN>"
  ```
</CodeGroup>

### 响应

```json theme={null}
{
  "credits": 12500,
  "breakdown": [
    {
      "purchase_kind": "Subscription",
      "allocated_units": 10000,
      "remaining_units": 8500,
      "expiry_date": 1735689600
    },
    {
      "purchase_kind": "Top-up",
      "allocated_units": 5000,
      "remaining_units": 4000,
      "expiry_date": 1743465600
    }
  ],
  "active_subscription": {
    "id": "SUB_PRO",
    "display_name": "Pro",
    "credits": 10000,
    "created_at": 1704067200
  },
  "allow_usage": true
}
```

| 字段                    | 描述                             |
| --------------------- | ------------------------------ |
| `credits`             | 所有未过期批次的剩余总信用                  |
| `breakdown`           | 每批次详情：类型、分配和剩余单位、到期时间          |
| `active_subscription` | 当前计划（如果没有活跃计划，则回退到 `SUB_BASE`） |
| `allow_usage`         | 团队是否仍然可以使用信用                   |

`breakdown` 中的每个批次都有一个 `purchase_kind`，可以是 `Subscription`、`Top-up`、`Manual`、`Setup` 或 `Pending`。

## 购买充值

`POST /user/purchase-topup` 在 Stripe 上扣费并一步购买信用。没有结账重定向或嵌入式支付 UI。

在请求体中传递信用数量：

```json theme={null}
{ "credits": 10000 }
```

| 字段        | 描述       |
| --------- | -------- |
| `credits` | 要购买的信用数量 |

支持的值：**10,000**、**20,000**、**80,000** 和 **100,000**。

有关 API 详细信息，请参阅[购买充值](/api-reference/billing/purchase-topup)。

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.olostep.com/user/purchase-topup",
      headers={
          "Authorization": "Bearer <API-TOKEN>",
          "Content-Type": "application/json",
      },
      json={"credits": 10000},
  )
  print(response.status_code)
  print(response.json())
  ```

  ```js Node theme={null}
  const res = await fetch("https://api.olostep.com/user/purchase-topup", {
    method: "POST",
    headers: {
      Authorization: "Bearer <API-TOKEN>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ credits: 10000 }),
  })
  console.log(res.status)
  console.log(await res.json())
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer <API-TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"credits": 10000}'
  ```
</CodeGroup>

### 要求

* 团队必须有一个 Stripe 客户，并至少保存了一张卡。
* 每个团队每 **60 秒** 只允许一次购买尝试。如果达到冷却时间，响应为 **429**，并带有 `Retry-After` 头。

### 响应

**200** — 支付成功：

```json theme={null}
{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}
```

**202** — 支付仍在处理中。Stripe 确认付款后将添加信用：

```json theme={null}
{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Payment is processing. Credits will be added once the payment is confirmed.",
  "credits": 10000
}
```

<Note>
  信用是在付款确认后由 Stripe webhook 发放的，而不是直接从 HTTP 响应中发放。将 **200** 视为支付成功；如果需要确认更新的余额，请轮询 `GET /user/credits/info`。
</Note>

### 常见错误

| 状态  | 错误                        | 何时                   |
| --- | ------------------------- | -------------------- |
| 400 | `missing_topup_selector`  | 未发送 `credits`        |
| 400 | `invalid_credits`         | 信用数量不在允许列表中          |
| 400 | `no_stripe_customer`      | 团队没有 Stripe 客户       |
| 400 | `no_payment_method`       | 没有保存的卡               |
| 402 | `payment_failed`          | 没有保存的卡完成扣费           |
| 429 | `purchase_topup_cooldown` | 在 60 秒内尝试了另一次购买      |
| 503 | `payment_status_unknown`  | 模糊的 Stripe 错误；重试前请等待 |