الاشتراكات - Dodo Payments Documentation

تتيح الاشتراكات لك بيع وصول مستمر مع تجديدات آلية. استخدم دورات فوترة مرنة، تجارب مجانية، تغييرات الخطة، والإضافات لتخصيص التسعير لكل عميل.

Upgrade & Downgrade

تحكم في تغييرات الخطة باستخدام النسبة وتحديثات الكمية.

On‑Demand Subscriptions

فوض تفويضًا الآن وادفع لاحقًا بمبالغ مخصصة.

Customer Portal

دع العملاء يديرون الخطط والفوترة والإلغاءات.

Subscription Webhooks

تفاعل مع أحداث دورة الحياة مثل الإنشاء والتجديد والإلغاء.

ما هي الاشتراكات؟

الاشتراكات هي منتجات متكررة يشتريها العملاء وفق جدول زمني. إنها مثالية لـ:

ترخيص SaaS: التطبيقات، واجهات برمجة التطبيقات، أو الوصول إلى المنصات
العضويات: المجتمعات، البرامج، أو الأندية
المحتوى الرقمي: الدورات، الوسائط، أو المحتوى المتميز
خطط الدعم: اتفاقيات مستوى الخدمة، حزم النجاح، أو الصيانة

الفوائد الرئيسية

إيرادات متوقعة: فواتير متكررة مع تجديدات تلقائية
دورات مرنة: شهرية، سنوية، فترات مخصصة، وتجارب
مرونة الخطط: تقسيط للترقيات والتخفيضات
إضافات ومقاعد: أضف ترقيات اختيارية وقابلة للقياس
تجربة دفع سلسة: دفع مستضاف وبوابة العملاء
موجه للمطورين: واجهات برمجة تطبيقات واضحة لإنشاء، تغييرات، وتتبع الاستخدام

إنشاء الاشتراكات

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

إنشاء منتج الاشتراك

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

تفاصيل المنتج

اسم المنتج (مطلوب): الاسم المعروض في الدفع، بوابة العملاء، والفواتير.
وصف المنتج (مطلوب): بيان قيمة واضح يظهر في الدفع والفواتير.
صورة المنتج (مطلوب): PNG/JPG/WebP حتى 3 ميغابايت. تستخدم في الدفع والفواتير.
العلامة التجارية: ربط المنتج بعلامة تجارية معينة للتصميم والبريد الإلكتروني.
فئة الضريبة (مطلوب): اختر الفئة (على سبيل المثال، SaaS) لتحديد قواعد الضريبة.

اختر فئة الضريبة الأكثر دقة لضمان جمع الضريبة الصحيح لكل منطقة.

التسعير

نوع التسعير: اختر Subscription (هذا الدليل). البدائل هي Single Payment وUsage Based Billing.
السعر (مطلوب): السعر الأساسي المتكرر مع العملة. يجب ألا يقل السعر عن $1 (أو ما يعادله بالعملة التي اخترتها). المبالغ الأقل من هذا الحد الأدنى غير مدعومة، ولن يعمل الاشتراك.
الخصم المطبق (%): خصم اختياري بنسبة مئوية يُطبَّق على السعر الأساسي؛ ويظهر في checkout والفواتير.
تكرار الدفع كل (مطلوب): الفاصل الزمني للتجديدات، مثل كل شهر واحد. اختر الوتيرة (بالأشهر أو السنوات) والكمية.
فترة الاشتراك (مطلوب): المدة الإجمالية التي يظل فيها الاشتراك نشطًا (مثل 10 سنوات). بعد انتهاء هذه الفترة، تتوقف التجديدات ما لم يتم تمديدها.
أيام الفترة التجريبية (مطلوب): حدّد مدة التجربة بالأيام. استخدم 0 لتعطيل الفترات التجريبية. يتم تحصيل الدفعة الأولى تلقائيًا عند انتهاء التجربة.
مبلغ الفترة التجريبية: رسم مقدّم اختياري لفترة تجريبية مدفوعة. اتركه دون تعيين لفترة تجريبية مجانية. راجع الفترات التجريبية المدفوعة.
تحديد الإضافة: أرفق ما يصل إلى 10 إضافات يمكن للعملاء شراؤها إلى جانب الخطة الأساسية.

