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

​

المتطلبات الأساسية

• حساب تاجر على Dodo Payments
• مفتاح API من Developer → API Keys في لوحة التحكم، محفوظ في DODO_PAYMENTS_API_KEY
• سر webhook من Developer → Webhooks، محفوظ في DODO_PAYMENTS_WEBHOOK_KEY
• منتج اشتراك واحد على الأقل تم إنشاؤه ضمن Products

​

تكامل API

​

جلسات الدفع

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

استجابة API

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhooks

​

أنواع أحداث الاشتراك

1. subscription.active — تم تفعيل الاشتراك
2. subscription.updated — تغيّر حقل في الاشتراك
3. subscription.on_hold — فشلت عملية تحصيل رسوم التجديد أو تغيير الخطة
4. subscription.failed — فشل إنشاء الاشتراك (نهائي؛ يجب على العميل الاشتراك مجددًا)
5. subscription.renewed — نجحت عملية تحصيل رسوم متكررة
6. subscription.past_due — فشل التجديد وبدأت فترة السماح؛ يحتفظ العميل بإمكانية الوصول حتى past_due_ends_at
7. subscription.plan_changed — تمت ترقية الخطة أو تخفيضها أو تغييرها
8. subscription.cancelled — أُلغي الاشتراك
9. subscription.expired — وصل الاشتراك إلى نهاية مدته

​

سيناريوهات الدفع

1. subscription.active: تتم الموافقة على التفويض وتفعيل الاشتراك.
2. payment.succeeded: يؤكد عملية التحصيل الأولى. توقّع هذا الحدث خلال دقيقتين إلى 10 دقائق من إتمام الدفع.

1. عند بدء الفترة التجريبية (الدفع): يتم تشغيل subscription.active بعد تفويض طريقة الدفع. لا يتم تحصيل رسوم متكررة بعد. ويتم تأجيل أول عملية تحصيل فعلية حتى انتهاء الفترة التجريبية.
2. عند انتهاء الفترة التجريبية: يتم تحصيل المبلغ المتكرر، وتتلقى payment.succeeded مع subscription.renewed.

• subscription.renewed: يتم تشغيله في كل دورة فوترة عند خصم دفعة التجديد، ودائمًا بالتزامن مع payment.succeeded. كما يتضمن next_billing_date المحدّث.

1. فشل الاشتراك

• subscription.failed - فشل إنشاء الاشتراك بسبب تعذّر إنشاء التفويض.
• payment.failed - يشير إلى فشل الدفع.

2. تعليق الاشتراك

• subscription.on_hold - تم تعليق الاشتراك بسبب فشل دفعة التجديد أو فشل رسوم تغيير الخطة. إذا كان لنشاطك التجاري فترة سماح، فإن التجديد الفاشل ينقل الاشتراك أولًا إلى past_due (subscription.past_due)، ثم ينقله إلى on_hold (أو cancelled، حسب إعدادات فترة السماح) فقط عند انتهاء فترة السماح. راجع حالات الاشتراك.
• عند تعليق الاشتراك، لن يتم تجديده تلقائيًا حتى يتم تحديث طريقة الدفع.

​

subscription.failed مقابل subscription.on_hold

​

التعامل مع الاشتراك المعلّق

​

متى يتم تعليق الاشتراكات

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

​

إعادة تفعيل الاشتراكات المعلّقة

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

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  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 for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

نموذج حمولة حدث اشتراك

​

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

​

خيارات Proration

​

1. prorated_immediately

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

​

2. full_immediately

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

​

3. difference_immediately

• يدفع العميل الفرق فقط بين سعر الخطة القديمة وسعر الخطة الجديدة
• لا يعتمد المبلغ على وقت إجراء التغيير ضمن الدورة. تكلف الترقية نفسها المبلغ نفسه في اليوم الأول واليوم 29
• عند الترقية، يُفرض على العميل الفرق فورًا. على سبيل المثال، $30/شهريًا → $80/شهريًا = يتم تحصيل $50 فورًا
• عند التخفيض، يُخزّن فرق السعر كرصيد مرتبط بالاشتراك ويُطبّق تلقائيًا على التجديدات المستقبلية. على سبيل المثال، $50/شهريًا → $20/شهريًا = يتم تخزين $30 كرصيد

​

4. do_not_bill

• يطبّق تغيير الخطة فورًا، لكنه لا يفرض أي رسوم وقت التغيير. ويمكن استخدام الخطة والكمية والإضافات الجديدة مباشرة
• بما أنه لا يتم تحصيل أي رسوم الآن، تمنح الترقية العميل الخطة الأعلى مجانًا لبقية الدورة الحالية. ويصبح التخفيض ساريًا فورًا دون رصيد للجزء غير المستخدم من الدورة التي دفع العميل مقابلها مسبقًا
• لا تتم إضافة رصيد للإضافات الممنوحة عبر do_not_bill عند تغيير الخطة لاحقًا، لأنها لم تُفوتر أصلًا. ويؤدي التغيير اللاحق إلى فوترة كمية الإضافة الجديدة بالكامل
• تتم فوترة الخطة المحدّثة (والكمية/الإضافات) عند التجديد المجدول التالي، مع الحفاظ على تاريخ الفوترة الأصلي

​

السلوك

• عند استدعاء API هذا، يبدأ Dodo Payments فورًا عملية تحصيل استنادًا إلى خيار proration الذي اخترته
• مع prorated_immediately، يتم احتساب رصيد الجزء غير المستخدم من الدورة الحالية عند كل تغيير، سواء كانت ترقية أو تخفيضًا. وإذا تجاوز الرصيد رسوم الدورة الجديدة، تُضاف القيمة المتبقية إلى رصيد الاشتراك. وتكون هذه الأرصدة خاصة بالاشتراك ولن تُستخدم إلا لمقاصة الدفعات المتكررة المستقبلية للاشتراك نفسه
• مع difference_immediately، يكون الصافي دائمًا مساويًا تمامًا لفرق السعر. وفي حالة التخفيض، يُخزّن الفرق الزائد كرصيد مرتبط بالاشتراك، كما في prorated_immediately
• يتجاوز خيار full_immediately حسابات الرصيد ويفرض كامل مبلغ الخطة الجديدة
• يطبّق خيار do_not_bill التغيير فورًا، لكنه يؤجل الفوترة إلى تاريخ التجديد التالي، مع الحفاظ على هذا التاريخ

​

معالجة الرسوم

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

​

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

​

أمور أساسية يجب معرفتها حول فوترة الاشتراكات

​

مرجع API ذي صلة