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

# API de recàrrega de crèdits

> Crea un checkout de Stripe per recarregar el saldo de Didit: de $50 a $20,000 al valor nominal als plans Free, Growth i Scale. Vàlides 12 mesos.



Prompt per recarregar crèdits
        Copia el prompt al porta-retalls



      
      

\<pre>

\``Goal: Start a manual credit top-up by creating a hosted Stripe Checkout session. Once Stripe processes the payment, Didit's invoice.paid webhook handler credits the organization's balance.

Endpoint: POST https://verification.didit.me/v3/billing/top-up/
Auth header: x-api-key: <DIDIT_API_KEY>
Content-Type: application/json

Request body:
\- amount_in_dollars (number, REQUIRED) — USD amount to charge, from $50 MINIMUM to $20,000 MAXIMUM. The balance receives the same amount: no discount or bonus. Tax is added automatically at checkout based on billing address.
\- success_url (URI, optional) — Stripe redirects here after successful payment. Currently defaults to `https://console.didit.me`. Pass a working URL explicitly; the default host is unavailable. Append literal placeholder {CHECKOUT_SESSION_ID} if you want Stripe to substitute the session id.
\- cancel_url (URI, optional) — Stripe redirects here when the customer aborts. Currently defaults to `https://console.didit.me`. Pass a working URL explicitly; the default host is unavailable.

curl:
curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"amount_in_dollars": 500,
"success_url": "https://yourapp.com/billing/success",
"cancel_url": "https://yourapp.com/billing/cancel"
}'

Response 200:
\{
"checkout_session_id": "cs_test_a1B2c3D4e5F6g7H8i9J0",
"checkout_session_url": "https://checkout.stripe.com/c/pay/cs_test_..."
}
Redirect the customer's browser to checkout_session_url (or hand it off to your billing admin out-of-band) to complete payment.

Full flow:
1\. POST /v3/billing/top-up/ with amount_in_dollars and explicit success_url and cancel_url values.
2\. Redirect to checkout_session_url.
3\. Customer pays on Stripe-hosted page.
4\. Stripe redirects to success_url (or cancel_url on abort).
5\. Didit receives invoice.paid webhook, increases organization balance.
6\. Poll GET /v3/billing/balance/ to confirm balance reflects the top-up.

Failure modes:
\- 400 — the body is a JSON array with one message:
\["amount_in_dollars is required."]
\["amount_in_dollars must be a number."]
\["Amount must be at least $50."]
\["Amount must be at most $20,000."]
\["You have an annual plan. Contact your account manager to top up."]  // Enterprise annual-contract orgs cannot top up: usage beyond the contract credit is invoiced as overage.
\- 401 — missing/malformed x-api-key.
\- 403 — key valid but cannot create top-up sessions for this organization.
\- 429 — rate-limited.

Notes:
\- Top-ups are available on the Free, Growth and Scale plans, from $50 to $20,000 each. They are added at face value (pay $20,000, receive $20,000; no discount or bonus), pay for every product, and last 12 months. Each check uses the month's plan credit first, then the oldest top-up.
\- Auto top-up amounts, set in Console → Billing, follow the same $50 to $20,000 range.
\- The Stripe Checkout session is single-use, but calling this endpoint repeatedly creates NEW sessions — track completion on your side via success_url/cancel_url to avoid duplicate charges.
\- When the cardholder pays with card / SEPA / US ACH, Stripe attaches the payment method with setup_future_usage=off_session so Didit can later auto-charge it for auto-refill.
\- The organization must already have a Stripe customer set up (created automatically the first time the org configures billing).

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.``

\</pre>



      
      

Enganxa a



## OpenAPI

