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

ربط بوابات الدفع Paymob وKashier وFawry بمتجرك خطوة بخطوة

T
Tarek Ibrahim
•
ربط بوابات الدفع Paymob وKashier وFawry مع WooCommerce وLaravel في مصر

أغلب مشاريع الدفع الاونلاين في مصر مش بتفشل بسبب البوابة نفسها. بتفشل بسبب اللي حواليها: أوردر اتعلم مدفوع قبل ما الفلوس تتأكد، أو كولباك محدش بيتحقق منه، أو فرق عملة مبانش غير في أول عملية حقيقية، أو عملية تحويل يدوي معتمدة على واحد بيراجع سكرين شوت على واتساب. المقال ده بيشرح إزاي Paymob وKashier وFawry بيتربطوا بمتجر WooCommerce أو بأبلكيشن Laravel، وفين التكامل بيقع غالبا، وإزاي تتعامل مع تحويلات InstaPay اللي مفيش وراها بوابة.

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

ابدأ بالقرار قبل الإضافة

فيه سؤالين لازم يتحسموا قبل ما حد يثبت أي حاجة. السؤال الأول: الشيك أوت عندك عادي ولا خطوات مخصصة؟ كتالوج عادي فيه عربة وشحن وكوبونات بيناسب WooCommerce، وكل بوابة كبيرة في مصر عندها إضافة له أو طريق موثق. أما لو عندك عربون، أو أقساط مربوطة بمراحل عقد، أو حدود ائتمان لعملاء B2B، أو حجز بيتثبت لوقت معين، فغالبا مكانه أبلكيشن مخصص، واحنا بنبنيه بـ Laravel.

السؤال التاني: عملاءك بيدفعوا بإيه فعلا؟ الكروت جزء واحد بس من الصورة في مصر. المحافظ الإلكترونية والدفع النقدي في نقطة بيع والتقسيط البنكي والتحويل البنكي المباشر، كلهم ليهم حجم حقيقي حسب نوع الجمهور. بوابة بتغطي طرق الدفع اللي عملاءك بيحبوها أحسن من بوابة لوحة التحكم بتاعتها شكلها أحلى شوية. اسأل كل مزود عن قائمة الطرق المفعلة على حسابك أنت بالظبط، لأن اللي مكتوب في التوثيق ممكن يختلف عن اللي مفعل عندك.

لو لسه بتحدد حجم المتجر نفسه، شوف مقالنا عن تكلفة متجر إلكتروني في مصر وصفحة تطوير المتاجر الإلكترونية. المقال ده مركز على الدفع بس.

شكل أي تكامل مع بوابة دفع

أي بوابة بتشتغل بنظام الصفحة المستضافة أو التحويل ماشية على نفس التسلسل، وفهمه بيسهل قراءة توثيق أي مزود.

  • السيرفر بتاعك بيعمل أوردر في قاعدة بياناتك بحالة زي بانتظار الدفع، ومعاه رقم مرجعي فريد.
  • السيرفر بيكلم البوابة ببيانات المبلغ والعملة والعميل والرقم المرجعي، باستخدام مفاتيح سرية عمرها ما توصل للمتصفح.
  • البوابة بترجع حاجة المتصفح يقدر يستخدمها: رابط دفع أو client secret أو توكن.
  • العميل بيدفع في صفحة البوابة نفسها، يعني بيانات الكارت ما بتدخلش سيرفرك أصلا.
  • العميل بيرجع لموقعك. الرجوع ده مجرد مجاملة للعميل، وهو مش دليل على الدفع.
  • البوابة بتبعت إشعار من سيرفر لسيرفر، اسمه كولباك أو ويب هوك. سيرفرك بيتحقق منه وبعدين بس بيعلم الأوردر مدفوع.

آخر خطوتين هما مكان أغلب العيوب. رجوع المتصفح ممكن يتقطع أو يتكرر أو يتزور. الإشعار الموقع من السيرفر هو مصدر الحقيقة. وكل قرار تصميم تحت بيمشي على القاعدة دي.

Paymob: نية الدفع ثم التحويل ثم كولباك متحقق منه

قبل تنفيذ الربط، راجع التوثيق الرسمي لـ Paymob Payment Intention للتأكد من أحدث الحقول المطلوبة، وطريقة التحقق، وخطوات عملية الدفع.

المفاتيح والبيئات

