الانتقال إلى المحتوى الرئيسي

نظرة عامة

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

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

  • حساب تاجر Dodo Payments ومفتاح API
  • سر الويب هوك مُعد ونقطة نهاية لاستقبال الأحداث
  • منتج اشتراك في الكتالوج الخاص بك
إذا كنت تريد من العميل الموافقة على التفويض عبر الخروج المستضاف، قم بتعيين payment_link: true وقدم return_url.

كيفية عمل الاشتراكات عند الطلب

  1. تقوم بإنشاء اشتراك باستخدام كائن on_demand لتفويض وسيلة الدفع وجمع رسوم أولية اختيارية.
  2. لاحقًا، تقوم بإنشاء رسوم ضد ذلك الاشتراك بمبالغ مخصصة باستخدام نقطة نهاية الرسوم المخصصة.
  3. تستمع إلى الويب هوكس (مثل payment.succeeded، payment.failed) لتحديث نظامك.

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

نقطة النهاية: POST /subscriptions الحقول الرئيسية المطلوبة في الطلب (الجسم):
product_id
string
required
معرف المنتج للاشتراك.
quantity
integer
required
عدد الوحدات. الحد الأدنى 1.
billing
object
required
عنوان الفوترة للعميل.
customer
object
required
إما إرفاق عميل موجود أو تقديم تفاصيل العميل.
إذا كانت صحيحة، يتم إنشاء رابط خروج مستضاف لتفويض التفويض والدفع الأولي الاختياري.
return_url
string
أين يتم إعادة توجيه العميل بعد إكمال الخروج المستضاف.
on_demand.mandate_only
boolean
required
إذا كانت صحيحة، تفوض وسيلة الدفع دون فرض رسوم على العميل أثناء الإنشاء.
on_demand.product_price
integer
مبلغ الرسوم الأولية (بالوحدة النقدية الأصغر). إذا تم تحديده، فإن هذه القيمة تتجاوز السعر الأصلي للمنتج المحدد أثناء إنشاء المنتج. إذا تم حذفها، يتم استخدام السعر المخزن للمنتج. مثال: لفرض 1.00 دولار، مرر 100.
on_demand.product_currency
string
تجاوز العملة الاختياري للرسوم الأولية.
on_demand.product_description
string
تجاوز الوصف الاختياري للفوترة وبنود السطر.
on_demand.adaptive_currency_fees_inclusive
boolean
إذا كانت صحيحة، تشمل رسوم العملة التكيفية ضمن product_price. إذا كانت خاطئة، تتم إضافة الرسوم فوق ذلك. يتم تجاهلها عند تعطيل التسعير التكيفي.

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

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 subscription = await client.subscriptions.create({
    billing: { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'customer_123' },
    product_id: 'prod_sub_123',
    quantity: 1,
    payment_link: true,
    return_url: 'https://example.com/billing/success',
    on_demand: {
      mandate_only: true, // set false to collect an initial charge
      // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
      // product_currency: 'USD',
      // product_description: 'Custom initial charge',
      // adaptive_currency_fees_inclusive: false,
    },
  });

  // If payment_link was true, redirect the customer to authorize the mandate
  console.log(subscription.payment_link);
}

main().catch(console.error);
قم بتعيين payment_link: true، وأعد توجيه العميل إلى payment_link لإكمال تفويض التفويض.
Success
{
  "subscription_id": "sub_123",
  "payment_link": "https://pay.dodopayments.com/checkout/...",
  "customer": { "customer_id": "customer_123", "email": "[email protected]", "name": "Alex Doe" },
  "metadata": {},
  "recurring_pre_tax_amount": 0,
  "addons": []
}

فرض رسوم على اشتراك عند الطلب