````yaml ca/openapi-25.json POST /v3/billing/top-up/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/billing/top-up/:
    post:
      tags:
        - Billing
      summary: Recarregar crèdits
      description: >-
        Afegeix crèdits mitjançant una sessió allotjada de Stripe Checkout
        (**\$50 a \$20,000** per recàrrega). Les recàrregues estan disponibles
        als plans Free, Growth i Scale, s'afegeixen pel seu valor nominal sense
        cap descompte ni bonificació, i duren 12 mesos; els contractes anuals
        Enterprise no poden recarregar. Redirigeix el client a la
        `checkout_session_url` retornada.
      operationId: billing_top_up
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount_in_dollars
              properties:
                amount_in_dollars:
                  type: number
                  minimum: 50
                  maximum: 20000
                  description: >-
                    Import a carregar, en USD. **Ha de ser de 50 a 20.000.** El
                    saldo rep el mateix import, sense descomptes ni
                    bonificacions. Els impostos s'afegeixen automàticament en el
                    pagament segons l'adreça de facturació del client.
                success_url:
                  type: string
                  format: uri
                  description: >-
                    URL a la qual la pantalla de pagament allotjada redirigeix
                    el client després d'un pagament satisfactori. Actualment per
                    defecte és `https://console.didit.me`. Passa una URL
                    funcional explícitament; l'amfitrió per defecte no està
                    disponible. Afegeix el marcador de posició literal
                    `{CHECKOUT_SESSION_ID}` si vols que la pantalla de pagament
                    allotjada substitueixi l'ID de sessió.
                cancel_url:
                  type: string
                  format: uri
                  description: >-
                    URL a la qual la pantalla de pagament allotjada redirigeix
                    el client quan cancel·la o tanca la finestra de pagament.
                    Actualment per defecte és `https://console.didit.me`. Passa
                    una URL funcional explícitament; el host per defecte no està
                    disponible.
            examples:
              Minimum top-up:
                value:
                  amount_in_dollars: 50
              Custom amount with redirects:
                value:
                  amount_in_dollars: 500
                  success_url: https://yourapp.com/billing/top-up/success
                  cancel_url: https://yourapp.com/billing/top-up/cancel
      responses:
        '200':
          description: >-
            Sessió de pagament allotjada creada. Redirigeix l'usuari a
            `checkout_session_url` per completar el pagament.
          content:
            application/json:
              schema:
                type: object
                required:
                  - checkout_session_id
                  - checkout_session_url
                properties:
                  checkout_session_id:
                    type: string
                    description: >-
                      Identificador de la sessió de pagament allotjada (p. ex.
                      `cs_test_a1B2c3...`). Útil per a la conciliació al costat
                      del servidor.
                  checkout_session_url:
                    type: string
                    format: uri
                    description: >-
                      URL de la pàgina de pagament allotjada d'un sol ús.
                      Redirigeix el client aquí per completar el pagament.
              examples:
                Created:
                  value:
                    checkout_session_id: cs_test_a1B2c3D4e5F6g7H8i9J0
                    checkout_session_url: >-
                      https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0
        '400':
          description: >-
            Payload no vàlid: falta l'import, no és un número, està per sota del
            mínim de \$50 o per sobre del màxim de \$20,000, o bé l'organització
            té un contracte anual Enterprise. El cos de l'error és una matriu
            JSON.
          content:
            application/json:
              examples:
                Missing amount:
                  value:
                    - amount_in_dollars is required.
                Not a number:
                  value:
                    - amount_in_dollars must be a number.
                Below minimum:
                  value:
                    - Amount must be at least $50.
                Above maximum:
                  value:
                    - Amount must be at most $20,000.
                Annual plan:
                  value:
                    - >-
                      You have an annual plan. Contact your account manager to
                      top up.
        '403':
          description: >-
            Falta la clau d'API, no és vàlida o està revocada, o la clau no pot
            crear sessions de recàrrega per a aquesta organització. Si falta la
            clau, es retorna `403`; una clau incorrecta, revocada o caducada
            retorna `401`.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            S'ha superat el límit de freqüència; redueix el ritme de les
            sol·licituds i reintenta-ho després de l'interval indicat a
            `Retry-After`.
          content:
            application/json:
              examples:
                Throttled:
                  value:
                    detail: Request was throttled. Expected available in 30 seconds.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "amount_in_dollars": 500,
                "success_url": "https://yourapp.com/billing/success",
                "cancel_url": "https://yourapp.com/billing/cancel"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.billing.top_up(
                amount_in_dollars=50.0,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.billing.topUp({
              amount_in_dollars: 50.0,
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.TopUp(ctx, didit.BillingTopUpParams{\n\tAmountInDollars: 50.0,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.BillingTopUpParams;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.billing().topUp(BillingTopUpParams.builder()
                    .amountInDollars(50.0)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->billing->topUp([
                'amount_in_dollars' => 50.0,
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.billing.top_up(amount_in_dollars: 50.0)
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // Reads DIDIT_API_KEY.
            using var client = new DiditClient();

            var result = await client.Billing.TopUpAsync(new BillingTopUpParams
            {
                AmountInDollars = 50.0,
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.