هتتعامل مع secret key وpublic key من لوحة تحكم Paymob، وواحد أو أكتر من integration IDs (كل واحد مربوط بطريقة دفع وعملة)، وكمان HMAC secret منفصل بيتستخدم للتحقق من الكولباك. الاختبار والتشغيل الفعلي بيئتين منفصلتين، والتوثيق بيقول إن حالة integration IDs (تجريبي أو فعلي) لازم تطابق الـ secret key اللي بتستخدمه. خلط الاتنين غلطة شائعة في أول يوم، وبتطلع أعطال شكلها كأنها غلطة في الكود.

إنشاء الـ intention

السيرفر بيكلم endpoint الـ Create Intention وفي الهيدر Authorization بتكتب كلمة Token وبعدها مسافة وبعدها الـ secret key. الـ body فيه المبلغ بالقروش (يعني 250 جنيه بتتبعت 25000)، والعملة اللي لازم تطابق عملة الـ integration ID، ومصفوفة payment_methods فيها الـ integration IDs، والعناصر items، وبيانات الفاتورة billing_data، وحقول إضافية اختيارية. فيه حقلين مهمين. حقل special_reference ده رقمك المرجعي الفريد، وبيرجع في كولباك المعاملة باسم merchant_order_id، وبه بتلاقي الأوردر الصح. وحقل extras بيخليك تمرر بياناتك الخاصة لحد الكولباك.

التوثيق كمان بيذكر إن notification URL مدعوم مع الـ integration IDs الخاصة بالكروت بس، وإن redirection URL مدعوم للكارت والمحفظة بس. فلو بتقدم طريقة دفع تانية، جهز طريقة لتأكيد الحالة مش معتمدة على الإشعار ده، زي مراجعة المعاملة من لوحة التحكم أو استعلام موصوف في مرجع الـ API.

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

الرد فيه client_secret. في تجربة التحويل، بتبعت متصفح العميل لهوست الشيك أوت الخاص بمنطقته، ومعاه الـ public key والـ client secret كـ query parameters. بالنسبة لمصر الهوست الموثق هو eg.checkout.paymob.com. العميل بيكمل الدفع هناك.

التحقق من الكولباك بـ HMAC

Paymob بتوقع كولباك المعاملات. الطريقة الموثقة هي HMAC بخوارزمية SHA-512 ومفتاحه الـ HMAC secret بتاعك، محسوب على تجميع حقول معينة من الكولباك بترتيب ثابت: amount_cents وcreated_at وcurrency وerror_occured وhas_parent_transaction ورقم المعاملة وintegration_id وis_3d_secure وis_auth وis_capture وis_refunded وis_standalone_payment وis_voided ورقم الأوردر وowner وpending وsource_data.pan وsource_data.sub_type وsource_data.type وsuccess. بتبني النص من غير فواصل، وبتحسب الـ HMAC، وبتقارنه بقيمة hmac اللي وصلت مع الكولباك. أسماء الحقول بتختلف شوية بين الـ processed callback (POST بجسم JSON) والـ response callback (GET بـ query parameters)، فاكتب mapper صغير لكل واحد بدل دالة واحدة بتخمن.

ملاحظتين تنفيذ من الخبرة، ومش خاصين بـ Paymob. قارن التوقيعات بدالة مقارنة ثابتة الزمن، وفي PHP دي hash_equals. وخد بالك من الحقول المنطقية: النص اللي بتعمله hash لازم يكون بنفس شكل true وfalse اللي البوابة استخدمته، فجرب بكولباك حقيقي من البيئة التجريبية بدل ما تفترض.

Paymob في WooCommerce وفي Laravel

في WooCommerce، شوف لو Paymob عندها إضافة رسمية لنسخة WooCommerce بتاعتك وهل بتدعم الشيك أوت المبني على الـ intention. لو آه، التثبيت غالبا مفاتيح وintegration IDs وروابط الكولباك المسجلة في لوحة Paymob. ولو محتاج سلوك الإضافة ما بتقدمهوش، زي تقسيم الأوردرات أو حالات أوردر مخصصة، فكلاس بوابة دفع مخصص صغير بيمتد من الكلاس الأساسي في WooCommerce أنضف من تعديل إضافة جاهزة.

في Laravel، اعمل كلاس خدمة للدفع بتلات مسؤوليات: إنشاء الـ intention، وبناء رابط التحويل، والتحقق من الكولباك. خزن رقم الـ intention أو الأوردر الخاص بـ Paymob في سجل الدفع، واعمل مسار الكولباك idempotent، وسيب تغيير حالة الأوردر الفعلي لـ job في الطابور. شغلنا في تطوير Laravel ماشي على النمط ده في مشاريع الحجز والبوابات.

