نظرة عامة
تتيح لك الاشتراكات عند الطلب تفويض وسيلة الدفع الخاصة بالعميل مرة واحدة ثم فرض مبالغ متغيرة كلما احتجت، بدلاً من جدول زمني ثابت.قد تحتاج هذه الميزة إلى تفعيلها على حسابك. اتصل بالدعم إذا لم ترها في لوحة التحكم الخاصة بك.
- إنشاء اشتراك عند الطلب (تفويض تفويض مع سعر أولي اختياري)
- تفعيل رسوم لاحقة بمبالغ مخصصة
- تتبع النتائج باستخدام الويب هوكس
المتطلبات الأساسية
- حساب تاجر 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
إعادة المحاولة في الدفع
قد يقوم نظام كشف الاحتيال لدينا بحظر أنماط إعادة المحاولة العدوانية (ويمكن أن ي 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_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 الخاص بك وسر إعداد التوقيع.