يؤثر تغيير التسعير على منتج نشط على المشتريات الجديدة. تتبع الاشتراكات الحالية إعدادات تغيير الخطة والنسبة الخاصة بك.

الإضافات مثالية للميزات القابلة للقياس مثل المقاعد أو التخزين. يمكنك التحكم في الكميات المسموح بها وسلوك النسبة عندما يغيرها العملاء.

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

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

استخدم البيانات الوصفية لتخزين المعرفات من نظامك (على سبيل المثال accountId) حتى تتمكن من تسوية الأحداث والفواتير لاحقًا.

تجارب الاشتراك

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

تكوين التجارب

قم بتعيين أيام الفترة التجريبية في قسم تسعير المنتج (استخدم 0 لتعطيلها). يمكنك تجاوز هذا عند إنشاء الاشتراكات:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

يجب أن تكون القيمة trial_period_days بين 0 و10,000 يوم.

الفترات التجريبية المدفوعة

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

نموذج تسعير الاشتراك مع مدة تجريبية ومبلغ تجريبي اختياري لفترة تجريبية مدفوعة

يتم إعداد الفترات التجريبية المدفوعة على سعر المنتج، وليس لكل اشتراك أو جلسة checkout:

الحقل	النوع	الوصف
`trial_amount`	integer	المبلغ الذي يتم تحصيله اليوم مقابل التجربة، بوحدات العملة الفرعية لعملة السعر (على سبيل المثال، `500` مقابل $5.00). يتطلب `trial_period_days > 0`. احذفه أو عيّنه إلى `null` للحصول على فترة تجريبية مجانية.
`trial_apply_discounts`	boolean	ما إذا كانت رموز خصم checkout تقلل رسم التجربة. القيمة الافتراضية هي `false`، لذلك يتم تحصيل مبلغ التجربة بالكامل حتى عند تطبيق خصم على السعر المتكرر.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

تمر الفترات التجريبية المدفوعة عبر checkout أيضًا. تخضع قيمة التجربة للضريبة، وتظهر في حسابات جلسة checkout وتسعير روابط الدفع، ويتم تطبيق هامش Adaptive Currency لكل عملة. يعيد نقطة نهاية المعاينة trial_amount وtrial_period_days، بحيث يمكنك عرض المبلغ المستحق اليوم قبل إنشاء الاشتراك.

لم تتغير الفترات التجريبية المجانية. يؤدي ترك مبلغ الفترة التجريبية دون تعيين إلى الإبقاء على السلوك الحالي، حيث تكون الدفعة الأولى 0 ويتم تحصيل السعر الكامل عند انتهاء الفترة التجريبية.

منع إساءة استخدام الفترة التجريبية

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

فعّله من علامة تبويب الاشتراكات في الإعدادات. بعد تفعيله:

تتم مطابقة العملاء باستخدام البريد الإلكتروني المطبّع، مع إزالة الأسماء المستعارة بعلامة الجمع، لذلك يُعتدّ بـ user+trial@example.com وuser@example.com على أنهما الشخص نفسه.
يتم تسجيل عمليات الاسترداد عند تفعيل الفترة التجريبية، لذلك يكون العميل الذي يلغي الاشتراك في اليوم نفسه قد استهلك فترته التجريبية بالفعل.
تتم إضافة العملاء الحاليين بأثر رجعي من فترات التجربة السابقة لديهم عبر البريد الإلكتروني، ولذلك يتم التعرّف على مستخدمي الفترات التجريبية السابقين فورًا.

الإعداد معطّل افتراضيًا. راجع إعدادات الاشتراك للاطلاع على القائمة الكاملة لعناصر التحكم في الاشتراكات على مستوى النشاط التجاري.

