الاشتراكات

​

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

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

​

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

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

​

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

​

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

​

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

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

​

التسعير

• نوع التسعير: اختر اشتراك (هذا الدليل). البدائل هي الدفع لمرة واحدة والفوترة بناءً على الاستخدام.
• السعر (مطلوب): السعر المتكرر الأساسي مع العملة.
• الخصم المطبق (%): نسبة الخصم الاختياري المطبقة على السعر الأساسي؛ تظهر في الدفع والفواتير.
• تكرار الدفع كل (مطلوب): الفترة الزمنية للتجديدات، على سبيل المثال، كل شهر واحد. اختر التكرار (شهور أو سنوات) والكمية.
• فترة الاشتراك (مطلوب): المدة الإجمالية التي يظل فيها الاشتراك نشطًا (على سبيل المثال، 10 سنوات). بعد انتهاء هذه الفترة، تتوقف التجديدات ما لم يتم تمديدها.
• أيام فترة التجربة (مطلوب): حدد طول التجربة بالأيام. استخدم 0 لتعطيل التجارب. يتم فرض الرسوم الأولى تلقائيًا عند انتهاء التجربة.
• اختر الإضافة: أضف ما يصل إلى 3 إضافات يمكن للعملاء شراؤها جنبًا إلى جنب مع الخطة الأساسية.

​

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

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

​

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

​

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

// 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 }
});

​

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

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;

​

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

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

​

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

​

أوضاع التقسيط

​

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'
});

​

full_immediately

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

​

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

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
});

​

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

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);

​

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

• active: الاشتراك نشط وسيتم تجديده تلقائيًا
• on_hold: الاشتراك متوقف بسبب فشل الدفع. يتطلب تحديث طريقة الدفع لإعادة التفعيل
• cancelled: تم إلغاء الاشتراك ولن يتم تجديده
• expired: وصل الاشتراك إلى تاريخ انتهاءه
• pending: يتم إنشاء الاشتراك أو معالجته

​

حالة الانتظار

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

​

إعادة التفعيل من الانتظار

1. ينشئ رسمًا للديون المتبقية
2. يولد فاتورة
3. يعالج الدفع باستخدام طريقة الدفع الجديدة
4. يعيد تفعيل الاشتراك إلى حالة active عند الدفع الناجح

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  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
}

​

إدارة واجهة برمجة التطبيقات

​

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

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

​

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

​

جلسات الدفع (الاشتراكات)

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

​

تغييرات الخطط مع التقسيط

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_period_end: true
});

​

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

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

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

​

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

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

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

​

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

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  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

​

حدود التفويض

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

​

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

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

​

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

• سيُطلب من العميل من قبل مصرفه تفويض المعاملة.
• إذا فشل العميل في تفويض المعاملة، ستفشل المعاملة وسيتم وضع الاشتراك في الانتظار.

​

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

• يتم بدء الرسوم في التاريخ المحدد وفقًا لتكرار اشتراكك.
• يتم خصم المبلغ الفعلي من حساب العميل فقط بعد 48 ساعة من بدء الدفع.
• قد يمتد هذا النافذة 48 ساعة إلى 2-3 ساعات إضافية اعتمادًا على استجابات واجهة برمجة التطبيقات للبنك.

​

نافذة إلغاء التفويض

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

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

​

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

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