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

# v1.86.0 (March 2, 2026)

> الفوترة المبنية على الرصيد مع تحكم في الترحيل والزيادات والانتهاء، ومحور موحد للتصميم وتخصيص السمة، وحالة الاسترداد والنزاع في واجهة قائمة المدفوعات، وجدول الاستردادات في بوابة العملاء، وخيار النسخ إلى الوضع الحي للعدادات

## الميزات الجديدة

### 1. **الفوترة المبنية على الرصيد**

تدعم Dodo Payments الآن **الفوترة المبنية على الرصيد**، وهو نظام مرن لإصدار وإدارة وتتبع استحقاقات الرصيد عبر الاشتراكات، والمنتجات ذات الدفع لمرة واحدة، والفوترة المبنية على الاستخدام. بدلاً من فرض رسوم لكل استخدام أو تحديد الوصول عبر أعلام الميزات، يمكنك تخصيص مجموعة من الأرصدة يسحب منها العملاء أثناء استهلاكهم لخدمتك.

<Frame>
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Checkout.png?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=21880df0e4b0b1a3cb8593dbeb8ae343" alt="صفحة الدفع تعرض الرصيد المتضمن مع شراء المنتج" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/CBB/Checkout.png" />
</Frame>

**ما يمكنك فعله**

| القدرة                                   | الوصف                                                                                           |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **وحدات مخصصة أو أرصدة بالعملة الرسمية** | عرّف الأرصدة بوحدتك الخاصة (نداءات API، رموز، ساعات الحوسبة) أو بقيمة عملة فعلية (USD، EUR)     |
| **أرصدة الاشتراك**                       | إصدار أرصدة لكل دورة فوترة مع إعادة الإصدار تلقائياً عند التجديد                                |
| **أرصدة لمرة واحدة**                     | منح رصيد ثابت عند الشراء، مثالية لحزم التعبئة أو باقات الترويج                                  |
| **الخصم المبني على الاستخدام**           | اربط الأرصدة بالعدادات للخصم التلقائي اعتماداً على أحداث الاستهلاك في الوقت الفعلي              |
| **التحويل**                              | السماح بترحيل الأرصدة غير المستخدمة مع حد أقصى نسبي مخصص، والإطار الزمني، وعدد مرات التحويل     |
| **ضوابط الزيادة**                        | اسمح للعملاء بمواصلة استخدام خدمتك بعد نفاد الرصيد، مع خيارات للغفران أو الفوترة أو ترحيل العجز |
| **انتهاء الصلاحية**                      | حدد صلاحية الرصيد من 7 أيام وحتى لا تنتهي، مع عدد أيام مخصص                                     |

**دورة حياة الرصيد**

1. **إصدار الأرصدة** - تُمنح عندما يشتري العميل منتجاً مرتبطاً باستحقاقات الرصيد. بالنسبة للاشتراكات، يُعاد إصدار الأرصدة كل دورة فوترة.
2. **استهلاك الأرصدة** - تُخصم مع استخدام العملاء للخدمة. تخصم العدادات الأرصدة تلقائياً وفقاً للأحداث في الوقت الفعلي، أو يمكنك الخصم يدوياً عبر لوحة التحكم أو API.
3. **انتهاء صلاحية الأرصدة أو ترحيلها** - في نهاية دورة الفوترة (أو بعد الفترة المحددة للانتهاء)، إما أن تنتهي صلاحية الأرصدة غير المستخدمة أو تُرحّل حسب إعداداتك.
4. **معالجة الزيادة** - إذا نفدت الأرصدة منتصف الدورة، يمكنك السماح بالاستمرار في الاستخدام وتحديد كيفية التعامل مع الزيادة عند نهاية الدورة.

**ربط الأرصدة بالمنتجات**

تُرفق الأرصدة كـ**استحقاقات** في سير إنشاء المنتج. يمكنك إرفاق ما يصل إلى **3 أرصدة لكل منتج**، وتعمل الأرصدة مع جميع أنواع التسعير الثلاثة: الاشتراكات، المدفوعات لمرة واحدة، والفوترة المبنية على الاستخدام.

```typescript theme={null}
// Create a checkout session for a product with attached credits
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_ai_pro_plan',
      quantity: 1,
    }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});
```

**الخصم المبني على الاستخدام**

عند ربط الأرصدة بالعدادات، يقوم النظام بخصم الأرصدة تلقائياً بناءً على أحداث الاستخدام المستوردة. قم بتكوين معدل **وحدات العداد مقابل الرصيد** للتحكم في التحويل (مثلاً، 1000 نداء API = رصيد واحد).

```typescript theme={null}
// Send usage events that deduct credits automatically
await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [{
      event_id: `gen_${Date.now()}`,
      customer_id: 'cus_abc123',
      event_name: 'ai.generation',
      timestamp: new Date().toISOString(),
      metadata: { model: 'gpt-4', tokens: 1500 }
    }]
  })
});
```

**تجربة العميل**