بعد تفويض التفويض، قم بإنشاء رسوم حسب الحاجة. نقطة النهاية: POST /subscriptions/{subscription_id}/charge الحقول الرئيسية المطلوبة في الطلب (الجسم):
product_price
integer
required
المبلغ الذي سيتم فرضه (بالوحدة النقدية الأصغر). مثال: لفرض 25.00 دولار، مرر 2500.
product_currency
string
تجاوز العملة الاختياري للرسوم.
product_description
string
تجاوز الوصف الاختياري لهذه الرسوم.
adaptive_currency_fees_inclusive
boolean
إذا كانت صحيحة، تشمل رسوم العملة التكيفية ضمن product_price. إذا كانت خاطئة، تتم إضافة الرسوم فوق ذلك.
metadata
object
بيانات وصفية إضافية للدفع. إذا تم حذفها، يتم استخدام بيانات الاشتراك الوصفية.
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);
Success
{ "payment_id": "pay_abc123" }
قد تفشل محاولة فرض رسوم على اشتراك ليس عند الطلب. تأكد من أن الاشتراك يحتوي على on_demand: true في تفاصيله قبل فرض الرسوم.

إعادة المحاولة في الدفع

قد يقوم نظام كشف الاحتيال لدينا بحظر أنماط إعادة المحاولة العدوانية (ويمكن أن ي flagها كاختبار محتمل للبطاقة). اتبع سياسة إعادة المحاولة الآمنة.
يمكن أن يتم الإبلاغ عن أنماط إعادة المحاولة المتفجرة كاحتيالية أو كاختبار محتمل للبطاقة من قبل أنظمة المخاطر ومعالجات الدفع لدينا. تجنب إعادة المحاولات المتجمعة؛ اتبع جدول التراجع وإرشادات محاذاة الوقت أدناه.

مبادئ سياسة إعادة المحاولة الآمنة

  • آلية التراجع: استخدم التراجع الأسي بين إعادة المحاولات.
  • حدود إعادة المحاولة: حدد إجمالي إعادة المحاولات (3-4 محاولات كحد أقصى).
  • تصفية ذكية: أعد المحاولة فقط في حالات الفشل القابلة لإعادة المحاولة (مثل أخطاء الشبكة/المصدر، نقص الأموال)؛ لا تعيد المحاولة أبدًا في حالات الرفض الصعبة.
  • منع اختبار البطاقة: لا تعيد المحاولة في حالات الفشل مثل DO_NOT_HONOR، STOLEN_CARD، LOST_CARD، PICKUP_CARD، FRAUDULENT، AUTHENTICATION_FAILURE.
  • تغيير البيانات الوصفية (اختياري): إذا كنت تحتفظ بنظام إعادة المحاولة الخاص بك، قم بتمييز إعادة المحاولات عبر البيانات الوصفية (مثل retry_attempt).

جدول إعادة المحاولة المقترح (الاشتراكات)

  • المحاولة الأولى: فورية عند إنشاء الرسوم
  • المحاولة الثانية: بعد 3 أيام
  • المحاولة الثالثة: بعد 7 أيام أخرى (10 أيام إجمالاً)
  • المحاولة الرابعة (الأخيرة): بعد 7 أيام أخرى (17 يومًا إجمالاً)
الخطوة النهائية: إذا لم يتم الدفع بعد، قم بوضع علامة على الاشتراك كغير مدفوع أو قم بإلغائه، بناءً على سياستك. قم بإخطار العميل خلال الفترة الزمنية لتحديث وسيلة الدفع الخاصة بهم.

تجنب إعادة المحاولات المتفجرة؛ محاذاة مع وقت التفويض

  • قم بتثبيت إعادة المحاولات على الطابع الزمني الأصلي للتفويض لتجنب سلوك “الانفجار” عبر محفظتك.
  • مثال: إذا بدأ العميل تجربة أو تفويض في الساعة 1:10 مساءً اليوم، قم بجدولة إعادة المحاولات التالية في الساعة 1:10 مساءً في الأيام التالية وفقًا لجدول التراجع الخاص بك (مثل +3 أيام → 1:10 مساءً، +7 أيام → 1:10 مساءً).
  • بدلاً من ذلك، إذا كنت تخزن وقت الدفع الناجح الأخير T، قم بجدولة المحاولة التالية في T + X days للحفاظ على محاذاة وقت اليوم.
