> ## 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 recharge de crédits

> Recharge de votre solde Didit via checkout Stripe : de 50 $ à 20 000 $ à valeur faciale, forfaits Free, Growth et Scale. Valable 12 mois.



Prompt pour recharger des crédits
        Copier le prompt dans le presse-papiers



      
      

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



      
      

Coller dans



## OpenAPI

````yaml fr/openapi-25.json POST /v3/billing/top-up/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/billing/top-up/:
    post:
      tags:
        - Billing
      summary: Recharger des crédits
      description: >-
        Ajoutez des crédits via une session Stripe Checkout hébergée (**\$50 à
        \$20,000** par recharge). Les recharges sont disponibles pour les
        forfaits Free, Growth et Scale, ajoutées à leur valeur nominale sans
        réduction ni bonus, et sont valables 12 mois ; les contrats annuels
        Enterprise ne peuvent pas effectuer de recharge. Redirigez le client
        vers la `checkout_session_url` retournée.
      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: >-
                    Montant à débiter, en USD. **Doit être compris entre 50 et
                    20,000.** Le solde reçoit le même montant, sans réduction ni
                    bonus. La taxe est ajoutée automatiquement lors du paiement
                    en fonction de l'adresse de facturation du client.
                success_url:
                  type: string
                  format: uri
                  description: "URL vers laquelle le paiement hébergé redirige le client après un paiement réussi. Actuellement défini par défaut sur `https://console.didit.me`. Transmettez explicitement une URL fonctionnelle\_; l'hôte par défaut n'est pas disponible. Ajoutez l'espace réservé textuel `{CHECKOUT_SESSION_ID}` si vous souhaitez que le paiement hébergé remplace l'identifiant de session."
                cancel_url:
                  type: string
                  format: uri
                  description: "URL vers laquelle le paiement hébergé redirige le client lorsqu'il abandonne ou ferme la fenêtre Checkout. Actuellement défini par défaut sur `https://console.didit.me`. Transmettez explicitement une URL fonctionnelle\_; l'hôte par défaut n'est pas 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: >-
            Session de paiement hébergée créée. Redirigez l'utilisateur vers
            `checkout_session_url` pour finaliser le paiement.
          content:
            application/json:
              schema:
                type: object
                required:
                  - checkout_session_id
                  - checkout_session_url
                properties:
                  checkout_session_id:
                    type: string
                    description: >-
                      Identifiant de la session de paiement hébergée (par
                      exemple `cs_test_a1B2c3...`). Utile pour la réconciliation
                      côté serveur.
                  checkout_session_url:
                    type: string
                    format: uri
                    description: >-
                      URL à usage unique d'une page de paiement hébergée.
                      Redirigez le client ici pour effectuer le paiement.
              examples:
                Created:
                  value:
                    checkout_session_id: cs_test_a1B2c3D4e5F6g7H8i9J0
                    checkout_session_url: >-
                      https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0
        '400':
          description: >-
            Payload non valide : le montant est manquant, n'est pas un nombre,
            est inférieur au minimum de \$50 ou supérieur au maximum de
            \$20,000, ou l'organisation est sous contrat annuel Enterprise. Le
            corps de l'erreur est un tableau 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: >-
            Clé API manquante, invalide ou révoquée, ou la clé ne peut pas créer
            de sessions de recharge pour cette organisation. Une clé manquante
            renvoie `403` ; une clé erronée, révoquée ou expirée renvoie `401`.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            Limite de débit dépassée ; réduisez la cadence et réessayez après
            l'intervalle indiqué dans `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 clé API de votre application, issue de Développeurs -> Clés API dans
        la Business Console. La clé principale dispose d'un accès complet. Une
        clé nommée peut être restreinte : aucun, lecture ou écriture par
        ressource, limitée à certains workflows ou aux sessions approuvées, à
        une liste d'adresses IP et à une date d'expiration. 401 signifie que la
        clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a
        été envoyée, que la clé n'a pas accès à cette ressource ou action, ou
        que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur
        une route de session signifie que la session est hors des workflows ou
        des statuts de la clé. Une clé sans accès aux médias reçoit les URL
        d'images, de vidéos et de PDF à null, et une clé sans accès en écriture
        aux sessions reçoit les liens et tokens de session à null. Voir
        https://docs.didit.me/console/api-keys.

````

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