v1.101.0 (2 يونيو 2026) - Dodo Payments Documentation

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

1. إعادة محاولات دفع الاشتراك

يمكن الآن إعادة محاولة دفع تجديد الاشتراك الفاشل تلقائيًا لاسترداد الإيرادات، دون الحاجة إلى عمل تكامل. قم بتمكينها من الإعدادات → استرداد، وقم بتعيين نافذة الاسترداد، وستعيد Dodo Payments محاولة التجديد وفقًا لجدول زمني ذكي حتى ينجح أو تنتهي النافذة.

صفحة إعدادات الاسترداد مع تمكين زر إعادة محاولات الدفع وحقل نافذة الاسترداد (أيام)

الإعداد	الوصف	الافتراضي
تمكين إعادة محاولات الدفع	إعادة محاولة الدفع الفاشل لتجديد الاشتراك تلقائيًا لاسترداد الإيرادات.	غير مفعل (الاشتراك اختياري)
نافذة الاسترداد (أيام)	المدة التي يجب الاستمرار في إعادة محاولة دفع فاشلة قبل التخلي (1–30).	13

كيف تعمل

يفشل دفع تجديد الاشتراك وتنتقل الاشتراك إلى on_hold.
إذا كان الرفض قابلاً لإعادة المحاولة (رفض مرن مثل نقص الرصيد أو خطأ مؤقت في الشبكة)، يتم جدولة المحاولة التالية تلقائياً.
تتم إعادة المحاولات خارج الجلسة وفقًا لجدول زمني متراجع، محدودًا بنافذة الاسترداد الخاصة بك.
عند المحاولة الناجحة الأولى، يعود الاشتراك إلى active ويتم تقديم تاريخ الفاتورة التالي بشكل طبيعي.

جدول إعادة المحاولة تتراجع المحاولات تدريجيًا، محاكية للوقت الذي تم فيه إنشاء الفاتورة الفاشلة. يتم القيام بما يصل إلى 8 محاولات، طالما أنها تتناسب مع نافذة الاسترداد الخاصة بك:

المحاولة	التأخير بعد السابقة
1	12 ساعة
2	24 ساعة
3	48 ساعة
4	72 ساعة
5	96 ساعة
6	120 ساعة
7	7 أيام
8	7 أيام

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

يكمل هذا أدوات الاسترداد الموجودة — حيث تقوم بريد متابعة الاشتراك بإرسال بريد إلكتروني للعميل لتحديث طريقة الدفع، بينما تقوم إعادة محاولات الدفع بإعادة المحاولة بصمت للطريقة الحالية. يعملون بشكل جيد معاً. تعرف على المزيد: إعادة محاولات دفع الاشتراك | إجراءات متابعة الاشتراك

2. إعدادات التنازل الخاصة بالأعمال

يمكنك الآن تعيين سلوك الترقية والتجريد الافتراضي المتوقع مرة واحدة على مستوى الأعمال بدلاً من تمرير معلمات التنازل في كل تغيير في الخطة. يتم تطبيق هذه الافتراضات كلما قام العميل بتغيير خطته من بوابة العميل، ويمكنك تجاوزها لكل مجموعة منتجات.

إعدادات سلوك الترقية والتخفيض الافتراضية في لوحة التحكم مع عناصر تحكم منفصلة للترقية وتخفيض الدرجة وفشل الدفع

كل اتجاه (ترقية وتخفيض) يحتوي على عنصرين تحكم مستقلين، بالإضافة إلى سياسة فشل الدفع المشتركة:

الإعداد	الحقل	الافتراضي (ترقية)	الافتراضي (تخفيض)
متى تبدأ الخطة الجديدة	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
كيف يتم تحصيل الرسوم من العميل	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
إذا فشل الدفع للعميل	`on_payment_failure`	`apply_change`	`apply_change`

متى تبدأ الخطة الجديدة (effective_at)

القيمة	السلوك
`immediately`	ينتقل العميل إلى الخطة الجديدة على الفور.
`next_billing_date`	يبقى العميل على الخطة الحالية حتى تاريخ الفاتورة التالي، ثم ينتقل إلى الجديدة.

كيف يتم تحصيل الرسوم من العميل (proration_billing_mode)

القيمة	السلوك
`prorated_immediately`	يتم تحصيل مبلغ محسوب الآن، بناءً على الوقت المتبقي في دورة الفوترة الحالية.
`full_immediately`	يتم تحصيل السعر الكامل للخطة الجديدة الآن.
`difference_immediately`	يتم تحصيل فرق السعر فقط بين الخطة الجديدة والقديمة.
`do_not_bill`	لا يتم تحصيل أي شيء الآن. يتم تطبيق أي تعديل في الفاتورة التالية.