Kashier: إضافة أولا، ونموذج مدمج كخيار

Kashier بتنشر إضافات WooCommerce، والتوثيق بيفرق بين تلات طرق: إضافة للشيك أوت الكلاسيكي، وإضافة للشيك أوت المبني على البلوكات، وخيار نموذج مدمج بيتوزع عن طريق دعم Kashier لحالات زي الحسابات المتصلة أو WooCommerce Subscriptions.

إيه اللي تراجعه قبل التثبيت

أول مراجعة: متجرك شغال بأنهي شيك أوت؟ متاجر WooCommerce على الشيك أوت المبني على البلوكات محتاجة إضافة البلوكات، وعدم التطابق ده أشهر سبب إن طريقة الدفع ما بتظهرش عند الشيك أوت. تاني مراجعة هي High-Performance Order Storage. التوثيق بيقول للتجار على WooCommerce 8 أو أحدث يفعلوا HPOS من WooCommerce ثم Settings ثم Advanced ثم Features قبل التثبيت. تالت مراجعة هي العملة. صفحات الإضافة بتذكر EGP وUSD وGBP وEUR، وبتوصف خيار Enforce EGP Payment: لما بيتفعل، المدفوعات بتتسوى بالجنيه حتى لو المتجر بيعرض عملة تانية، ولازم تحط سعر صرف أكبر من 1. قرر مين صاحب السعر ده وبيتحدث كل قد إيه، لأن السعر القديم بيتحول لغلطة تسعير.

الإعداد

بتاخد API key وsecret key من صفحة Integration في لوحة تحكم تاجر Kashier، وMerchant ID بيتكتب في إعدادات كل طريقة دفع مفعلة. بعد رفع الإضافة وتفعيلها، طرق الدفع بتظهر تحت WooCommerce ثم Settings ثم Payments، وكل طريقة تفعلها محتاجة بياناتها وعنوانها ووصفها. سيب وضع الاختبار شغال وانت بتجرب بكروت الاختبار من دليل الاختبار عند Kashier، وبعدها بدل مفاتيح الاختبار بمفاتيح التشغيل وطفي وضع الاختبار. اعمل ده كخطوة إصدار مقصودة وليها مسؤول بالاسم، مش كتعديل عابر ليلة الجمعة.

الويب هوك

صفحة إضافة WooCommerce اللي راجعناها ما بتغطيش الويب هوك أو الكولباك. ما تفترضش إن الإضافة بتتعامل مع كل تغيير حالة في بيئتك. اقرأ توثيق الويب هوك عند Kashier، واتأكد من الدعم إزاي بيبلغوا عن المدفوعات الفاشلة والمستردة والمنتهية، وجربهم. ولو بتبني Laravel مخصص على Kashier، استخدم طريق صفحة الدفع المستضافة من دليل التكامل عندهم، ونفس القاعدة: الإشعار الموقع من السيرفر هو اللي بيحدد حالة الأوردر، مش رجوع المتصفح.

Fawry: طلبات دفع موقعة ودفع نقدي في المحل

Fawry مختلفة بسبب Pay at Fawry، اللي فيها العميل بياخد رقم مرجعي ويدفع كاش في نقطة فوري. ده بيغير دورة حياة الأوردر، لأن الأوردر ممكن يفضل غير مدفوع ساعات أو أيام.

طلب الدفع

الأدلة العامة بتوصف طلب الدفع كحامل لـ merchantCode وmerchantRefNum (رقمك المرجعي) وcustomerMobile وcustomerEmail وamount بخانتين عشريتين وcurrencyCode وlanguage وchargeItems فيها itemId وdescription وprice وquantity، وpaymentMethod زي PAYATFAWRY أو CARD، ووصف، وsignature. والحقول الاختيارية منها customerProfileId وcustomerName وorderWebHookUrl. للدفع بالكارت الأدلة بتضيف بيانات الكارت وreturnUrl وعلم enable3DS وخيارات توكنات الكروت وخطط التقسيط البنكي.

