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

نظرة عامة

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

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

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

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

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

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

نقطة النهاية: POST /subscriptions حقول الطلب الرئيسية (الجسم):
product_id
string
مطلوب
معرف المنتج للاشتراك.
quantity
integer
مطلوب
عدد الوحدات. الحد الأدنى 1.
billing
object
مطلوب
عنوان الفوترة للعميل.
customer
object
مطلوب
إما إرفاق عميل موجود أو تقديم تفاصيل العميل.
إذا كانت صحيحة، يتم إنشاء رابط خروج مستضاف لتفويض التفويض والدفع الأولي الاختياري.
return_url
string
أين يتم إعادة توجيه العميل بعد إكمال الخروج المستضاف.
on_demand.mandate_only
boolean
مطلوب
إذا كانت صحيحة، تفوض وسيلة الدفع دون فرض رسوم على العميل أثناء الإنشاء.
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
مطلوب
المبلغ المفروض (بالوحدة النقدية الأصغر). مثال: لفرض 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 في تفاصيله قبل فرض الرسوم.

محاولات الدفع

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

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

  • آلية التراجع: استخدم التراجع الأسي بين المحاولات.
  • حدود إعادة المحاولة: حدد إجمالي المحاولات (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 الخاص بك للويب هوك وتكوين سر التوقيع.