تكامل الدفع الإلكتروني دورة مترابطة من الحالات، وليس زر دفع وصفحة نجاح. ينشئ النظام فاتورة أو طلباً، وقد يبدأ العميل أكثر من محاولة، وتصل إشعارات المزود متأخرة أو مكررة، ثم تحدث تسوية أو استرداد لاحقاً. التصميم الموثوق يفصل الالتزام التجاري عن محاولات الدفع وإشعارات المزود، ويتحقق من النتيجة في الخادم، ويمنح المالية والدعم سجلاً يصلح للمطابقة. تختلف القدرات والرسوم بين المزودين، لذلك تُراجع الوثائق الحالية ولا تُبنى القواعد على افتراض عام.
نمذج ما يجب دفعه أولاً
حدد الفاتورة أو الطلب والمدين والعملة والمبلغ والانتهاء وسياسة الدفعة الجزئية أو الزائدة. استخدم معرفاً داخلياً ثابتاً. عرّف متى تصبح قابلة للدفع وماذا يعني الإلغاء. لا تجعل استجابة المزود السجل الوحيد للعملية. يغطي دليل الفوترة الإلكترونية دورة المستند، ويشرح دليل أتمتة الإشعارات كيف يتبع التأكيد حدثاً مالياً موثقاً.
افصل محاولة الدفع عن الفاتورة
قد تفشل محاولة ويترك العميل أخرى ثم تنجح ثالثة. خزّن لكل محاولة معرفاً ومرجع مزود ومبلغاً وعملة وحالة وأوقاتاً وmetadata آمنة. اشتق حالة الفاتورة من الأحداث المقبولة وقواعد العمل. لا تستبدل المحاولة الأولى بالأخيرة. هذا الفصل يفسر الاسترداد الجزئي والمراجعة ويعطي الدعم مرجعاً واضحاً لكل تواصل.
عرّف الحالات حسب المزود
عرّف الحالات الداخلية بالعربية وفق ما يثبته المزود، مثل: أُنشئت، وقيد التحقق، ومفوّضة، ومدفوعة، وفاشلة، وملغاة، ومنتهية، ومستردة جزئياً أو كلياً. وثّق الانتقالات المسموحة بينها. عودة المتصفح ليست دليلاً نهائياً، ولا تختصر النتيجة في قيمة «نجح أو فشل»؛ فقد تبقى الأموال قيد المعالجة. وحّد أسباب الفشل داخلياً مع الاحتفاظ بالمرجع الآمن الذي يحتاجه الدعم.
تحقق من الخادم
افحص signature أو آلية التحقق الرسمية، ونوع الحدث والحساب والمبلغ والعملة والمراجع قبل الانتقال. استعلم عن الحالة إذا تطلبت الوثائق. ارفض callback غير مطابق وسجل correlation من دون أسرار. ضع credentials في إعدادات خادم محمية، ودوّرها، وافصل الاختبار عن الإنتاج. لا تمنح التطبيق مفتاحاً يستطيع تأكيد دفعه.
اجعل تكرار المعالجة آمناً
يعيد المزود الإشعار، وقد تسلم queue الوظيفة مرتين. خزّن event ID أو مفتاحاً فريداً وعالج داخل transaction. إذا سبق الحدث، أعد acknowledgment المتوقع من دون side effects. احم انتقال الفاتورة أيضاً. يجب ألا يرسل النظام إيصالين أو يخفض المخزون مرتين بسبب callback مكرر.
أظهر حالة عدم اليقين
Timeout عند إنشاء المحاولة لا يثبت الفشل. احتفظ بهوية الطلب واستعلم عند الإمكان، واعرض «جار التحقق» بدلاً من تشجيع retry عشوائي. إذا بدأ العميل محاولة أخرى، أبقِ الاثنين وحدد ما يحدث إذا نجح القديم لاحقاً. أنشئ queue للدعم للحالة المجهولة أو اختلاف المبلغ. لا تنفذ refund أو paid بالتخمين.
صمّم الاسترداد كسجل مالي
للـ refund مبلغ وسبب واعتماد ومرجع مزود وحالة وأحداث. تحقق من أن مجموع الاسترداد لا يتجاوز المسموح. اطلب صلاحية أقوى حسب المخاطر. فرّق في رسالة العميل بين requested وcompleted. طابق الاستردادات منفصلة واحتفظ بالدفع الأصلي. لا تغير سجل الدفع إلى قيمة جديدة تمحو تاريخه.
ابنِ تسوية يومية
قارن تقارير أو API المزود بالمحاولات الناجحة والفواتير والاستردادات والتسوية المتاحة. اعرض أحداثاً مفقودة وحالات paid بلا تطابق واختلاف مبلغ وتكراراً وpending قديماً. وزع الاستثناء على المالية أو الدعم أو الهندسة. dashboard إجمالي لا يكفي إن تعذر الانتقال من السطر إلى الفاتورة والمرجع.
اعزل المزود خلف مهايئ واضح
عرّف عمليات وحالات يملكها نظامك، ثم استخدم مهايئاً (Adapter) يترجمها إلى عقد المزود. لا تفترض أن التفويض والتحصيل الجزئي والاسترداد وإشعار Webhook تعمل بالطريقة نفسها لدى الجميع. احتفظ بالتفاصيل اللازمة للدعم داخل طبقة التكامل، واختبر المهايئ بعينات موثقة وفي البيئة التجريبية للمزود، ثم نفّذ تحققاً إنتاجياً مضبوطاً عند الحاجة.
اختبر تسلسلات خصمة
اختبر callback مكرراً وخارج الترتيب ومبلغاً أو عملة خاطئة ومحاولة منتهية ونجاحاً متأخراً وإغلاق المتصفح وانقطاع المزود وqueue retry واسترداداً جزئياً. تحقق من صلاحيات إجراءات الدعم. راقب event lag واستثناءات التسوية وأنواع الخطأ بعد الإطلاق. لا تسجل payload مالي حساس لمجرد تسهيل debug.
احمِ أدوات الدعم
واجهة الدعم المالي جزء من التكامل وليست شاشة إدارية عادية. افصل صلاحية البحث عن صلاحية تغيير الحالة أو بدء الاسترداد، واطلب سبباً واعتماداً للعملية الحساسة. لا توفر زر «اعتبر مدفوعاً» بلا مرجع وسياسة. اعرض timeline للمحاولات والأحداث والتحقق والتسوية حتى يتخذ الموظف القرار من دليل، وسجل كل وصول وتغيير.
خطط لتغيير المفاتيح والمزود
وثق rotation للـ credentials وبيئة الاختبار ووجهة callbacks والتحقق من الحساب. اختبر دوران المفتاح من دون فقد إشعارات. احتفظ بإصدار adapter وmapping، وحدد كيف تعالج محاولة بدأت قبل التغيير. عند نقل المزود، لا تخلط المراجع أو تعتبر الحالات القديمة قابلة للاستعلام دائماً. صدّر سجل التسوية واحفظ الوصول الضروري وفق السياسة.
راجع الأداء والضغط
يجب أن يرد endpoint الإشعار بسرعة وفق متطلبات المزود ثم ينقل العمل الثقيل إلى queue، مع حماية من flood وإعادة منظمة. اختبر bursts وتزامن أحداث الفاتورة نفسها. راقب queue lag وdead letters. لا تمنع callback حقيقية بسبب rate limit مصمم لمسارات المستخدم، ولا تسمح لحمولة ضخمة أو توقيع مكلف بإرهاق الخدمة من دون حدود.
نفّذ يوم تسوية مصغراً
أنشئ محاولات تجريبية ناجحة وفاشلة ومكررة، وأخّر إشعار المزود، وأضف استرداداً جزئياً ورسماً في تقرير التسوية. يجب أن يستطيع المسؤول المالي ربط كل حركة بالمحاولة والفاتورة والمرجع الخارجي من دون تعديل الإجماليات يدوياً. سجّل كل فرق في قائمة استثناءات مع مسؤول ودليل. نجاح صفحة العودة لا يثبت أن المال وصل أو أن السجل جاهز للإقفال.
الخلاصة: اجعل كل حالة مالية قابلة للتفسير
يصبح التكامل جاهزاً عندما يتتبع الدعم الفاتورة عبر المحاولات والأحداث الموثقة والتسوية والاسترداد من دون تعديل بالحدس. ابدأ بالنموذج والمطابقة قبل تجميل checkout. لمراجعة مزود بعينه، اطلب تقييماً لتكامل الدفع الإلكتروني مع الوثائق وأحداث العينة وقواعد الاسترداد وعمل المالية.