> ## 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 carregamento de saldo

> Crie um checkout Stripe para carregar saldo na Didit: $50 a $20,000 ao valor nominal, nos planos Free, Growth e Scale. Validade de 12 meses.



Instruções para carregar saldo
        Copiar o prompt para a área de transferência



      
      

\<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>



      
      

Colar em



## OpenAPI

````yaml pt/openapi-25.json POST /v3/billing/top-up/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/billing/top-up/:
    post:
      tags:
        - Billing
      summary: Carregar saldo de créditos
      description: >-
        Adicione créditos através de uma sessão Stripe Checkout alojada (**\$50
        a \$20,000** por carregamento de saldo). Os carregamentos de saldo estão
        disponíveis nos planos Free, Growth e Scale, são adicionados pelo valor
        nominal sem desconto ou bónus, e duram 12 meses; os contratos anuais
        Enterprise não podem carregar saldo. Redirecione o cliente para o
        `checkout_session_url` devolvido.
      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: >-
                    Montante a cobrar, em USD. **Deve ser entre 50 e 20 000.** O
                    saldo recebe o mesmo montante, sem desconto nem bónus. O
                    imposto é adicionado automaticamente no processo de
                    pagamento com base na morada de faturação do cliente.
                success_url:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o checkout alojado redireciona o cliente após
                    um pagamento bem-sucedido. Atualmente o valor predefinido é
                    `https://console.didit.me`. Indique explicitamente um URL
                    funcional; o anfitrião predefinido não está disponível.
                    Anexe o marcador de posição literal `{CHECKOUT_SESSION_ID}`
                    se pretender que o checkout alojado substitua o ID da
                    sessão.
                cancel_url:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o checkout alojado redireciona o cliente
                    quando este cancela ou fecha a janela do Checkout.
                    Atualmente o valor predefinido é `https://console.didit.me`.
                    Indique explicitamente um URL funcional; o anfitrião
                    predefinido não está disponível.
            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: >-
            Sessão de checkout alojada criada. Redirecione o utilizador para
            `checkout_session_url` para concluir o pagamento.
          content:
            application/json:
              schema:
                type: object
                required:
                  - checkout_session_id
                  - checkout_session_url
                properties:
                  checkout_session_id:
                    type: string
                    description: >-
                      Identificador da sessão de checkout alojada (ex.:
                      `cs_test_a1B2c3...`). Útil para reconciliação do lado do
                      servidor.
                  checkout_session_url:
                    type: string
                    format: uri
                    description: >-
                      URL de página de pagamento alojada de utilização única.
                      Redirecione o cliente para esta página para concluir o
                      pagamento.
              examples:
                Created:
                  value:
                    checkout_session_id: cs_test_a1B2c3D4e5F6g7H8i9J0
                    checkout_session_url: >-
                      https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0
        '400':
          description: >-
            Payload inválido: o montante está em falta, não é um número, está
            abaixo do mínimo de \$50 ou acima do máximo de \$20,000, ou a
            organização tem um contrato anual Enterprise. O corpo do erro é uma
            matriz 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: >-
            Chave de API em falta, inválida ou revogada, ou a chave não pode
            criar sessões de carregamento de saldo para esta organização. Uma
            chave em falta devolve `403`; uma chave incorreta, revogada ou
            expirada devolve `401`.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            Limite de pedidos excedido; reduza a frequência e tente novamente
            após o intervalo indicado em `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: >-
        A chave de API da sua aplicação, a partir de Programadores -> Chaves de
        API na Business Console. A chave principal tem acesso total. Uma chave
        nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por
        recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de
        endereços IP e a uma data de validade. 401 significa que a chave está
        incorreta, revogada ou expirada; 403 significa que nenhuma chave foi
        enviada, que a chave não tem acesso a este recurso ou ação, ou que o
        pedido veio de um endereço fora da sua lista de IP; 404 numa rota de
        sessão significa que a sessão está fora dos fluxos ou estados da chave.
        Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs
        como nulos, e uma chave sem permissão de escrita em sessões recebe
        ligações de sessão e tokens como nulos. Consulte
        https://docs.didit.me/console/api-keys.

````

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