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

​

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

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

​

الويب هوكس

​

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

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 - يشير إلى خصم الدفع وتجديده للدورة التالية. (بشكل أساسي، كلما تم خصم الدفع لمنتجات الاشتراك، ستحصل على webhook 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 دولارًا المتبقية كرصيد ويُستخدم في دورة الفوترة التالية.

​

السلوك

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

​

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

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

​

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