اكتشاف حالة الفترة التجريبية

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

لتحديد ما إذا كان اشتراك فترة تجريبية مجانية لا يزال في فترة التجربة، استرجع قائمة المدفوعات الخاصة بالاشتراك. إذا كانت هناك دفعة واحدة بالضبط ومبلغها 0، يكون الاشتراك في الفترة التجريبية:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

يعمل التحقق من المبلغ الصفري مع الفترات التجريبية المجانية فقط. بالنسبة إلى الفترة التجريبية المدفوعة، تساوي الدفعة الأولى مبلغ التجربة، وليس 0. قارن الدفعة الأولى مع trial_amount الخاص بالاشتراك، أو تحقق مما إذا كان next_billing_date لا يزال ضمن فترة التجربة.

تحديث الفترة التجريبية

مدّد الفترة التجريبية من خلال تحديث next_billing_date:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

لا يمكنك تعيين next_billing_date إلى وقت سابق. يجب أن يكون التاريخ في المستقبل.

تغييرات خطة الاشتراك

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

يمكنك تغيير خطط الاشتراك وتحديث تاريخ الفوترة التالي مباشرةً من لوحة معلومات Dodo Payments. توفر هذه الطريقة وسيلة سريعة لضبط الاشتراكات استجابةً لطلبات دعم العملاء أو الترقيات الترويجية أو عمليات نقل الخطط، من دون إجراء استدعاءات API.

تمكين تغييرات الخطط بالخدمة الذاتية: هل تريد أن يتمكن العملاء من ترقية اشتراكاتهم أو تخفيضها عبر Customer Portal؟ أضف منتجات الاشتراك إلى Product Collection وفعّل “Allow Subscription Updates” في Subscription Settings.

Product Collections

جمّع المنتجات المرتبطة في مجموعات لتمكين مسارات الترقية والتخفيض السلسة في Customer Portal.

أوضاع proration

اختر طريقة فوترة العملاء عند تغيير الخطط:

مقارنة سريعة بين أوضاع proration الأربعة:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
الترقية	رسم محسوب نسبيًا للأيام المتبقية	تحصيل فرق السعر الكامل	تحصيل سعر الخطة الجديدة بالكامل	لا يوجد رسم — التبديل فورًا
التخفيض	رصيد محسوب نسبيًا للأيام المتبقية	فرق السعر الكامل كرصيد	لا يوجد رصيد، تحصيل كامل	لا يوجد رصيد — التبديل فورًا
دورة الفوترة	تُعاد إلى اليوم	تُعاد إلى اليوم	تُعاد إلى اليوم	تبقى كما هي
الأفضل لـ	فوترة عادلة بحسب الوقت	تغييرات المستويات البسيطة	إعادة ضبط دورة الفوترة	عمليات النقل المجانية أو التبديلات المجاملة

`prorated_immediately`

يحصّل مبلغًا محسوبًا نسبيًا بناءً على الوقت المتبقي في دورة الفوترة الحالية. وهو مناسب للفوترة العادلة التي تراعي الوقت غير المستخدم.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

`difference_immediately`

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

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

الأرصدة الناتجة عن التخفيضات باستخدام difference_immediately تكون مقيّدة بالاشتراك وتُطبّق تلقائيًا على التجديدات المستقبلية. وهي تختلف عن استحقاقات Credit-Based Billing.

عندما يخفض العميل خطته باستخدام difference_immediately، تصبح القيمة غير المستخدمة رصيدًا مقيّدًا بالاشتراك، ويُخصم تلقائيًا من التجديدات المستقبلية:

`full_immediately`

يحصّل مبلغ الخطة الجديدة بالكامل فورًا، متجاهلًا الوقت المتبقي. وهو مناسب لإعادة ضبط دورات الفوترة.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

`do_not_bill`