التوقيع هو SHA-256 لتجميع merchantCode وmerchantRefNum وcustomerProfileId (نص فاضي لو مش موجود) وpaymentMethod والمبلغ بخانتين عشريتين والمفتاح السري، بالترتيب ده. استعلام الحالة بيستخدم hash شبهه من merchantCode وmerchantRefNumber والمفتاح السري. ولأن التوقيع معتمد على شكل النص بالظبط، مبلغ اتبعت 250 في مكان و250.00 في مكان تاني هيطلع hash مختلف. اجمع التنسيق ده في دالة واحدة.

الحالات والإشعارات

حالات الأوردر الموثقة منها NEW وPAID وEXPIRED وCANCELED وREFUNDED وFAILED. فوري بتبعت POST من سيرفر لسيرفر على endpoint متظبط كل ما الحالة تتغير، وخيار الويب هوك الخاص بكل أوردر بيغطي أحداث زي الدفع والانتهاء والاسترداد. في Pay at Fawry، نظامك لازم يتعامل بنضافة مع مسار غير مدفوع ثم منتهي: حرر المخزون أو مواعيد الحجز المحجوزة لما الرقم المرجعي ينتهي، وقول للعميل بوضوح الرقم صالح لحد امتى.

Fawry في WooCommerce وLaravel

في WooCommerce، اتأكد من فوري أنهي إضافة أو حزمة تكامل بتدعمها دلوقتي لنسختك. فيه إضافات من أطراف تانية وجودتها بتختلف، فراجع أي إضافة بتتعامل مع فلوس بنفس دقة مراجعة كود كتبته بنفسك. في Laravel، حط الطلب وبناء التوقيع ومعالج الويب هوك في خدمة واحدة، وخزن merchantRefNum والرقم المرجعي من فوري في سجل الدفع، واكتب job مجدول بيفحص حالة الأوردرات اللي فضلت غير مدفوعة بعد المدة المتوقعة، باستخدام استعلام الحالة كشبكة أمان للإشعارات الفايتة.

InstaPay والتحويل اليدوي: ابني العملية مش التعليمات بس

تجار كتير في مصر بيقبلوا تحويلات InstaPay مباشرة: العميل بيحول للعنوان الخاص بالتاجر وبعدين يبعت إثبات. مفيش كولباك من بوابة في النظام ده، يعني مفيش إثبات دفع أوتوماتيك. احنا مش بنوصف API هنا لأن الطريق اليدوي مالوش واحد. اللي تقدر تبنيه هو عملية متحكم فيها حواليه.

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

التحويل اليدوي مقبول مع الحجم الصغير ومع عملاء B2B اللي بيفضلوا الدفع البنكي. هو مش بيكبر كويس، وهو الطريق اللي بتتركز فيه الأخطاء والخلافات. ولما الحجم يزيد، انقل الحالات الشائعة لطريقة دفع على بوابة، وسيب التحويل كاستثناء.

القواعد المشتركة في أي تكامل

التكرار الآمن idempotency

البوابات ممكن تبعت نفس الإشعار أكتر من مرة، والعملاء ممكن يعملوا ريفريش لصفحة الرجوع. المعالج عندك لازم يكون آمن لو اتنفذ مرتين: دور على الدفع برقمك المرجعي، وافحص الحالة الحالية، وغير من معلق لمدفوع مرة واحدة بس. قيد فريد في قاعدة البيانات على رقم معاملة البوابة بيمنع التكرار لو طلبين وصلوا في نفس اللحظة.

فحص المبلغ والعملة

لما إشعار يوصل، قارن المبلغ والعملة بالأوردر في قاعدة بياناتك. التوقيع الصحيح بيثبت إن الرسالة جاية من البوابة، لكنه ما بيثبتش إن المبلغ مطابق للمتوقع للأوردر ده. ارفض أي عدم تطابق وعلم عليه.

تصميم حالات الأوردر

حدد الحالات صراحة: بانتظار الدفع، بانتظار التحويل، مدفوع، فاشل، منتهي، مسترد، مسترد جزئيا. وحدد التحويلات المسموحة. أوردر مسترد عمره ما يرجع مدفوع لأن إشعار متأخر وصل بترتيب غلط.

الأسرار والسجلات

مفاتيح الـ API وأسرار الـ HMAC مكانها إعدادات البيئة، مش المستودع، ومش ملفات القالب، ومش قاعدة البيانات كنص عادي في شاشة إدارة مشتركة. سجل كل إشعار ببياناته الخام ونتيجة التحقق والإجراء اللي اتاخد، لكن عمرك ما تسجل بيانات الكارت كاملة، وقنع أي بيان مش محتاجه. لما يحصل خلل الساعة تلاتة الفجر، السجلات دي هي اللي بتخليك ترد على العميل في دقايق.

