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

​

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

• حساب تاجر مدفوعات دودو
• بيانات اعتماد واجهة برمجة التطبيقات (مفتاح API ومفتاح سرية webhook) من لوحة التحكم

​

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

​

جلسات الدفع

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: 'prod_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": "prod_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: 'prod_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);

​

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

{
  "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 - تم تجديد الاشتراك لفترة الفوترة التالية.

​

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

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

​

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

​

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

​

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

​

خيارات التقسيم النسبي

​

1. prorated_immediately

• يحسب المبلغ المقسّم نسبيًا بناءً على الوقت المتبقي في دورة الفوترة الحالية
• يحمّل العميل الفرق فقط بين الخطة القديمة والجديدة
• خلال الفترة التجريبية، ينقل المستخدم فورًا إلى الخطة الجديدة ويحمّل العميل المبلغ مباشرةً

​

2. full_immediately

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

​

3. difference_immediately

• عند الترقية، يتم تحميل العميل فورًا الفرق بين مبلغي الخطتين.
• على سبيل المثال، إذا كانت الخطة الحالية بقيمة 30 دولارًا وقام العميل بالترقية إلى خطة بقيمة 80 دولارًا، فسيتم تحميله 50 دولارًا فورًا.
• عند التخفيض، تتم إضافة المبلغ غير المستخدم من الخطة الحالية كرصيد داخلي وتطبيقه تلقائيًا على تجديدات الاشتراك المستقبلية.
• على سبيل المثال، إذا كانت الخطة الحالية بقيمة 50 دولارًا وانتقل العميل إلى خطة بقيمة 20 دولارًا، فسيتم إضافة المبلغ المتبقي، وهو 30 دولارًا، إلى الرصيد واستخدامه في دورة الفوترة التالية.

​

4. do_not_bill

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

​

السلوك

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

​

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

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

​

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

​

أهم المعلومات حول فوترة الاشتراكات

​

مرجع API ذي صلة