ينتقل إلى الخطة الجديدة من دون أي تعديل على الفوترة. لا توجد رسوم proration أو أرصدة — ينتقل العميل ببساطة إلى الخطة الجديدة. وهو مناسب لعمليات النقل المجاملة، أو تبديلات الخطط المجانية، أو الحالات التي تريد فيها تحمّل فرق التكلفة.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

السيناريو: يرقّي عميل مشترك في Basic (

30/شهريًا) إلى Pro (

80/شهريًا) في اليوم 16 من دورة مدتها 30 يومًا باستخدام prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

التجديد التالي في 15 فبراير (16 يناير + 30 يومًا): $80.00/شهريًا.

للاطلاع على أمثلة حسابية أكثر تفصيلًا والحالات الطرفية، راجع دليل الترقية والتخفيض الكامل.

Example: Downgrade credit calculation

السيناريو: يخفض عميل مشترك في Pro (

80/شهريًا) إلى Starter (

20/شهريًا) باستخدام difference_immediately.

Credit = Old plan − New plan = $80 − $20 = $60.00

يُطبّق رصيد $60 تلقائيًا على التجديدات المستقبلية:

التجديد 1: $20 −$ 20 (رصيد) = ** $0.00** (الرصيد المتبقي$ 40)
التجديد 2: $20 −$ 20 (رصيد) = ** $0.00** (الرصيد المتبقي$ 20)
التجديد 3: $20 −$ 20 (رصيد) = $0.00 (استهلاك الرصيد بالكامل)
التجديد 4: $20.00 (السعر الكامل)

تعرّف على المزيد حول إدارة الأرصدة في دليل الترقية والتخفيض.

تغيير الخطط مع الإضافات

عدّل الإضافات عند تغيير الخطط. يتم تضمين الإضافات في حسابات proration:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

تؤدي تغييرات الخطط إلى تحصيل رسوم فورية. قد تنقل الرسوم الفاشلة الاشتراك إلى حالة on_hold. تتبّع التغييرات عبر أحداث webhook من نوع subscription.plan_changed.

معاينة تغييرات الخطط

قبل اعتماد تغيير الخطة، اعرض معاينة للرسم الدقيق والاشتراك الناتج:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

عاين تغييرات الخطط قبل اعتمادها.

حالات الاشتراك

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

الحالة	معناها	هل يمكن استعادتها؟	مسار الاستعادة / الخطوة التالية
`pending`	يجري إنشاء الاشتراك أو معالجته	—	انتظر `subscription.active` (أو `subscription.failed`)
`active`	الاشتراك نشط وسيُجدّد تلقائيًا	—	لا يلزم اتخاذ أي إجراء
`on_hold`	فشلت دفعة التجديد (أو رسم تغيير الخطة)؛ الاشتراك متوقف مؤقتًا	نعم	حدّث طريقة الدفع لإعادة التفعيل — تلقائيًا عبر Payment Retries وDunning، أو يدويًا عبر Update Payment Method API
`cancelled`	أُلغي الاشتراك ولن يُجدّد	إعادة الشراء فقط	يجب على العميل بدء اشتراك جديد؛ ويمكن لـ Dunning حثّه على إعادة الشراء
`failed`	فشل إنشاء الاشتراك (لم تنجح التفويض أو الدفعة الأولية)	لا — نهائية	يجب على العميل إنشاء اشتراك جديد باستخدام طريقة دفع صالحة
`expired`	وصل الاشتراك إلى نهاية مدته	—	يجب على العميل بدء اشتراك جديد إذا رغب في ذلك

غالبًا ما يحدث خلط بين on_hold وfailed. الحالة on_hold قابلة للاستعادة لاشتراك نشط بالفعل فشل تجديده. أما failed فهي حالة نهائية تحدث فقط عند فشل إنشاء الاشتراك الأولي — ولا يمكن إعادة تفعيلها.

آلة الحالات

حالة التعليق

يدخل الاشتراك في حالة on_hold عندما:

