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

# Guthaben aufladen

> Eine gespeicherte Karte belasten und Guthaben in einem Schritt kaufen. Kein Checkout-Redirect oder eingebettete Zahlungsoberfläche.

<Note>
  **`credits` muss einer der folgenden Werte sein:** `10000`, `20000`, `80000` oder `100000` — also **10K**, **20K**, **80K** oder **100K** Guthaben.
</Note>

Für eine geführte Übersicht, siehe [Saldo & Abrechnung](/balance-billing/balance-and-billing).


## OpenAPI

````yaml de/openapi/billing.json POST /user/purchase-topup
openapi: 3.0.3
info:
  title: Balance & Billing API
  version: 1.0.0
  description: Lese das Guthaben und kaufe Aufladungen für das authentifizierte Team.
servers:
  - url: https://api.olostep.com
security: []
tags:
  - name: Balance & Billing
    description: Endpunkte für Guthaben und Aufladekäufe.
paths:
  /user/purchase-topup:
    post:
      tags:
        - Balance & Billing
      summary: Guthaben aufladen
      description: >-
        Belastet eine gespeicherte Karte auf Stripe und kauft in einem Schritt
        Guthaben. Es gibt keine Checkout-Weiterleitung oder eingebettete
        Zahlungsoberfläche.  **Anforderungen:** - Das Team muss einen
        Stripe-Kunden mit mindestens einer gespeicherten Karte haben. - Pro Team
        ist nur ein Kaufversuch alle **60 Sekunden** erlaubt. 
        **Guthabenausstellung:** Guthaben werden nach Zahlungsbestätigung durch
        den Stripe-Webhook hinzugefügt. Poll `GET /user/credits/info`, um das
        aktualisierte Guthaben zu bestätigen.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTopupRequest'
            example:
              credits: 10000
      responses:
        '200':
          description: Zahlung erfolgreich.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTopupSuccess'
              example:
                success: true
                payment_intent_id: pi_xxx
                credits: 10000
        '202':
          description: >-
            Zahlung wird verarbeitet. Guthaben werden hinzugefügt, sobald Stripe
            die Zahlung bestätigt.
          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: >-
            Ungültige Anfrage. Häufige Fehler: `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: >-
            Ungültiger API-Schlüssel oder Zahlung auf allen gespeicherten Karten
            fehlgeschlagen (`payment_failed`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: payment_failed
        '404':
          description: Team nicht gefunden (`team_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: team_not_found
        '429':
          description: >-
            Kauf-Abkühlung aktiv. Höchstens ein Kauf alle 60 Sekunden pro Team.
            Enthält `Retry-After` Header.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Sekunden bis ein weiterer Kaufversuch erlaubt ist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: purchase_topup_cooldown
                retry_after: 42
                cooldown_seconds: 60
        '500':
          description: Interner Serverfehler.
        '503':
          description: >-
            Mehrdeutiger Stripe-Fehler (`payment_status_unknown`). Warte, bevor
            du es erneut versuchst.
          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: >-
            Anzahl der zu kaufenden Guthaben. Erlaubte Werte: **10,000**,
            **20,000**, **80,000** oder **100,000**.
    PurchaseTopupSuccess:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        payment_intent_id:
          type: string
          description: Stripe PaymentIntent-ID für die Belastung.
        credits:
          type: integer
          description: In dieser Anfrage gekaufte Guthaben.
    PurchaseTopupProcessing:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        status:
          type: string
          enum:
            - processing
        payment_intent_id:
          type: string
        message:
          type: string
          description: >-
            Menschlich lesbare Notiz, dass Guthaben hinzugefügt werden, sobald
            die Zahlung bestätigt ist.
        credits:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Maschinell lesbarer Fehlercode.
        retry_after:
          type: integer
          description: >-
            Sekunden, bis ein weiterer Kaufversuch erlaubt ist (nur bei
            Abkühlungsantworten).
        cooldown_seconds:
          type: integer
          description: Abkühlungszeitfenster in Sekunden (nur für Abkühlungsantworten).
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: >-
        Bearer-Authentifizierungsheader in der Form Bearer <token>, wobei
        <token> dein Authentifizierungstoken ist.

````