يمكن للعملاء عرض وإدارة أرصدةهم في **بوابة العملاء** ضمن قسم الأرصدة، مع الرصيد المتاح، وسجل المعاملات، وتحليل الاستخدام. تظهر الأرصدة أيضاً في صفحة الخروج، وتفاصيل الاشتراك، وصفحات معاملات الدفع.

<Frame>
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Customer%20Portal.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=b8afe1f89242f9e347b26b990dd00fe8" alt="عرض أرصدة بوابة العملاء مع الرصيد وسجل المعاملات" style={{ maxHeight: '500px', width: 'auto' }} width="3016" height="2030" data-path="images/CBB/Customer Portal.jpg" />
</Frame>

**الويب هوكس**

**الفوترة المبنية على الرصيد** تُطلق أحداث ويب هوكس عند كل تغيير في دورة حياة الرصيد:

| الحدث                       | الوصف                                             |
| --------------------------- | ------------------------------------------------- |
| `credit.added`              | الأرصدة الممنوحة للعميل                           |
| `credit.deducted`           | الأرصدة المستهلكة عبر الاستخدام أو الخصم اليدوي   |
| `credit.expired`            | انتهت صلاحية الأرصدة غير المستخدمة                |
| `credit.rolled_over`        | تم ترحيل الأرصدة إلى منح جديدة                    |
| `credit.rollover_forfeited` | فُقدت الأرصدة عند بلوغ الحد الأقصى لعدد الترحيلات |
| `credit.overage_charged`    | تم تطبيق رسوم الزيادة                             |
| `credit.manual_adjustment`  | تم إجراء تعديل يدوي في الرصيد/الخصم               |
| `credit.balance_low`        | انخفض الرصيد عن الحد المكوّن                      |

<Tip>
  ابدأ بإعدادات بسيطة، لا ترحيل، لا زيادة، وأضف التعقيد مع تعلمك كيفية استخدام العملاء للأرصدة. يمكن تحديث معظم الإعدادات في أي وقت دون التأثير على المنح الحالية.
</Tip>

تعرف على المزيد: [الفوترة المبنية على الرصيد](/features/credit-based-billing) | [بيانات ويب هوك الفوترة بالرصيد](/developer-resources/webhooks/intents/credit) | [واجهة برمجة تطبيقات استحقاقات الأرصدة](/api-reference/credit-entitlements/create-credit-entitlement)

### 2. **التصميم وتخصيص السمة**

نقدم الصفحة الجديدة **التصميم**، وهي محور موحد لتخصيص مظهر تجربة الخروج، والواجهة، وبوابة العملاء من مكان واحد. اختر السمات الجاهزة، اضبط الطباعة والألوان، وطبّق تفضيلات لكل قسم، مع معاينة مباشرة قبل الحفظ.

<Frame>
  <img src="https://mintcdn.com/dodopayments/vsqWNGxzquCPMqJB/images/design/general-overview.jpg?fit=max&auto=format&n=vsqWNGxzquCPMqJB&q=85&s=89f19bfb791cb903fccb3ea7127246ba" alt="صفحة إعدادات التصميم مع معاينة مباشرة للدفع، بوابة العملاء، والواجهة الرئيسية" style={{ maxHeight: '500px', width: 'auto' }} width="2880" height="1920" data-path="images/design/general-overview.jpg" />
</Frame>

**النقاط البارزة**

| الميزة                | الوصف                                                                            |
| --------------------- | -------------------------------------------------------------------------------- |
| **محور تصميم موحد**   | اضبط مظهر صفحة الدفع، والواجهة، وبوابة العملاء من صفحة واحدة                     |
| **سمات جاهزة**        | ابدأ بسمة مختارة (Dodo Pulses، Terminal، Bumblebee، أو Bubblegum) وخصصها من هناك |
| **وضع الضوء والظلام** | حدد لوحات ألوان منفصلة لكل وضع                                                   |
| **معاينة مباشرة**     | شاهد كيف تبدو التعديلات عبر الخروج، وبوابة العملاء، والواجهة قبل الحفظ           |
| **التجاوز لكل قسم**   | اضبط الأقسام الفردية بدقة دون التأثير على الآخرين                                |
| **التحكم البرمجي**    | تجاوز السمات عند الخروج عبر API أو Checkout SDK                                  |

**البدء**

انتقل إلى **التصميم** في الشريط الجانبي الرئيسي من لوحة التاجر. تحتوي الصفحة على أربعة تبويبات:

| التبويب           | الغرض                                                                |
| ----------------- | -------------------------------------------------------------------- |
| **عام**           | اسم النشاط التجاري، الشعار، اختيار السمة، والإعدادات المتقدمة العامة |
| **الدفع**         | تجاوز إعدادات السمة خصيصاً لصفحة الدفع                               |
| **الواجهة**       | تجاوز إعدادات السمة وضبط تخطيط الواجهة                               |
| **بوابة العملاء** | تجاوز إعدادات السمة لبوابة العملاء                                   |

**الإعدادات المتقدمة**