تفشل دفعة تجديد (رصيد غير كافٍ، بطاقة منتهية، وغير ذلك)
تفشل رسوم تغيير الخطة
يفشل تفويض طريقة الدفع

عندما يكون الاشتراك في حالة on_hold، لن يُجدّد تلقائيًا. يجب عليك تحديث طريقة الدفع لإعادة تفعيل الاشتراك.

إعادة التفعيل من حالة التعليق

لإعادة تفعيل اشتراك من حالة on_hold، حدّث طريقة الدفع. يؤدي ذلك تلقائيًا إلى:

إنشاء رسم للمستحقات المتبقية
إنشاء فاتورة
معالجة الدفعة باستخدام طريقة الدفع الجديدة
إعادة تفعيل الاشتراك إلى حالة active عند نجاح الدفع

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

بعد تحديث طريقة الدفع بنجاح لاشتراك في حالة on_hold، ستتلقى أحداث webhook من نوع payment.succeeded، تليها أحداث subscription.active.

أحداث webhook حسب الانتقال

ينشئ كل انتقال حدث webhook، بحيث يمكنك تشغيل منطق الاستحقاقات من دون polling:

الانتقال	الحدث
تفعيل الاشتراك	`subscription.active`
نجاح التجديد	`subscription.renewed`
فشل التجديد ← توقف مؤقت	`subscription.on_hold`
فشل الإنشاء	`subscription.failed`
ترقية/تخفيض الخطة	`subscription.plan_changed`
الإلغاء	`subscription.cancelled`
انتهاء المدة	`subscription.expired`
أي تغييرات على الحقول	`subscription.updated`

Subscription Webhook Payloads

اعرض مخطط الحمولة الكامل لأحداث دورة حياة الاشتراك.

إدارة API

Create subscriptions

استخدم POST /subscriptions لإنشاء الاشتراكات برمجيًا من المنتجات، مع فترات تجريبية وإضافات اختيارية.

API Reference

اعرض API إنشاء الاشتراك.

Update subscriptions

استخدم PATCH /subscriptions/{id} لتحديث الكميات، أو الإلغاء في تاريخ الفوترة التالي، أو تعديل البيانات الوصفية.

API Reference

تعرّف على كيفية تحديث تفاصيل الاشتراك.

Change plans (proration)

غيّر المنتج النشط والكميات باستخدام عناصر تحكم proration.

API Reference

راجع خيارات تغيير الخطة.

On‑demand charges

بالنسبة إلى الاشتراكات عند الطلب، حصّل مبالغ محددة عند الطلب.

API Reference

حصّل رسوم اشتراك عند الطلب.

List and retrieve

استخدم GET /subscriptions لسرد جميع الاشتراكات وGET /subscriptions/{id} لاسترجاع اشتراك واحد.

API Reference

تصفّح APIs الخاصة بالسرد والاسترجاع.

Usage history

اجلب الاستخدام المسجّل لنماذج التسعير القائم على القياس أو التسعير الهجين.

API Reference

راجع API سجل الاستخدام.

Update payment method

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

API Reference

تعرّف على كيفية تحديث طرق الدفع وإعادة تفعيل الاشتراكات.

حالات الاستخدام الشائعة

SaaS وواجهات API: وصول متعدد المستويات مع إضافات للمقاعد أو الاستخدام
المحتوى والوسائط: وصول شهري مع فترات تجريبية تمهيدية
خطط دعم B2B: عقود سنوية مع إضافات دعم متميزة
الأدوات والإضافات: مفاتيح ترخيص وإصدارات متعاقبة

أمثلة التكامل

جلسات checkout (الاشتراكات)

عند إنشاء جلسات checkout، أدرج منتج الاشتراك والإضافات الاختيارية:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

تغييرات الخطة مع proration

رقِّ الاشتراك أو خفّضه وتحكّم في سلوك proration:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

الإلغاء في تاريخ الفوترة التالي

