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

# Acquista ricarica

> Addebita una carta salvata e acquista crediti in un solo passaggio. Nessun reindirizzamento a Checkout o interfaccia di pagamento incorporata.

<Note>
  **`credits` deve essere uno dei seguenti:** `10000`, `20000`, `80000`, o `100000` — cioè **10K**, **20K**, **80K**, o **100K** crediti.
</Note>

Per una panoramica guidata, vedi [Saldo e fatturazione](/balance-billing/balance-and-billing).


## OpenAPI

````yaml it/openapi/billing.json POST /user/purchase-topup
openapi: 3.0.3
info:
  title: API Saldo & Fatturazione
  version: 1.0.0
  description: Leggi il saldo dei crediti e acquista ricariche per il team autenticato.
servers:
  - url: https://api.olostep.com
security: []
tags:
  - name: Balance & Billing
    description: Endpoint per saldo crediti e acquisto ricariche.
paths:
  /user/purchase-topup:
    post:
      tags:
        - Balance & Billing
      summary: Acquista ricarica
      description: >-
        Addebita una carta salvata su Stripe e acquista crediti in un solo
        passaggio. Non c'è reindirizzamento a Checkout o interfaccia di
        pagamento incorporata.  **Requisiti:** - Il team deve avere un cliente
        Stripe con almeno una carta salvata. - È consentito solo un tentativo di
        acquisto ogni **60 secondi** per team.  **Emissione dei crediti:** I
        crediti vengono aggiunti dal webhook di Stripe dopo la conferma del
        pagamento. Interroga `GET /user/credits/info` per confermare il saldo
        aggiornato.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTopupRequest'
            example:
              credits: 10000
      responses:
        '200':
          description: Pagamento riuscito.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTopupSuccess'
              example:
                success: true
                payment_intent_id: pi_xxx
                credits: 10000
        '202':
          description: >-
            Pagamento in elaborazione. I crediti vengono aggiunti una volta che
            Stripe conferma il pagamento.
          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: >-
            Richiesta non valida. Errori comuni: `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: >-
            Chiave API non valida, o pagamento fallito su tutte le carte salvate
            (`payment_failed`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: payment_failed
        '404':
          description: Team non trovato (`team_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: team_not_found
        '429':
          description: >-
            Cooldown di acquisto attivo. Al massimo un acquisto ogni 60 secondi
            per team. Include l'intestazione `Retry-After`.
          headers:
            Retry-After:
              schema:
                type: integer
              description: >-
                Secondi fino a quando è consentito un altro tentativo di
                acquisto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: purchase_topup_cooldown
                retry_after: 42
                cooldown_seconds: 60
        '500':
          description: Errore interno del server.
        '503':
          description: >-
            Errore ambiguo di Stripe (`payment_status_unknown`). Attendi prima
            di riprovare.
          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: >-
            Numero di crediti da acquistare. Valori consentiti: **10,000**,
            **20,000**, **80,000**, o **100,000**.
    PurchaseTopupSuccess:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        payment_intent_id:
          type: string
          description: ID Stripe PaymentIntent per l'addebito.
        credits:
          type: integer
          description: Crediti acquistati in questa richiesta.
    PurchaseTopupProcessing:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        status:
          type: string
          enum:
            - processing
        payment_intent_id:
          type: string
        message:
          type: string
          description: >-
            Nota leggibile dall'uomo che i crediti saranno aggiunti una volta
            confermato il pagamento.
        credits:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Codice di errore leggibile dalla macchina.
        retry_after:
          type: integer
          description: >-
            Secondi fino a quando è consentito un altro tentativo di acquisto
            (solo risposte di cooldown).
        cooldown_seconds:
          type: integer
          description: Finestra di cooldown in secondi (solo risposte di cooldown).
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: >-
        Intestazione di autenticazione Bearer del tipo Bearer <token>, dove
        <token> è il tuo token di autenticazione.

````