معمارية الدفع: لماذا تفشل الاشتراكات في المنتصف لا في البداية
التكرار الآمن، والفشل الجزئي، ومصدر الحقيقة بين مزوّد الدفع وقاعدتك — الأخطاء التي تكلّف مالاً حقيقياً.
الدفع هو المكان الوحيد في منتجك الذي يتحوّل فيه الخطأ البرمجي إلى خسارة مالية مباشرة أو عميل غاضب. ومع ذلك يُعامَل غالباً كاستدعاء API عادي، وهنا تبدأ المشكلة.
الشبكة تفشل بين الطلب والجواب
أخطر حالة ليست فشل الدفع، بل نجاحه دون أن تعرف: أرسلت الطلب، خُصم المبلغ، ثم انقطع الاتصال قبل وصول الجواب. إن أعاد المستخدم المحاولة خُصم مرتين. الحل هو مفتاح idempotency — معرّف تولّده أنت وترسله مع الطلب، فيتعرّف المزوّد على التكرار ويعيد النتيجة الأصلية بدل تنفيذ عملية جديدة.
مصدر الحقيقة هو المزوّد لا قاعدتك
- لا تمنح الوصول بناءً على استجابة الواجهة الأمامية — يمكن التلاعب بها أو قد لا تصل أصلاً.
- امنح الوصول عند وصول تأكيد موقّع من المزوّد (webhook)، فهو الحدث الوحيد الموثوق.
- خزّن معرّف العملية لدى المزوّد في صفّك، فهو ما تعود إليه في كل نزاع.
- طابق دورياً بين حالتك وحالة المزوّد — الانحراف يحدث، والاكتشاف المتأخّر يكلّف أكثر.
الفشل الجزئي هو الحالة الطبيعية
الدفع نجح لكن كتابة الصف فشلت. أو نجح الاثنان وفشل إرسال بريد التأكيد. لا تكتب هذه الخطوات في تسلسل واحد يُفترض نجاحه كاملاً. اجعل كل خطوة قابلة للإعادة بأمان، وسجّل الحالة بعد كل واحدة، وافصل ما يجب أن يحدث فوراً عمّا يمكن أن يحدث بعد ثانية.
عميل دفع ولم يحصل على وصوله سيراسلك خلال دقائق. عميل حصل على وصول ولم يدفع لن يراسلك أبداً.
الاشتراك ليس دفعة متكرّرة
الاشتراك حالة لها دورة حياة: نشط، متأخّر السداد، ملغى مع بقاء وصول حتى نهاية المدة، منتهٍ. أغلب الأخطاء تأتي من اختزال هذا في حقل منطقي واحد. عرّف الحالات صراحةً وعرّف الانتقالات بينها، وقرّر ما يحدث في فترة التأخّر — قطع فوري يفقدك عملاء بسبب بطاقة منتهية، لا بسبب رغبة في المغادرة.
الفشل المتوقّع في التجديد
- نبّه قبل التجديد بأيام، فأغلب الفشل سببه بطاقة منتهية يمكن تحديثها مسبقاً.
- أعد المحاولة بتباعد متزايد على مدى أيام لا دقائق.
- أبقِ الوصول خلال فترة سماح معلنة بدل القطع من أول محاولة فاشلة.
- اجعل تحديث البطاقة رابطاً مباشراً في البريد، لا رحلة داخل الإعدادات.
بناء هذا صحيحاً يستغرق أسابيع ويحتاج صيانة دائمة. أوضح توثيق عملي لمفاتيح التكرار الآمن هو صفحة Stripe عن الطلبات المتكرّرة بأمان، ودليلها للويبهوكس يشرح لماذا يجب أن يكون كل معالج آمن التكرار — وهي مكتوبة كمواصفة لا كإعلان.
وإن كنت تبني منتجاً باشتراكات، فهذه المنطقة أكثر ما رأيناه يُعاد بناؤه بعد أول خسارة. راجع تصميمك معنا.
أسئلة شائعة
من أين آتي بمفتاح idempotency؟
ولّده في الواجهة عند بدء عملية الشراء واحتفظ به عبر إعادات المحاولة؛ توليده مع كل ضغطة يلغي الغرض منه.
ماذا لو وصل نفس الويبهوك مرتين؟
هذا متوقّع ومضمون الحدوث. خزّن معرّف الحدث وتجاهل ما عولج، فكل معالج ويبهوك يجب أن يكون آمن التكرار.
هل أخزّن بيانات البطاقة؟
لا. استخدم رمزاً (token) من المزوّد؛ تخزين البطاقة يضعك تحت متطلبات امتثال لا تريدها.