جدول إلغاءً يسري مفعوله عند نهاية فترة الفوترة الحالية:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

تمديد فترة الاشتراك

مدّد مدة تشغيل الاشتراك من خلال تمرير subscription_period_count وsubscription_period_interval جديدين إلى PATCH /subscriptions/{id}. تتم إعادة حساب انتهاء الاشتراك من العدد والفاصل الجديدين — على سبيل المثال، لمنح العميل وقتًا إضافيًا على خطته الحالية:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

يمكن زيادة فترة الاشتراك فقط، ولا يمكن تقصيرها.

الاشتراكات عند الطلب

أنشئ اشتراكًا عند الطلب وحصّل الرسوم لاحقًا عند الحاجة:

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

تحديث طريقة الدفع لاشتراك نشط

حدّث طريقة الدفع لاشتراك نشط:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

إعادة تفعيل اشتراك من on_hold

أعد تفعيل اشتراك تم تعليقه بسبب فشل الدفع:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

الاشتراكات ذات التفويضات المتوافقة مع RBI

تعمل اشتراكات UPI والبطاقات الهندية وفق لوائح RBI (Reserve Bank of India) مع متطلبات تفويض محددة:

حدود التفويض

يعتمد نوع التفويض ومبلغه على الرسم المتكرر لاشتراكك:

الرسوم الأقل من حد التفويض (₹15,000 افتراضيًا): ننشئ تفويضًا عند الطلب بمبلغ الحد. يتم تحصيل مبلغ الاشتراك دوريًا وفقًا لتكرار اشتراكك، وبحد أقصى حد التفويض.
الرسوم عند حد التفويض أو أعلى منه: ننشئ تفويض اشتراك (أو تفويضًا عند الطلب) بالمبلغ الدقيق للاشتراك.

يمكن ضبط حد التفويض لكل تاجر أو لكل طلب عبر mandate_min_amount_inr_paise (بـ INR paise). المبلغ المسجّل لدى البنك هو max(mandate_floor, billing_amount) — ولذلك يصبح الحد فعليًا سقف التفويض الذي يراه العميل عندما تكون الفوترة أقل. للاطلاع على معلومات تفصيلية حول التفويضات المتوافقة مع RBI وحد التفويض القابل للضبط لطرق الدفع الهندية، راجع صفحة طرق الدفع في الهند.

اعتبارات الترقية والتخفيض

مهم: عند ترقية الاشتراكات أو تخفيضها، راعِ حدود التفويض بعناية:

إذا أدت الترقية/التخفيض إلى مبلغ رسم يتجاوز Rs 15,000 ويتجاوز حد الدفع عند الطلب الحالي، فقد تفشل رسوم المعاملة.
في هذه الحالات، قد يحتاج العميل إلى تحديث طريقة الدفع أو تغيير الاشتراك مجددًا لإنشاء تفويض جديد بالحد الصحيح.

التفويض للرسوم ذات القيمة العالية

بالنسبة إلى رسوم الاشتراك التي تبلغ Rs 15,000 أو أكثر:

سيطلب البنك من العميل تفويض المعاملة.
إذا لم يتمكن العميل من تفويض المعاملة، فستفشل المعاملة وسيتم وضع الاشتراك في حالة التعليق.

تأخير المعالجة لمدة 48 ساعة

الجدول الزمني للمعالجة: تتبع الرسوم المتكررة على البطاقات الهندية واشتراكات UPI نمط معالجة فريدًا:

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

فترة إلغاء التفويض

خلال فترة المعالجة البالغة 48 ساعة:

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

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

تأخير تفعيل المزايا حتى تأكيد الدفع
تطبيق فترات سماح أو وصول مؤقت
مراقبة حالة الاشتراك لاكتشاف إلغاءات التفويض
معالجة حالات تعليق الاشتراك في منطق تطبيقك

