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

​

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

• حساب تاجر مدفوعات دودو
• بيانات اعتماد واجهة برمجة التطبيقات (مفتاح 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: '[email protected]',
      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": "[email protected]",
        "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: '[email protected]',
      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"
}

​

الويب هوكس

​

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

1. subscription.active - تم تفعيل الاشتراك بنجاح.
2. subscription.updated - تم تحديث كائن الاشتراك (يتم تشغيله عند أي تغيير في الحقول).
3. subscription.on_hold - تم تعليق الاشتراك بسبب فشل التجديد.
4. subscription.failed - فشل إنشاء الاشتراك أثناء إنشاء التفويض.
5. subscription.renewed - تم تجديد الاشتراك للفترة التالية من الفوترة.

​

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

1. subscription.active - يشير إلى تفعيل الاشتراك
2. payment.succeeded - يؤكد الدفع الأولي:
   • للفوترة الفورية (0 أيام تجريبية): توقع خلال 2-10 دقائق
   • لأيام التجربة: في أي وقت ينتهي
3. subscription.renewed - يشير إلى خصم الدفع والتجديد للدورة التالية. (بشكل أساسي، كلما تم خصم الدفع لمنتجات الاشتراك، ستحصل على subscription.renewed ويب هوك مع payment.succeeded)

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

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

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

• 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
}

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 دولارًا المتبقية كرصيد واستخدامها نحو دورة الفوترة التالية.

​

السلوك

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

​

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

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

​

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