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

# トップアップを購入する

> 保存されたカードに課金し、クレジットを一度に購入します。チェックアウトのリダイレクトや埋め込み支払いUIはありません。

<Note>
  **`credits` は次のいずれかでなければなりません:** `10000`, `20000`, `80000`, または `100000` — つまり **10K**, **20K**, **80K**, または **100K** クレジットです。
</Note>

ガイド付きの概要については、[残高と請求](/balance-billing/balance-and-billing)を参照してください。


## OpenAPI

````yaml ja/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のリダイレクトや埋め込みの支払いUIはありません。 
        **要件:** - チームは、少なくとも1枚の保存されたカードを持つStripeの顧客である必要があります。 -
        チームごとに**60秒**ごとに1回の購入試行のみが許可されます。  **クレジット発行:**
        支払い確認後、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秒ごとに最大1回の購入が可能です。`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>はあなたの認証トークンです。

````