نظرة عامة
تتيح لك الاشتراكات عند الطلب تفويض طريقة دفع العميل مرة واحدة ثم تحصيل مبالغ متغيرة كلما احتجت، بدلاً من جدول زمني ثابت.الاشتراكات عند الطلب متاحة الآن لجميع الشركات. تتيح هذه الميزة التحكم المرن في الفوترة للخدمات المعتمدة على الاستخدام والمقاسة.
- إنشاء اشتراك عند الطلب (تفويض تفويض مع سعر أولي اختياري)
- تفعيل رسوم لاحقة بمبالغ مخصصة
- تتبع النتائج باستخدام الويب هوكس
المتطلبات الأساسية
- حساب تاجر Dodo Payments ومفتاح API
- سر الويب هوك مُعد ونقطة نهاية لاستقبال الأحداث
- منتج اشتراك في الكتالوج الخاص بك
كيف يعمل الاشتراك عند الطلب
- تقوم بإنشاء اشتراك باستخدام كائن
on_demandلتفويض وسيلة الدفع وجمع رسوم أولية اختيارية. - لاحقًا، تقوم بإنشاء رسوم ضد ذلك الاشتراك بمبالغ مخصصة باستخدام نقطة نهاية الرسوم المخصصة.
- تستمع إلى الويب هوكس (مثل
payment.succeeded،payment.failed) لتحديث نظامك.
إنشاء اشتراك عند الطلب
نقطة النهاية: POST /subscriptions حقول الطلب الرئيسية (الجسم):معلمات جسم الطلب
معلمات جسم الطلب
معرف المنتج للاشتراك.
عدد الوحدات. الحد الأدنى 1.
عنوان الفوترة للعميل.
إما إرفاق عميل موجود أو تقديم تفاصيل العميل.
إذا كانت صحيحة، يتم إنشاء رابط خروج مستضاف لتفويض التفويض والدفع الأولي الاختياري.
أين يتم إعادة توجيه العميل بعد إكمال الخروج المستضاف.
إذا كانت صحيحة، تفوض وسيلة الدفع دون فرض رسوم على العميل أثناء الإنشاء.
مبلغ الرسوم الأولية (بالوحدة النقدية الأصغر). إذا تم تحديده، فإن هذه القيمة تتجاوز السعر الأصلي للمنتج المحدد أثناء إنشاء المنتج. إذا تم حذفها، يتم استخدام السعر المخزن للمنتج. مثال: لفرض 1.00 دولار، مرر
100.تجاوز العملة الاختياري للرسوم الأولية.
تجاوز الوصف الاختياري للفوترة وبنود السطر.
إذا كانت صحيحة، تشمل رسوم العملة التكيفية ضمن
product_price. إذا كانت خاطئة، تتم إضافة الرسوم فوق ذلك. يتم تجاهلها عند تعطيل التسعير التكيفي.إنشاء اشتراك عند الطلب
- Node.js SDK
- Python SDK
- Go SDK
- cURL
قم بتعيين
payment_link: true، وأعد توجيه العميل إلى payment_link لإكمال تفويض التفويض.Success
فرض رسوم على اشتراك عند الطلب
بعد تفويض التفويض، قم بإنشاء رسوم حسب الحاجة. نقطة النهاية: POST /subscriptions/{subscription_id}/charge حقول الطلب الرئيسية (الجسم):معلمات جسم طلب الرسوم
معلمات جسم طلب الرسوم
المبلغ المفروض (بالوحدة النقدية الأصغر). مثال: لفرض 25.00 دولار، مرر
2500.تجاوز العملة الاختياري للرسوم.
تجاوز الوصف الاختياري لهذه الرسوم.
إذا كانت صحيحة، تشمل رسوم العملة التكيفية ضمن
product_price. إذا كانت خاطئة، تتم إضافة الرسوم فوق ذلك.بيانات وصفية إضافية للدفع. إذا تم حذفها، يتم استخدام بيانات الاشتراك الوصفية.
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
محاولات الدفع
قد يقوم نظام كشف الاحتيال لدينا بحظر أنماط المحاولة العدوانية (ويمكن أن يحددها كاختبار بطاقة محتمل). اتبع سياسة إعادة المحاولة الآمنة.مبادئ سياسة إعادة المحاولة الآمنة
- آلية التراجع: استخدم التراجع الأسي بين المحاولات.
- حدود إعادة المحاولة: حدد إجمالي المحاولات (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_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
للحصول على قائمة شاملة بأسباب الرفض وما إذا كانت قابلة للتصحيح من قبل المستخدم، راجع
فشل المعاملات الوثائق.
إرشادات التنفيذ (بدون كود)
- استخدم جدولة/طابور يحتفظ بطوابع زمنية دقيقة؛ احسب المحاولة التالية في نفس وقت اليوم (مثل
T + 3 daysفي نفس HH:MM). - احتفظ بالإشارة إلى آخر طابع زمني للدفع الناجح
Tلحساب المحاولة التالية؛ لا تجمع بين اشتراكات متعددة في نفس اللحظة. - قم دائمًا بتقييم سبب الرفض الأخير؛ توقف عن المحاولات في حالات الرفض الصعبة في قائمة التجاوز أعلاه.
- حدد المحاولات المتزامنة لكل عميل وحساب لمنع الارتفاعات العرضية.
- تواصل بشكل استباقي: أرسل بريدًا إلكترونيًا/SMS للعميل لتحديث وسيلة الدفع الخاصة بهم قبل المحاولة المجدولة التالية.
- استخدم البيانات الوصفية فقط للرصد (مثل
retry_attempt)؛ لا تحاول “التملص” من أنظمة الاحتيال/المخاطر عن طريق تدوير الحقول غير المهمة.
تتبع النتائج باستخدام الويب هوكس
قم بتنفيذ معالجة الويب هوك لتتبع رحلة العميل. راجع تنفيذ الويب هوكس.- subscription.active: تم تفويض التفويض وتفعيل الاشتراك
- subscription.failed: فشل الإنشاء (مثل فشل التفويض)
- subscription.on_hold: تم وضع الاشتراك في حالة تعليق (مثل الحالة غير المدفوعة)
- 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 الخاص بك للويب هوك وتكوين سر التوقيع.