إذا فشل الدفع للعميل (on_payment_failure)

القيمة	السلوك
`prevent_change`	يبقى العميل في خطته الحالية إذا لم ينجح الدفع.
`apply_change`	ينتقل العميل إلى الخطة الجديدة حتى لو لم يتم الدفع. يمكنك تحصيل المبلغ لاحقاً.

تجاوزات لكل مجموعة يمكن لكل مجموعة منتجات تجاوز أي من هذه الافتراضات. كل حقل مستقل — اتركه على الوراثة من العمل لاتباع الافتراض الأفتراضي للأعمال، أو قم بتعيين قيمة صريحة لتجاوزها لتلك المجموعة فقط.

قسم تجاوز سلوك الترقية والتخفيض لمجموعة منتجات، مع كل حقل يعرف على 'الوراثة من العمل'

يتم حل كل إعداد بهذا الترتيب:

per-request value (Change Plan API) → collection field (if set) → business field → system default

قيمه الطلب التي تمرر إلى تغيير خطة API (proration_billing_mode, effective_at, on_payment_failure) دائمًا تأخذ الأسبقية على كلًا من افتراضات العمل والتجميع. التعيينات الجديدة تغير فقط ما يحدث عندما لا يتم توفير قيمة صريحة — وهو الحال لجميع تغييرات الخطة عبر بوابة العميل.

تعرف على المزيد: ترقية الاشتراك وتخفيضه | مجموعات المنتجات

3. جمع اسم الشركة لفواتير B2B

يمكن الآن للعملاء B2B أن يُسجل اسم الشركة القانونية على الفاتورة بدلاً من اسم المشتري الشخصي. عند تقديم رقم ضريبي صالح في عملية الشراء، يمكنك أيضًا جمع customer_business_name ذات الصلة حتى تعكس الفاتورة الكيان الشرائي.

صفحة الخروج مع تمكين تبديل 'الشراء كشركة' ، موضحاً حقول اسم الشركة ورقم التعريف الضريبي

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

تكون المعاملة B2B (b2b = true)
يوجد tax_id
يتم تقديم customer_business_name غير فارغ

وإلاّ يُستخدم اسم العميل الشخصي. جمعها عند الخروج قم بتعيين customer_business_name بشكل مباشر، و/أو تمكين allow_customer_editing_business_name للسماح للعميل بإدخالها أو تعديلها في صفحة الخروج إلى جانب رقم التعريف الضريبي الخاص بهم:

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
  customer: { email: 'buyer@acme.com' },
  tax_id: 'GB123456789',
  customer_business_name: 'Acme Corp Ltd',
  feature_flags: {
    allow_tax_id: true,
    allow_customer_editing_business_name: true // let the customer enter/edit it
  },
  return_url: 'https://yoursite.com/return'
});

أين يُطبق

السطح	الحقل	الملاحظات
جلسات الخروج	`customer_business_name`, `feature_flags.allow_customer_editing_business_name`	بحد أقصى 250 حرفًا؛ القيمة الافتراضية هي `false`
الدفعات	`customer_business_name`	بحد أقصى 250 حرفًا
الاشتراكات	`customer_business_name`	التعيين أو الإزالة عبر `PATCH /subscriptions/{id}`

لا يمكن تعيين customer_business_name دون tax_id. يتم رفض إرسال اسم الشركة دون رقم ضريبي. إزالة tax_id أيضًا يزيل اسم الشركة، حيث أن الاثنين مرتبطان على الفاتورة.

يتم تقليم الفراغ المحيط، وتعامل القيم المكونة من الفراغ فقط كإزالة صريحة — لذا فإن البيانات المخزنة دائمًا تتطابق مع ما يظهر على الفاتورة.

تعرف على المزيد: دفعات B2B | إدارة الفواتير | جلسة الخروج

إصلاحات الأخطاء والتحسينات

إصلاحات أخطاء طفيفة وتحسينات في الثبات عبر المنصة.

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

​1. إعادة محاولات دفع الاشتراك

​2. إعدادات التنازل الخاصة بالأعمال

​3. جمع اسم الشركة لفواتير B2B

​إصلاحات الأخطاء والتحسينات

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

1. إعادة محاولات دفع الاشتراك

2. إعدادات التنازل الخاصة بالأعمال

3. جمع اسم الشركة لفواتير B2B

إصلاحات الأخطاء والتحسينات