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

# 购买充值

> 一步完成保存卡的扣款和购买积分。无需结账重定向或嵌入支付界面。

<Note>
  **`credits` 必须是以下之一：** `10000`、`20000`、`80000` 或 `100000` — 即 **10K**、**20K**、**80K** 或 **100K** 积分。
</Note>

有关指导概述，请参阅[余额与账单](/balance-billing/balance-and-billing)。


## OpenAPI

````yaml zh/openapi/billing.json POST /user/purchase-topup
openapi: 3.0.3
info:
  title: 余额与账单 API
  version: 1.0.0
  description: 读取已认证团队的信用余额并购买充值。
servers:
  - url: https://api.olostep.com
security: []
tags:
  - name: Balance & Billing
    description: 信用余额和充值购买端点。
paths:
  /user/purchase-topup:
    post:
      tags:
        - Balance & Billing
      summary: 购买充值
      description: >-
        在 Stripe 上使用保存的卡片进行扣款并一步购买信用。没有 Checkout 重定向或嵌入式支付界面。  **要求：** - 团队必须有一个
        Stripe 客户，并至少保存了一张卡片。 - 每个团队每 **60 秒** 只允许一次购买尝试。  **信用发放：** 支付确认后，信用通过
        Stripe webhook 添加。轮询 `GET /user/credits/info` 以确认更新的余额。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTopupRequest'
            example:
              credits: 10000
      responses:
        '200':
          description: 支付成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTopupSuccess'
              example:
                success: true
                payment_intent_id: pi_xxx
                credits: 10000
        '202':
          description: 支付处理中。Stripe 确认支付后将添加信用。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTopupProcessing'
              example:
                success: true
                status: processing
                payment_intent_id: pi_xxx
                message: >-
                  Payment is processing. Credits will be added once the payment
                  is confirmed.
                credits: 10000
        '400':
          description: >-
            无效请求。常见错误：`missing_topup_selector`，`invalid_credits`，`no_stripe_customer`，`no_payment_method`，`topup_not_available`。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_topup_selector:
                  value:
                    error: missing_topup_selector
                invalid_credits:
                  value:
                    error: invalid_credits
                no_payment_method:
                  value:
                    error: no_payment_method
        '402':
          description: 无效的 API 密钥，或所有保存的卡片支付失败（`payment_failed`）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: payment_failed
        '404':
          description: 找不到团队（`team_not_found`）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: team_not_found
        '429':
          description: 购买冷却中。每个团队最多每 60 秒一次购买。包含 `Retry-After` 头。
          headers:
            Retry-After:
              schema:
                type: integer
              description: 直到允许再次购买尝试的秒数。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: purchase_topup_cooldown
                retry_after: 42
                cooldown_seconds: 60
        '500':
          description: 内部服务器错误。
        '503':
          description: 模糊的 Stripe 错误（`payment_status_unknown`）。等待后再重试。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: payment_status_unknown
      security:
        - Authorization: []
components:
  schemas:
    PurchaseTopupRequest:
      type: object
      required:
        - credits
      properties:
        credits:
          type: integer
          enum:
            - 10000
            - 20000
            - 80000
            - 100000
          description: 要购买的信用数量。允许的值：**10,000**、**20,000**、**80,000** 或 **100,000**。
    PurchaseTopupSuccess:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        payment_intent_id:
          type: string
          description: 此次收费的 Stripe PaymentIntent id。
        credits:
          type: integer
          description: 此请求中购买的信用。
    PurchaseTopupProcessing:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        status:
          type: string
          enum:
            - processing
        payment_intent_id:
          type: string
        message:
          type: string
          description: 人类可读的备注，信用将在付款确认后添加。
        credits:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: 机器可读的错误代码。
        retry_after:
          type: integer
          description: 允许再次尝试购买的秒数（仅限冷却响应）。
        cooldown_seconds:
          type: integer
          description: 冷却窗口（仅限冷却响应）以秒为单位。
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: Bearer认证头格式为Bearer <token>，其中<token>是你的认证令牌。

````