أصبح توفير الدفع الإلكتروني خطوة أساسية لأي متجر أو منصة أو تطبيق يستقبل طلبات من العملاء داخل مصر. لكن اختيار بوابة الدفع لا يتوقف على اسم الشركة أو عدد وسائل الدفع فقط، بل يعتمد أيضًا على طريقة التكامل، وسهولة استخدام واجهة API، ودعم الإشعارات، ووضوح التوثيق، وسرعة تسوية المدفوعات.
إذا كان لديك موقع مخصص أو تطبيق هاتف أو نظام داخلي، فقد تحتاج إلى ربط بوابة الدفع API في مصر بدل الاعتماد على إضافة جاهزة فقط. يتيح لك التكامل عبر API التحكم في رحلة الدفع، وربط نتيجة المعاملة بالطلب، وتحديث حالة الفاتورة أو الاشتراك أو الشحنة تلقائيًا.
في هذا الدليل سنشرح معنى ربط بوابة الدفع عبر API، ونوضح خطوات التنفيذ، ثم نستعرض ثلاث حلول معروفة في السوق المصري: Paymob، وKashier، وFawry Accept. المقارنة هنا مبنية على المعلومات المنشورة في الصفحات الرسمية للشركات، بينما تختلف الرسوم وشروط القبول حسب النشاط وحجم العمليات والعقد التجاري.
ما المقصود بربط بوابة الدفع API؟
واجهة API هي طريقة منظمة تسمح لموقعك أو تطبيقك بالتواصل مع بوابة الدفع. فعند ضغط العميل على زر الدفع، يرسل نظامك طلبًا إلى البوابة لإنشاء عملية أو جلسة دفع، ثم يحصل على رابط دفع أو رمز جلسة أو نتيجة يمكن استخدامها لإكمال العملية.
بعد إتمام العميل للدفع، تعيد البوابة النتيجة إلى نظامك من خلال إعادة توجيه أو إشعار Server-to-Server يسمى غالبًا Webhook أو Callback. يستخدم نظامك هذه النتيجة لتحديث الطلب إلى مدفوع أو مرفوض أو قيد المراجعة.
وتوضح [MDN أن التواصل بين العميل والخادم يعتمد على طلبات واستجابات HTTP] ، وهي القاعدة التي تعمل من خلالها كثير من واجهات الدفع على الويب. لذلك فإن ربط بوابة الدفع ليس مجرد وضع زر داخل صفحة، بل هو دورة متكاملة تشمل إنشاء المعاملة، والتحقق، وتحديث الطلب، ومعالجة الأخطاء.
متى تحتاج إلى API بدل الإضافة الجاهزة؟
استخدم API عندما يكون موقعك مخصصًا
إذا كان الموقع مبنيًا بإطار مثل Laravel أو Node.js أو Django أو PHP مخصص، فقد تحتاج إلى استدعاء API مباشرة بدل تركيب إضافة مصممة لمنصة محددة.
استخدم API عند تطوير تطبيق هاتف
تحتاج تطبيقات Android وiOS غالبًا إلى ربط آمن مع خادم خلفي ينشئ عملية الدفع ويتابع نتيجتها. ولا يُنصح بوضع المفاتيح السرية داخل التطبيق نفسه.
استخدم API عند وجود دورة عمل خاصة
قد تحتاج الشركة إلى ربط الدفع بفاتورة أو اشتراك أو حجز أو طلب شحن أو نظام CRM. يسمح التكامل البرمجي بربط حالة الدفع بالعملية التجارية الكاملة.
استخدم الإضافة الجاهزة عندما يكون المتجر على منصة مدعومة
إذا كان متجرك يعمل على WooCommerce أو Shopify أو Magento وكانت بوابة الدفع توفر إضافة رسمية مناسبة، فقد تكون الإضافة أسرع في الإطلاق وأقل تعقيدًا. ويمكن الانتقال إلى API مخصص لاحقًا إذا ظهرت احتياجات لا تغطيها الإضافة.
كيف تتم عملية ربط بوابة الدفع API؟
تختلف أسماء الخطوات من بوابة إلى أخرى، لكن التدفق العام يكون قريبًا من الآتي:
1.إنشاء حساب تاجر وإرسال المستندات المطلوبة للمراجعة.
2.الحصول على مفاتيح الاختبار من بيئة Sandbox.
3.إنشاء طلب أو جلسة دفع من الخادم الخلفي.
4.إرسال قيمة الطلب والعملة وبيانات العميل ومعرف العملية.
5.فتح صفحة الدفع المستضافة أو تضمين نموذج الدفع وفق طريقة البوابة.
6.استقبال نتيجة الدفع من خلال Webhook أو Callback.
7.التحقق من توقيع الإشعار أو الاستجابة من الخادم.
8.تحديث الطلب مرة واحدة فقط لمنع تكرار الشحن أو إصدار الفاتورة.
9.حفظ رقم المعاملة وتسجيل النتيجة لأغراض الدعم والمطابقة المالية.
10.اختبار عمليات النجاح والرفض والإلغاء والاسترداد قبل الانتقال إلى Live.
مثال مبسط لتدفق التكامل
Plain Text
العميل يضغط على الدفع ↓ الخادم ينشئ Payment Session أو Payment Intention ↓ البوابة تعيد رابط أو رمز الدفع ↓ العميل يكمل الدفع ↓ البوابة ترسل Webhook إلى الخادم ↓ الخادم يتحقق من الإشعار ويحدّث حالة الطلب
يجب أن تتم خطوات إنشاء المعاملة والتحقق من النتيجة على الخادم الخلفي، وليس في الواجهة الأمامية فقط، حتى لا يستطيع المستخدم تعديل قيمة الطلب أو اعتبار العملية ناجحة دون تحقق حقيقي.
مقارنة بين Paymob وKashier وFawry Accept
البوابة | طرق التكامل المعلنة | أمثلة على وسائل الدفع أو الخدمات | مناسبة أكثر لـ |
APIs وإضافات جاهزة وiFrames ونماذج طبيعية | البطاقات، المحافظ، التقسيط، روابط الدفع، وخيارات دفع أخرى | المتاجر والمواقع والتطبيقات التي تريد API أو إضافة جاهزة | |
API مباشر، Payment Sessions، Hosted Checkout، Webhooks، إضافات | البطاقات، المحافظ، روابط الدفع، POS، Apple Pay والاشتراكات وفق الحل المستخدم | المشاريع التي تحتاج مسارات تكامل متعددة وبيئة اختبار | |
تكامل مباشر مع الموقع أو إضافة لمنصات التجارة الإلكترونية | البطاقات، كود فوري، المحافظ، التقسيط، الدفع عند الاستلام وخيارات أخرى | الأنشطة التي تريد قبول وسائل دفع متنوعة وتقارير وتسوية مركزية |
مهم: الجدول للمقارنة الأولية فقط. تحققي من توافر طريقة الدفع والرسوم ومدة التسوية وشروط قبول نشاطك قبل توقيع العقد.
أولًا: ربط Paymob API في مصر
تقدم Paymob حلول دفع إلكتروني للتجار والمتاجر، وتذكر في صفحتها الرسمية دعم بطاقات الائتمان والخصم، والمحافظ الإلكترونية، والتقسيط، وروابط الدفع، وبعض خيارات الدفع الأخرى. كما تذكر توفير APIs وإضافات لمنصات مثل WooCommerce وShopify وMagento وOpenCart وWix.
متى تكون Paymob مناسبة؟
قد تكون Paymob مناسبة إذا كنت تريد الجمع بين التكامل المخصص والإضافات الجاهزة. فالمتجر الذي يعمل على منصة مدعومة يمكنه البدء بإضافة، بينما يستطيع الموقع المخصص استخدام API وفق دورة الدفع المطلوبة.
وتوضح وثائق Paymob الخاصة بالتكامل عبر APIs أن هذا المسار يناسب المواقع المخصصة، والمنصات التي لا تملك تكاملًا مباشرًا، وتطبيقات الهاتف التي تستخدم Checkout قائمًا على الويب.
ما الذي يجب تحديده قبل تكامل Paymob؟
قبل بدء التطوير، حدد طريقة Checkout المطلوبة، وأسلوب استقبال نتيجة الدفع، والوسائل التي تريد تفعيلها، وطريقة ربط رقم المعاملة برقم الطلب داخل نظامك. كما يجب اختبار حالات الدفع المرفوض أو الملغى، وعدم الاعتماد على صفحة العودة وحدها لتأكيد العملية.
ثانيًا: ربط Kashier API في مصر
تقدم Kashier منصة دفع إلكتروني وحلولًا للتجارة الإلكترونية، وتعرض على موقعها مسارات تشمل التجارة الإلكترونية، وواجهات API وSDK، وروابط الدفع، والمدفوعات داخل المتجر، والاشتراكات، والمدفوعات المتكررة.
وتوضح وثائق Kashier الرسمية أكثر من طريقة للتكامل، منها Payment Sessions أو Hosted Checkout، والتكامل المباشر عبر API، وإضافات منصات التجارة الإلكترونية، وWebhooks، بالإضافة إلى بيئة اختبار قبل الانتقال إلى المدفوعات الحقيقية.
ما الفرق بين Payment Session وDirect API في Kashier؟
•Payment Session أو Hosted Checkout: ينشئ الخادم جلسة دفع ويعيد رابطًا لصفحة دفع مستضافة أو مضمّنة. هذا المسار أبسط نسبيًا ويقلل حجم واجهة الدفع التي تحتاج إلى بنائها.
•Direct API: يمنح تحكمًا أكبر في نموذج الدفع والتوكنز و3D Secure والمحافظ والتقسيط، لكنه يحتاج إلى تطوير واختبار أكثر، وقد يرفع مسؤوليات المشروع المتعلقة بنطاق PCI DSS وفق طريقة التنفيذ.
•Plugins: مناسبة للمتاجر التي تستخدم منصة مدعومة ولا تحتاج إلى منطق دفع مخصص.
•Webhooks: تستخدم لاستقبال إشعارات الخادم عند تغير حالة الدفع.
متى تختار Kashier؟
قد تكون Kashier مناسبة إذا كنت تريد البدء بجلسة دفع سريعة، أو تحتاج لاحقًا إلى تكامل أعمق عبر API مباشرة، أو تريد اختبار دورة الدفع في بيئة منفصلة قبل الإطلاق.
ثالثًا: ربط Fawry Accept API في مصر
تقدم Fawry Accept خدمة الدفع الإلكتروني للمتاجر والمواقع، وتذكر صفحتها الرسمية إمكانية ربط بوابة الدفع بالموقع أو استخدام إضافة متوافقة مع منصات التجارة الإلكترونية.
ومن وسائل الدفع التي تعرضها Fawry Accept: البطاقات، وكود الدفع عبر فوري، والتقسيط البنكي، والمحافظ الإلكترونية، والدفع عند الاستلام، وخيارات أخرى تختلف حسب تفعيل الخدمة والنشاط.
مميزات يجب تقييمها في Fawry Accept
تذكر الصفحة الرسمية وجود لوحة تحكم وتقارير، وخيارات تكامل متعددة، ومدفوعات متكررة، وتوكنة البطاقات، وتقسيم المدفوعات، وخدمات حماية من الاحتيال. كما تذكر أن الخدمة خاضعة لمتطلبات الجهات المحلية ومعايير أمن الدفع وفق المعلومات المنشورة على الصفحة.
قبل الاختيار، اسأل عن طريقة API المتاحة لنوع مشروعك، وصيغة الإشعارات، وعمليات الاسترداد، وطريقة المطابقة بين أرقام الطلبات وأرقام المعاملات.
كيف تختار بوابة الدفع المناسبة لمشروعك؟
لا توجد بوابة واحدة هي الأفضل لكل المواقع. الاختيار يعتمد على نوع النشاط، والمنصة، ووسائل الدفع المطلوبة، وحجم العمليات، وطريقة التسوية.
1. حدد وسائل الدفع التي يحتاج إليها عملاؤك
هل تحتاج إلى البطاقات فقط؟ أم المحافظ الإلكترونية؟ أم كود دفع نقدي؟ أم التقسيط؟ أم الدفع عند الاستلام؟ لا تفترض أن توافر وسيلة في السوق يعني أنها مفعّلة تلقائيًا لحسابك، بل اطلب تأكيدًا مكتوبًا من فريق المبيعات.
2. قارن طرق التكامل
إذا كان موقعك مخصصًا، راجع وثائق API، وطريقة المصادقة، وأمثلة الطلبات، ووجود SDK أو مكتبات مناسبة للغة البرمجة. وإذا كان متجرك على WooCommerce أو Shopify، تحقق من وجود إضافة رسمية محدثة.
3. افحص بيئة الاختبار
يجب أن توفر البوابة طريقة لاختبار الدفع دون تحريك أموال حقيقية. اختبر النجاح والرفض والإلغاء، والطلبات المكررة، وانقطاع الاتصال، ووصول Webhook متأخرًا.
4. اسأل عن التسوية والمطابقة
تحقق من العملة، وجدول التسوية، والتقارير، والحد الأدنى للتحويل إن وجد، وطريقة التعامل مع الاسترداد والنزاعات. هذه التفاصيل تؤثر في التدفق النقدي أكثر من شكل صفحة الدفع.
5. راجع الدعم والتوثيق
توثيق واضح ومحدث يقلل وقت التطوير. كما يجب معرفة قناة الدعم الفني، ومدة الرد، وطريقة الحصول على المساعدة عند فشل عملية أو تغير إصدار API.
6. راجع متطلبات نشاطك القانوني والتجاري
قد تحتاج إلى سجل تجاري وبطاقة ضريبية وحساب بنكي ومستندات تخص النشاط. تختلف المتطلبات حسب نوع الشركة والمنتجات والجهة المقدمة للخدمة، لذلك لا تبدأ التطوير النهائي قبل معرفة شروط قبول الحساب.
ما تكلفة ربط بوابة الدفع API في مصر؟
تنقسم التكلفة عادة إلى جانبين:
رسوم مزود خدمة الدفع
قد تشمل رسوم فتح الحساب أو التفعيل أو نسبة من كل عملية أو رسومًا ثابتة أو تكلفة تسوية أو رسوم استرداد. لا يمكن تعميم رقم واحد، لأن العرض يعتمد على نشاطك وحجم المبيعات ووسائل الدفع والتفاوض التجاري.
تكلفة التطوير والتكامل
تعتمد تكلفة البرمجة على المنصة المستخدمة، وعدد طرق الدفع، وهل ستستخدم Hosted Checkout أم Direct API، وعدد الأنظمة التي يجب تحديثها بعد الدفع، وحجم الاختبارات، ومتطلبات التقارير والاسترداد.
ومن الأفضل طلب عرض يوضح بشكل منفصل رسوم البوابة وتكلفة التطوير والصيانة. ويمكنك مراجعة خدمة برمجة المواقع والتكامل مع بوابات الدفع والأنظمة الخارجية من ستورك للتعرف على نطاق العمل البرمجي المرتبط بواجهات API وقواعد البيانات.
متطلبات الأمان عند ربط بوابة الدفع
تتعامل بوابة الدفع مع معلومات مالية وبيانات شخصية، لذلك يجب أن يكون الأمان جزءًا من التصميم وليس خطوة بعد الإطلاق.
•استخدم HTTPS في الموقع والخادم.
•خزّن مفاتيح API في إعدادات الخادم أو مدير أسرار، ولا تضعها في كود الواجهة الأمامية.
•استخدم مفاتيح منفصلة لبيئة الاختبار وبيئة الإنتاج.
•تحقق من توقيع Webhook أو آلية التحقق التي تحددها البوابة.
•لا تعتبر وصول العميل إلى صفحة النجاح إثباتًا نهائيًا للدفع.
•اربط كل عملية بمعرف فريد لمنع تكرار إصدار الفاتورة أو الشحن.
•سجّل رقم المعاملة وحالتها دون تخزين بيانات البطاقة الحساسة.
•طبّق صلاحيات محدودة على المستخدمين والأنظمة المتصلة.
•راقب العمليات الفاشلة والطلبات غير المعتادة.
•حدّث مكتبات التكامل وتابع تغييرات إصدار API.
ويعرض [مشروع OWASP لأمن واجهات API] المخاطر الشائعة عند بناء واجهات تتعامل مع بيانات حساسة، لذلك يجب اختبار المصادقة والصلاحيات والتحقق من المدخلات قبل الإطلاق.
أخطاء شائعة في ربط بوابة الدفع
الاعتماد على Callback من المتصفح فقط
قد يغلق العميل الصفحة أو ينقطع الاتصال بعد إتمام الدفع. لذلك يجب الاعتماد على إشعار خادم موثوق أو الاستعلام الآمن عن حالة المعاملة، وليس على عودة المتصفح وحدها.
وضع المفاتيح السرية في JavaScript
كل ما يصل إلى المتصفح يمكن للمستخدم الاطلاع عليه. يجب أن تبقى المفاتيح السرية وعمليات إنشاء المعاملة على الخادم.
عدم منع تكرار الطلبات
قد يؤدي إعادة إرسال الطلب إلى إنشاء عمليتين أو شحنتين. استخدم معرفًا فريدًا للعملية وآلية تجعل تحديث الطلب قابلًا للتكرار بأمان.
تجاهل الاسترداد والإلغاء
يجب تصميم دورة الدفع لتتعامل مع الاسترداد الجزئي والكلي، وفشل التسوية، وإلغاء الطلب، ورفض العملية، وليس فقط حالة النجاح.
عدم اختبار المدفوعات المتأخرة
قد يصل Webhook بعد عدة دقائق أو يصل بعد تغير حالة الطلب. صمّم النظام ليتعامل مع التأخير والتعارض دون فقدان العملية أو تحديثها بشكل غير صحيح.
مقارنة الأسعار دون حساب التكلفة الكلية
الرسوم ليست العامل الوحيد. أضف تكلفة التطوير، والصيانة، والإضافات، والاستردادات، والدعم، والتسوية، ووقت الفريق المطلوب لإدارة العمليات.
خطوات عملية قبل بدء البرمجة
1.اكتب وسائل الدفع المطلوبة ونوع العملاء والدول المستهدفة.
2.حدد المنصة: متجر جاهز، موقع مخصص، تطبيق، أو نظام داخلي.
3.اطلب عروضًا من Paymob وKashier وFawry Accept أو البدائل المناسبة.
4.اطلب وثائق API وبيانات Sandbox قبل توقيع نطاق التطوير.
5.صمّم دورة الطلب من الإنشاء حتى الدفع والاسترداد.
6.حدد Webhook أو Callback وطريقة التحقق من النتيجة.
7.نفّذ التكامل على بيئة اختبار منفصلة.
8.اختبر الحالات الطبيعية والاستثنائية.
9.راجع التقارير والتسوية مع فريق الحسابات.
10.انتقل إلى الإنتاج بعد تأكيد الحساب والمفاتيح ونطاق الدعم.
أسئلة شائعة عن ربط بوابة الدفع API في مصر
ما أفضل بوابة دفع API في مصر؟
لا توجد إجابة واحدة تناسب كل الأنشطة. قد تكون Paymob أو Kashier أو Fawry Accept مناسبة بحسب وسائل الدفع المطلوبة، والمنصة، وطريقة التكامل، والدعم، والتسوية. قارن عرض كل بوابة بعد معرفة نشاطك وحجم عملياتك.
هل يمكن ربط Paymob أو Kashier بمتجر WooCommerce؟
تذكر Paymob رسميًا توفير إضافات لمنصات منها WooCommerce وShopify وMagento وOpenCart وWix. وتذكر Kashier توفير إضافات لمنصات تجارة إلكترونية متعددة. يجب التأكد من الإصدار المدعوم وتوافق الإضافة مع قالب المتجر وإعداداته قبل التثبيت.
هل API أفضل من الإضافة الجاهزة؟
API تمنحك تحكمًا أكبر وتناسب المواقع والتطبيقات المخصصة، بينما الإضافة الجاهزة أسرع وأبسط إذا كانت تغطي احتياجات منصتك. الاختيار يعتمد على مستوى التخصيص المطلوب وموارد التطوير.
هل ربط بوابة الدفع يحتاج إلى مطور؟
الإضافة الجاهزة قد تحتاج إلى إعداد تقني محدود، لكن التكامل عبر API يحتاج عادة إلى مطور يفهم الخادم وقواعد البيانات والمصادقة ومعالجة Webhooks وأمان المعاملات.
هل أستطيع اختبار التكامل قبل تفعيل الحساب الحقيقي؟
نعم، توفر بعض البوابات بيئة اختبار أو مفاتيح Sandbox. استخدمها لبناء التكامل وتجربة الحالات المختلفة، ثم اطلب تفعيل Live بعد اكتمال مراجعة النشاط والمستندات.
هل يمكن ربط بوابة الدفع بتطبيق هاتف؟
نعم، لكن الأفضل أن تتم العمليات الحساسة عبر خادم خلفي. يمكن للتطبيق طلب إنشاء جلسة دفع من الخادم، ثم عرض تجربة الدفع المناسبة، وبعدها يستقبل الخادم نتيجة المعاملة ويتحقق منها.
هل يجب أن تكون الشركة مسجلة؟
تختلف مستندات القبول حسب مزود الخدمة ونوع النشاط. قد تُطلب مستندات قانونية وبيانات بنكية وبيانات عن المنتجات أو الخدمات. اسأل البوابة مباشرة قبل الاعتماد على قائمة ثابتة.
الخلاصة
يمنحك ربط بوابة الدفع API في مصر قدرة أكبر على دمج الدفع داخل الموقع أو التطبيق وربط النتيجة بالطلبات والفواتير والاشتراكات والشحن وCRM. وتوفر Paymob وKashier وFawry Accept مسارات مختلفة تشمل API أو Checkout مستضافًا أو إضافات جاهزة، لكن الاختيار الصحيح يعتمد على احتياجات مشروعك وليس على الاسم وحده.
ابدأ بتحديد وسائل الدفع المطلوبة، ثم راجع التوثيق وبيئة الاختبار والتسوية والدعم والأمان. وبعد اختيار البوابة، نفّذ التكامل على الخادم، وتحقق من Webhooks، واختبر كل حالات الدفع قبل الإطلاق.
إذا كنت تحتاج إلى ربط بوابة دفع بموقع أو متجر أو تطبيق، يمكنك التواصل مع ستورك لعرض متطلبات مشروعك والحصول على تصور فني لنطاق التكامل.
