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

# استعلام الرصيد: واجهة برمجة الفوترة لـ KYC

> استرجع رصيدك في Didit وإعدادات الشحن التلقائي للرصيد. رصيد واحد يغطي كل منتج، سواء من رصيد الخطة أو من عمليات شحن الرصيد.



موجّه الحصول على الرصيد
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\`Goal: Read the organization's current pre-paid credit balance (USD) plus its auto-refill configuration.

Endpoint: GET https://verification.didit.me/v3/billing/balance/
Auth header: x-api-key: <DIDIT_API_KEY>

curl:
curl -X GET 'https://verification.didit.me/v3/billing/balance/' \
-H 'x-api-key: YOUR_API_KEY'

Response 200:
\{
"balance": "1234.5600",                  // USD, FIXED-POINT DECIMAL STRING — parse with Decimal/BigDecimal, not float.
"auto_refill_enabled": true,             // boolean
"auto_refill_amount": "500.00",          // USD string or null
"auto_refill_threshold": "100.00"        // USD string or null — auto-refill fires when balance falls below this
}

Notes:
\- Balance is ORGANIZATION-WIDE — shared across every application under the same org.
\- Decreases as verifications are billed; increases when a top-up settles via Stripe webhook.
\- Currency is always USD.
\- Configure auto-refill in Console → Billing; requires a saved Stripe payment method (card, SEPA, or US ACH). The auto-refill amount is $50 to $20,000, added at face value, the same range as a manual top-up.
\- Poll at a low cadence (every few minutes max) — balance only changes when usage is billed or a top-up settles.

Common patterns:
\- Gate session creation in production — stop opening new sessions if balance drops below your operational floor.
\- Power internal dashboards / low-balance alerts.
\- Detect misconfigured auto-refill: auto_refill_enabled=true with null auto_refill_amount/threshold means it's effectively off (or no eligible payment method on file).

Failure modes (envelope {"detail": "..."}):
\- 401 — missing/malformed x-api-key.
\- 403 — key valid but bound application not allowed to read billing.
\- 429 — rate-limited.

See /getting-started/pricing for the credit consumption model and POST /v3/billing/top-up/ to add funds programmatically.

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

\</pre>



      
      

الصق في



## OpenAPI

````yaml ar/openapi-25.json GET /v3/billing/balance/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/billing/balance/:
    get:
      tags:
        - Billing
      summary: الحصول على الرصيد
      description: >-
        الحصول على الرصيد المدفوع مسبقاً الحالي بالدولار الأمريكي (على مستوى
        المؤسسة) بالإضافة إلى إعدادات إعادة الشحن التلقائي. المبالغ عبارة عن
        سلاسل نصية عشرية — حلّلها باستخدام مكتبة للأعداد العشرية.
      operationId: get_billing_balance
      responses:
        '200':
          description: >-
            رصيد الائتمان الحالي بالإضافة إلى إعدادات إعادة التعبئة التلقائية
            للمؤسسة.
          content:
            application/json:
              schema:
                type: object
                required:
                  - balance
                  - auto_refill_enabled
                properties:
                  balance:
                    type: string
                    description: >-
                      الرصيد الائتماني مسبق الدفع الحالي بالدولار الأمريكي،
                      كسلسلة نصية عشرية بنقطة ثابتة. يتناقص مع فوترة عمليات
                      التحقق ويزداد عند تسوية شحن الرصيد.
                  auto_refill_enabled:
                    type: boolean
                    description: >-
                      عندما تكون `true`، ستقوم Didit تلقائياً بالخصم من طريقة
                      الدفع المحفوظة لإضافة رصيد بمجرد أن يتجاوز الرصيد
                      `auto_refill_threshold`. يتم تكوينه من Console ← الفوترة.
                  auto_refill_amount:
                    type: string
                    nullable: true
                    description: >-
                      المبلغ بالدولار الأمريكي الذي سيتم تحصيله وإضافته إلى
                      الرصيد عند كل شحن تلقائي، بقيمته الاسمية. يُعيَّن من \$50
                      إلى \$20,000 في Console → الفوترة. تكون القيمة `null` عند
                      تعطيل الشحن التلقائي أو عدم تعيينه.
                  auto_refill_threshold:
                    type: string
                    nullable: true
                    description: >-
                      حد التشغيل بالدولار الأمريكي (USD). يتم تشغيل إعادة
                      التعبئة التلقائية عندما ينخفض `balance` عن هذه القيمة.
                      تكون القيمة `null` عند تعطيل إعادة التعبئة التلقائية أو
                      عدم تعيينها.
              examples:
                Healthy balance with auto-refill:
                  value:
                    balance: '1234.5600'
                    auto_refill_enabled: true
                    auto_refill_amount: '500.00'
                    auto_refill_threshold: '100.00'
                Low balance, manual top-up only:
                  value:
                    balance: '12.0000'
                    auto_refill_enabled: false
                    auto_refill_amount: null
                    auto_refill_threshold: null
        '403':
          description: >-
            مفتاح API مفقود أو غير صالح أو ملغى، أو لا يمكن للمفتاح قراءة بيانات
            الفوترة لهذه المؤسسة. يعيد المفتاح المفقود `403`؛ بينما يعيد المفتاح
            الخاطئ أو الملغى أو منتهي الصلاحية `401`.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            تم تجاوز حد المعدل؛ تراجع مؤقتاً وأعد المحاولة بعد الفاصل الزمني
            الموضح في `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 GET 'https://verification.didit.me/v3/billing/balance/' \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.billing.retrieve_balance()
            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.retrieveBalance();
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.RetrieveBalance(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;

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

            var result = client.billing().retrieveBalance();
            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->retrieveBalance();
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.billing.retrieve_balance
            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.RetrieveBalanceAsync();
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console.
        يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
        شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
        المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
        المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
        إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
        الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
        404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
        بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
        للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك
        إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع
        https://docs.didit.me/console/api-keys.

````

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