راقب أحداث webhook للاشتراك لتتبّع تغييرات حالة الدفع ومعالجة الحالات الطرفية التي يتم فيها إلغاء التفويضات خلال فترة الـ48 ساعة.

أفضل الممارسات

ابدأ بمستويات واضحة: خطتان أو ثلاث خطط ذات اختلافات واضحة
وضّح الأسعار: اعرض الإجماليات وproration والتجديد التالي
استخدم الفترات التجريبية بحكمة: حقّق التحويل من خلال onboarding، وليس بمجرد إتاحة الوقت
استفد من الإضافات: حافظ على بساطة الخطط الأساسية وبِع الإضافات بشكل إضافي
اختبر التغييرات: تحقّق من تغييرات الخطط وproration في وضع الاختبار

تُعد الاشتراكات أساسًا مرنًا للإيرادات المتكررة. ابدأ ببساطة، واختبر جيدًا، ثم حسّن بناءً على مقاييس التبنّي ومعدل إلغاء الاشتراك والتوسع.

آخر تعديل في ٣١ يوليو ٢٠٢٦

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​ما هي الاشتراكات؟

​الفوائد الرئيسية

​إنشاء الاشتراكات

​إنشاء منتج الاشتراك

​تفاصيل المنتج

​التسعير

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

​تجارب الاشتراك

​تكوين التجارب

​الفترات التجريبية المدفوعة

​منع إساءة استخدام الفترة التجريبية

​اكتشاف حالة الفترة التجريبية

​تحديث الفترة التجريبية

​تغييرات خطة الاشتراك

Product Collections

​أوضاع proration

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​تغيير الخطط مع الإضافات

​معاينة تغييرات الخطط

Preview Change Plan API

​حالات الاشتراك

​آلة الحالات

​حالة التعليق

​إعادة التفعيل من حالة التعليق

​أحداث webhook حسب الانتقال

Subscription Webhook Payloads

​إدارة API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​حالات الاستخدام الشائعة

​أمثلة التكامل

​جلسات checkout (الاشتراكات)

​تغييرات الخطة مع proration

​الإلغاء في تاريخ الفوترة التالي

​تمديد فترة الاشتراك

​الاشتراكات عند الطلب

​تحديث طريقة الدفع لاشتراك نشط

​إعادة تفعيل اشتراك من on_hold

​الاشتراكات ذات التفويضات المتوافقة مع RBI

​حدود التفويض

​اعتبارات الترقية والتخفيض

​التفويض للرسوم ذات القيمة العالية

​تأخير المعالجة لمدة 48 ساعة

​فترة إلغاء التفويض

​أفضل الممارسات

ما هي الاشتراكات؟

الفوائد الرئيسية

إنشاء الاشتراكات

إنشاء منتج الاشتراك

تفاصيل المنتج

التسعير

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

تجارب الاشتراك

تكوين التجارب

الفترات التجريبية المدفوعة

منع إساءة استخدام الفترة التجريبية

اكتشاف حالة الفترة التجريبية

تحديث الفترة التجريبية

تغييرات خطة الاشتراك

أوضاع proration

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

تغيير الخطط مع الإضافات

معاينة تغييرات الخطط

حالات الاشتراك

آلة الحالات

حالة التعليق

إعادة التفعيل من حالة التعليق

أحداث webhook حسب الانتقال

إدارة API

حالات الاستخدام الشائعة

أمثلة التكامل

جلسات checkout (الاشتراكات)

تغييرات الخطة مع proration

الإلغاء في تاريخ الفوترة التالي

تمديد فترة الاشتراك

الاشتراكات عند الطلب

تحديث طريقة الدفع لاشتراك نشط

إعادة تفعيل اشتراك من on_hold

الاشتراكات ذات التفويضات المتوافقة مع RBI

حدود التفويض

اعتبارات الترقية والتخفيض

التفويض للرسوم ذات القيمة العالية

تأخير المعالجة لمدة 48 ساعة

فترة إلغاء التفويض

أفضل الممارسات