وسع الإعدادات المتقدمة في تبويب العام للتحكم التفصيلي في الطباعة (خطي Google الأساسي/الثانوي، حجم الخط، وزن الخط)، وتكوين الألوان (لوحات منفصلة لوضع الضوء والظلام تغطي الخلفيات، والنصوص، والأزرار، والحدود)، ونصف القطر للتحكم في درجة استدارة عناصر واجهة المستخدم.

<Frame>
  <img src="https://mintcdn.com/dodopayments/vsqWNGxzquCPMqJB/images/design/general-color-settings.jpg?fit=max&auto=format&n=vsqWNGxzquCPMqJB&q=85&s=c09ecc738beb79cff0d130f46bb72b0a" alt="الإعدادات المتقدمة الموسعة تظهر التكوين الكامل للألوان للوضعين الفاتح والداكن" style={{ maxHeight: '500px', width: 'auto' }} width="2880" height="4192" data-path="images/design/general-color-settings.jpg" />
</Frame>

**السمات الجاهزة**

تأتي أربع سمات مختارة افتراضياً:

* **Dodo Pulses** - السمة الافتراضية مع لمسات خضر الليمون وطباعة نظيفة بدون أطراف
* **Terminal** - موجهة للمطورين مع طباعة ثابتة العرض ولمسات زرقاء ملكية
* **Bumblebee** - لمسات كهرمانية وذهبية دافئة مع تصميم جريء وفاخر
* **Bubblegum** - لمسات وردية وماغنتا مرحة مع زوايا مدورة بالكامل

<Tip>
  بعد اختيار سمة جاهزة، يمكنك تخصيص خصائص فردية أكثر في الإعدادات المتقدمة. أي خصائص غير محددة تعود إلى إعدادات السمة الافتراضية.
</Tip>

تعرف على المزيد: [التصميم وتخصيص السمة](/features/design) | [ميزات الخروج](/features/checkout) | [الواجهة](/features/storefront)

### 3. **حالة الاسترداد وحالة النزاع في واجهة قائمة المدفوعات**

يحتوي نقطة النهاية القائمة `GET /payments` الآن على الحقول `refund_status` و `dispute_status` في كل عنصر دفع، حتى تتمكن من رؤية حالة الاسترداد والنزاع مباشرة دون استرجاع تفاصيل الدفع الفردية.

| الحقل            | النوع                     | الوصف                                                                  |
| ---------------- | ------------------------- | ---------------------------------------------------------------------- |
| `refund_status`  | `partial \| full \| null` | ملخص حالة الاسترداد لهذا الدفع. `null` إذا لم تكن هناك استردادات ناجحة |
| `dispute_status` | `string \| null`          | أحدث حالة نزاع لهذا الدفع. `null` إذا لم تكن هناك نزاعات               |

**قيم `dispute_status`**: `dispute_opened`، `dispute_expired`، `dispute_accepted`، `dispute_cancelled`، `dispute_challenged`، `dispute_won`، `dispute_lost`

<Tip>
  استخدم هذه الحقول لبناء لوحات مراقبة النزاعات والاستردادات، وتفعيل التنبيهات عند حدوث تغييرات في حالة النزاع، أو لعرض المدفوعات التي تحتاج إلى اهتمام.
</Tip>

تعرف على المزيد: [List Payments API](/api-reference/payments/get-payments)

### 4. **جدول الاستردادات في بوابة العملاء**

تتضمن بوابة العملاء الآن قسمًا مخصصًا لـ **الاستردادات** حيث يمكن للعملاء عرض جميع الاستردادات المرتبطة بمدفوعاتهم. يظهر كل إدخال استرداد مبلغ الاسترداد والحالة والتاريخ والدفع الأصلي الذي صدر ضده، مما يمنح العملاء شفافية كاملة في تاريخ استرداد الأموال دون الحاجة إلى الاتصال بالدعم.

<Check>
  يتوفر جدول الاستردادات تلقائيًا في بوابة العملاء لجميع الشركات. لا تحتاج إلى تكوين.
</Check>

تعرف على المزيد: [Customer Portal](/features/customer-portal)

### 5. **نسخ إلى الوضع الحي للعدادات**

يمكنك الآن **نسخ العدادات من وضع الاختبار إلى الوضع الحي** مباشرة من لوحة التحكم. عند الانتهاء من اختبار تكوين العداد في وضع الاختبار، استخدم إجراء النسخ لتكراره إلى الوضع الحي مع الحفاظ على جميع الإعدادات: نوع التجميع، اسم الحدث، الفلاتر، وارتباطات الائتمان. هذا يلغي الحاجة إلى إعادة إنشاء العدادات يدويًا عند الانتقال من التطوير إلى الإنتاج.

<Tip>
  قم ببناء وتحقق من تكوينات العداد في وضع الاختبار أولاً، ثم انسخها إلى الوضع الحي عندما تكون جاهزًا للانتقال إلى الإنتاج. يضمن ذلك اختبار إعداد الفوترة قبل التعامل مع استخدام العملاء الفعلي.
</Tip>

تعرف على المزيد: [Usage-Based Billing](/features/usage-based-billing/introduction) | [Meters](/features/usage-based-billing/meters)