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

​

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

• حساب تاجر على 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: يؤكد عملية التحصيل الأولى. توقّع وصوله خلال 2–10 دقائق من Checkout.

1. عند بدء الفترة التجريبية (Checkout): يتم تشغيل 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 States.
• عند تعليق الاشتراك، لن يتم تجديده تلقائيًا حتى يتم تحديث طريقة الدفع.

​

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

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

​

2. full_immediately

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

​

3. difference_immediately

• يدفع العميل الفرق فقط بين سعر الخطة القديمة وسعر الخطة الجديدة
• لا يعتمد المبلغ على وقت إجراء التغيير ضمن الدورة. تكلف الترقية نفسها المبلغ ذاته في اليوم الأول واليوم التاسع والعشرين
• عند الترقية، يُحصّل الفرق من العميل فورًا. مثلًا: $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 ذي صلة