> ## 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. # واجهة شحن الرصيد > أنشئ جلسة دفع Stripe لإضافة شحن إلى رصيد Didit: من 50$ إلى 20,000$ بالقيمة الاسمية، على خطط Free وGrowth وScale. تبقى الشحنات صالحة لمدة 12 شهرًا. تعليمات شحن الرصيد نسخ الموجّه إلى الحافظة \

\``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: 
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.``

\
الصق في ## OpenAPI ````yaml ar/openapi-25.json POST /v3/billing/top-up/ 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/top-up/: post: tags: - Billing summary: شحن الرصيد description: >- أضف أرصدة عبر جلسة Stripe Checkout مستضافة (**\$50 إلى \$20,000** لكل عملية شحن رصيد). تتوفر عمليات شحن الرصيد في خطط Free وGrowth وScale، وتُضاف بالقيمة الاسمية دون أي خصم أو مكافأة، وتستمر لمدة 12 شهراً؛ ولا يمكن للعقود السنوية في خطة Enterprise شحن الرصيد. أعد توجيه العميل إلى `checkout_session_url` المُرجع. 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: >- المبلغ المراد تحصيله بالدولار الأمريكي. **يجب أن يكون من 50 إلى 20,000.** يتلقى الرصيد نفس المبلغ، دون أي خصم أو مكافأة. تُضاف الضريبة تلقائياً عند الدفع بناءً على عنوان الفوترة الخاص بالعميل. success_url: type: string format: uri description: >- رابط URL الذي تعيد صفحة الدفع المستضافة توجيه العميل إليه بعد نجاح الدفع. القيمة الافتراضية حالياً هي `https://console.didit.me`. مرّر رابط URL صالحاً بشكل صريح؛ فالمضيف الافتراضي غير متاح. ألحق العنصر النائب الحرفي `{CHECKOUT_SESSION_ID}` إذا كنت تريد أن تستبدل صفحة الدفع المستضافة معرّف الجلسة به. cancel_url: type: string format: uri description: >- رابط URL الذي تعيد صفحة الدفع المستضافة توجيه العميل إليه عندما يلغي العميل نافذة الدفع أو يغلقها. القيمة الافتراضية حالياً هي `https://console.didit.me`. مرّر رابط URL صالحاً بشكل صريح؛ فالمضيف الافتراضي غير متاح. 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: >- تم إنشاء جلسة الدفع المستضافة. أعد توجيه المستخدم إلى `checkout_session_url` لإتمام الدفع. content: application/json: schema: type: object required: - checkout_session_id - checkout_session_url properties: checkout_session_id: type: string description: >- معرّف جلسة الدفع المستضافة (مثل `cs_test_a1B2c3...`). مفيد للتسوية من جانب الخادم. checkout_session_url: type: string format: uri description: >- رابط URL لصفحة دفع مستضافة للاستخدام لمرة واحدة. أعد توجيه العميل إلى هنا لإتمام الدفع. examples: Created: value: checkout_session_id: cs_test_a1B2c3D4e5F6g7H8i9J0 checkout_session_url: >- https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0 '400': description: >- payload غير صالح: المبلغ مفقود، أو ليس رقماً، أو أقل من الحد الأدنى \$50 أو أعلى من الحد الأقصى \$20,000، أو أن المؤسسة تعمل بموجب عقد Enterprise سنوي. جسم الخطأ هو مصفوفة 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: >- مفتاح 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 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: |- 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: >- مفتاح 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.