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

​

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

• حساب تاجر مدفوعات دودو
• بيانات اعتماد واجهة برمجة التطبيقات (مفتاح 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 - يُؤكد الدفع الأولي:
   • للفواتير الفورية (0 أيام تجربة): يُتوقع الاستلام خلال 2-10 دقائق
   • لأيام التجربة: بمجرد انتهائها
3. subscription.renewed - يُشير إلى خصم الدفع وتجديد الدورة القادمة. (بشكل أساسي، كلما تم خصم الدفع للمنتجات المشتركة، ستحصل على subscription.renewed webhook مع payment.succeeded)

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 دولارًا يُضاف كائتمان ويُستخدم في دورة الفوترة التالية.

​

السلوك

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

​

معالجة الشحن

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

​

الاشتراكات حسب الطلب

​

مرجع API ذو صلة