المنطقة الزمنية وDST: استخدم معيار وقت ثابت لجدولة وتحويل العرض فقط للحفاظ على الفترات.

رموز الرفض التي يجب ألا تعيد المحاولة عليها

  • STOLEN_CARD
  • DO_NOT_HONOR
  • FRAUDULENT
  • PICKUP_CARD
  • AUTHENTICATION_FAILURE
  • LOST_CARD
للحصول على قائمة شاملة بأسباب الرفض وما إذا كانت قابلة للتصحيح من قبل المستخدم، راجع فشل المعاملات الوثائق.
قم بإعادة المحاولة فقط في المشكلات المؤقتة/الناعمة (مثل insufficient_funds، issuer_unavailable، processing_error، مهلات الشبكة). إذا تكرر نفس الرفض، توقف عن المزيد من إعادة المحاولات.

إرشادات التنفيذ (بدون كود)

  • استخدم جدولة/طابور يحتفظ بطوابع زمنية دقيقة؛ احسب المحاولة التالية في نفس وقت اليوم (مثل T + 3 days في نفس HH:MM).
  • احتفظ بالإشارة إلى آخر طابع زمني للدفع الناجح T لحساب المحاولة التالية؛ لا تجمع بين اشتراكات متعددة في نفس اللحظة.
  • قم دائمًا بتقييم سبب الرفض الأخير؛ توقف عن إعادة المحاولات في حالات الرفض الصعبة في قائمة التجاوز أعلاه.
  • حدد عدد إعادة المحاولات المتزامنة لكل عميل ولكل حساب لمنع الارتفاعات العرضية.
  • تواصل بشكل استباقي: أرسل بريدًا إلكترونيًا/SMS للعميل لتحديث وسيلة الدفع الخاصة بهم قبل المحاولة المجدولة التالية.
  • استخدم البيانات الوصفية فقط للرؤية (مثل retry_attempt)؛ لا تحاول “التملص” من أنظمة الاحتيال/المخاطر عن طريق تدوير الحقول غير المهمة.

تتبع النتائج باستخدام الويب هوكس

قم بتنفيذ معالجة الويب هوك لتتبع رحلة العميل. راجع تنفيذ الويب هوكس.
  • subscription.active: تم تفويض التفويض وتم تفعيل الاشتراك
  • subscription.failed: فشل الإنشاء (مثل فشل التفويض)
  • subscription.on_hold: تم وضع الاشتراك في حالة تعليق (مثل حالة غير مدفوعة)
  • payment.succeeded: تم فرض الرسوم بنجاح
  • payment.failed: فشل فرض الرسوم
بالنسبة لتدفقات الاشتراك عند الطلب، ركز على payment.succeeded و payment.failed لمصالحة الرسوم المستندة إلى الاستخدام.

الاختبار والخطوات التالية

1

إنشاء في وضع الاختبار

استخدم مفتاح API الخاص بك للاختبار لإنشاء الاشتراك مع payment_link: true، ثم افتح الرابط وأكمل التفويض.
2

تفعيل رسوم

استدعِ نقطة نهاية الرسوم بمبلغ صغير product_price (مثل 100) وتحقق من أنك تتلقى payment.succeeded.
3

الانتقال إلى الوضع المباشر

قم بالتبديل إلى مفتاح API المباشر الخاص بك بمجرد التحقق من الأحداث وتحديثات الحالة الداخلية.

استكشاف الأخطاء وإصلاحها

  • 422 طلب غير صالح: تأكد من تقديم on_demand.mandate_only عند الإنشاء و product_price مقدمة للرسوم.
  • أخطاء العملة: إذا قمت بتجاوز product_currency، تأكد من أنه مدعوم لحسابك وعميلك.
  • لم يتم استلام الويب هوكس: تحقق من عنوان URL الخاص بك وسر إعداد التوقيع.