الاسترداد والمطابقة

خطط للاسترداد قبل الإطلاق. اعرف هل البوابة بتدعم الاسترداد الجزئي، وأنهي طرق دفع ينفع ترجعها بالـ API، وأنهي واحدة محتاجة تكلم المزود. الأرقام المرجعية النقدية في فوري مثلا بتتوصف في الأدلة العامة إنها محتاجة تدخل من الدعم في الاسترداد. وبعدها طابق التسويات: قارن اللي البوابة بتقول إنه اتسوى بإجماليات أوردراتك على جدول ثابت، علشان الرسوم والمرتجعات وفشل التحويلات تبان بدري.

الجنيه المصري وعملة العرض

لو بتعرض الأسعار بالدولار أو اليورو للزوار الأجانب وبتسوي بالجنيه، قرر فين التحويل بيحصل، ومين بيحدد السعر، وإيه اللي العميل بيشوفه في الإيصال. اختلاف المبلغ المعروض عن المبلغ المخصوم بيجيب شكاوى ومرتجعات.

خطة اختبار قبل الإطلاق

استخدم البيئة التجريبية وكروت الاختبار، وامشي على قائمة ثابتة مش عملية شراء ناجحة واحدة.

  • دفع ناجح، والأوردر ما يبقاش مدفوع إلا بعد الإشعار المتحقق منه.
  • دفع مرفوض، وعميل سابق صفحة الدفع.
  • عميل قفل المتصفح بعد ما دفع وما رجعش لموقعك أبدا.
  • نفس الإشعار اتبعت مرتين، وإشعارين وصلوا بترتيب مقلوب.
  • إشعار بتوقيع غلط، لازم يترفض ويتسجل.
  • إشعار بتوقيع صحيح لكن مبلغ مختلف.
  • استرداد جزئي وكلي بالطريقة اللي المزود بيدعمها.
  • رقم مرجعي نقدي منتهي أو تحويل غير مدفوع وصل لمدة الانتهاء.
  • الانتقال من مفاتيح الاختبار لمفاتيح التشغيل، وبعده عملية حقيقية صغيرة واحدة بترجعها.

الاختيار بين التلاتة

طريقة عملية للاختيار إنك تقيم كل مزود على قيودك انت مش على ترتيب عام. اكتب طرق الدفع اللي عملاءك بيستخدموها واتأكد إن كل واحدة مفعلة على حسابك. شوف نوع الشيك أوت اللي متجرك شغال بيه وهل فيه إضافة متحدثة له. بص على نموذج الكولباك والتحقق الموثق، واسأل المزود عن الاسترداد والتقسيط وتقارير المطابقة. اسأل عن مواعيد التسوية وشروط العقد كتابة. جمهور بيدفع كاش كتير بيشاور على Fawry، ومتجر عايز إعداد معتمد على إضافة وصفحة دفع مستضافة بيشاور على Kashier، وفريق بيبني Laravel مخصص ويحب يتحكم بالـ API كتير بيلاقي نموذج Paymob للـ intention مريح. دي نقط بداية للاختبار مش قواعد، وفيه تجار بيشغلوا بوابتين علشان عطل في واحدة ما يوقفش المبيعات.

لما المشروع فيه شيك أوت مخصص أو نظام حجز أو بوابة عملاء، التكامل جزء من تصميم النظام من أول يوم، مش إضافة في الآخر. لو عايز مراجعة معمارية لشيك أوت موجود، أو بناء بيعامل الدفع كوحدة أساسية بكولباك متحقق منها وسجلات ومطابقة، فريقنا يقدر يحدد النطاق معاك، ونبدأ من حالات الأوردر وسيناريوهات الفشل مش من اسم البوابة.

شارك:
مراجعة مجانية لموقعك

ابعتلنا موقعك وهنقولك إيه اللي معطّله على جوجل ومع الزوار.

مجاناً ومن غير أي التزام. بنبص على الصفحات اللي ظاهرة للناس بس، فمش محتاجين أي باسوورد.

المراجعة بتشمل إيه؟
لغة التقرير

التقرير بيوصلك على واتساب خلال يومين عمل

بتخطط لمشروعك الرقمي الجاي؟

قولنا أهدافك، وهنراجع احتياجاتك، ونرشحلك الطريقة المناسبة، ونبعتلك عرض سعر واضح. وبنرد خلال يوم عمل واحد.