الدفع الإلكتروني في العراق: خيارات ربط التطبيقات والمتاجر

الخيارات المتاحة

الشروط والرسوم وطرق الربط تتغير؛ تحقق منها مباشرة مع كل مزود قبل التخطيط النهائي.

• المحافظ الإلكترونية على الجوال (مثل ZainCash وFastPay).
• البطاقات المحلية (مثل Qi Card) عبر بوابات الدفع.
• الدفع عند الاستلام: يبقى ضروريًا لشريحة كبيرة من الزبائن.
• التحويل المسبق للطلبات الكبيرة أو الجملة.

كي كارد وFastPay والبطاقات والدفع عند الاستلام: ما يجب معرفته

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

• كي كارد (Qi Card): بطاقة منتشرة بين شريحة واسعة من الناس، ويتطلب قبولها في متجرك حساب تاجر واتفاقًا مع الجهة المزودة لبوابة الدفع. اسأل المزود إن كانت صفحة الدفع مستضافة لديه، فهذا يعفيك من التعامل مع بيانات البطاقة مباشرة على خادمك.
• بطاقات Visa وMastercard: تصدرها بنوك عراقية أيضًا، ويحتاج قبولها إلى بوابة أو مزود دفع يدعم هذه البطاقات. فعّل التحقق الإضافي مثل 3-D Secure إن كان المزود يوفره لتقليل الاحتيال.
• FastPay: محفظة إلكترونية على الجوال يمكن للتاجر استقبال المدفوعات عبرها. طرق الاستقبال وشروط حساب التاجر تحددها الشركة، فاطلب وثائقها الحالية قبل التخطيط للربط.
• الدفع عند الاستلام: لا يحتاج ربطًا تقنيًا مع مزود، لكنه يحتاج نظامًا: تأكيد الطلب قبل الشحن بمكالمة أو رسالة واتساب، وتتبع النقد مع المندوب أو شركة التوصيل، وتسوية يومية، وتسجيل الطلبات المرفوضة عند الباب لمعرفة أسبابها.
• التحويل المسبق: مناسب للجملة والطلبات الكبيرة. أضف في النظام حالة «بانتظار تأكيد التحويل» وطريقة لرفع إثبات الدفع ومراجعته يدويًا قبل تجهيز الطلب.

خطوات التفعيل

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

ربط ZainCash API: ما تحتاجه وخطوات الدفع والأخطاء الشائعة

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

قبل كتابة أي كود تحتاج إلى: حساب تاجر مفعّل لدى زين كاش باسم شركتك، وبيانات الاعتماد الخاصة بالتاجر (مثل معرّف التاجر والمفتاح السري)، وبيئة اختبار منفصلة ببيانات تجريبية للتجربة قبل التشغيل الفعلي، وخادم خلفي (Backend) خاص بك. المفتاح السري يبقى على الخادم فقط؛ لا تضعه أبدًا داخل تطبيق الجوال أو كود الموقع الأمامي، لأن أي شخص يستطيع استخراجه منهما.

مسار الدفع المعتاد يمر بالمراحل التالية:

• ينشئ خادمك طلب معاملة موقّعًا بالمفتاح السري، يحتوي المبلغ بالدينار العراقي ورقمًا مرجعيًا فريدًا للطلب ورابط العودة (Redirect URL) إلى موقعك.
• يرسل خادمك الطلب إلى زين كاش ويستلم معرّف معاملة (Transaction ID) يحفظه مع الطلب في قاعدة البيانات بحالة «بانتظار الدفع».
• يُوجَّه الزبون إلى صفحة الدفع الخاصة بزين كاش، فيدخل رقم محفظته ورمزه السري (PIN) ثم رمز التحقق (OTP) الذي يصله لتأكيد العملية.
• بعد الدفع أو الإلغاء تعيد زين كاش الزبون إلى رابط العودة ومعه رمز (Token) موقّع يحمل نتيجة العملية.
• يتحقق خادمك من توقيع الرمز بالمفتاح السري ويقرأ الحالة ورقم الطلب، ولا يعلّم الطلب «مدفوعًا» إلا إذا كانت الحالة ناجحة والمبلغ ورقم الطلب مطابقين لما أنشأه.
• للتسوية والمطابقة يمكن لخادمك الاستعلام عن حالة المعاملة لاحقًا حسب ما تتيحه الواجهة، خصوصًا للطلبات التي بقيت معلّقة.

مخطط الطلب والاستجابة في ربط زين كاش

المخطط التالي يبين من يرسل ماذا إلى من، وبأي ترتيب، في عملية دفع واحدة عبر زين كاش. اقرأ كل سطر على أنه رسالة بين طرفين: تطبيق الزبون أو متصفحه، وخادمك، وزين كاش. تعمدنا ألا نذكر أسماء حقول أو عناوين واجهات بعينها، لأنها تختلف بين إصدارات الواجهة؛ وعند تحديث هذا القسم يوم 2026-10-14 لم يكن موقع وثائق المطورين لدى زين كاش متاحًا لنا للمراجعة، فخذ التفاصيل التقنية من أحدث وثائق يسلّمها لك المزود مع بيانات التاجر.

• الخطوة 1 — تطبيق الزبون ← خادمك: «أريد دفع الطلب رقم كذا». يرسل التطبيق رقم الطلب فقط، ولا يُعتمد على أي مبلغ يأتي من الواجهة.
• الخطوة 2 — خادمك: يقرأ المبلغ من قاعدة البيانات، وينشئ رقمًا مرجعيًا فريدًا لمحاولة الدفع، ويوقّع طلب المعاملة بالمفتاح السري.
• الخطوة 3 — خادمك ← زين كاش: طلب إنشاء معاملة يحمل المبلغ بالدينار والرقم المرجعي ورابط العودة.
• الخطوة 4 — زين كاش ← خادمك: معرّف المعاملة عند النجاح، أو رد خطأ. يحفظ خادمك المعرّف مع الطلب بحالة «بانتظار الدفع»، ويسجّل أي خطأ دون المفتاح السري.
• الخطوة 5 — خادمك ← متصفح الزبون: توجيه إلى صفحة دفع زين كاش الخاصة بهذه المعاملة.
• الخطوة 6 — الزبون ↔ زين كاش: يدخل رقم محفظته ورمزه السري، ثم رمز التحقق الذي يصله، أو يلغي العملية.
• الخطوة 7 — زين كاش ← متصفح الزبون ← خادمك: إعادة الزبون إلى رابط العودة ومعه رمز موقّع يحمل نتيجة العملية.
• الخطوة 8 — خادمك: يتحقق من توقيع الرمز بالمفتاح السري، ثم يطابق الرقم المرجعي والمبلغ والحالة مع ما أنشأه. إن فشل أي فحص يرفض النتيجة ويبقي الطلب معلّقًا.
• الخطوة 9 — خادمك ← زين كاش، عند الحاجة: استعلام عن حالة المعاملة للطلبات التي لم يعد أصحابها، حسب ما تتيحه الواجهة.
• الخطوة 10 — خادمك ← الزبون: صفحة تأكيد أو رسالة فشل، وإشعار بالطلب، ثم يبدأ التجهيز للطلبات المدفوعة فقط.

أخطاء ربط ZainCash API الشائعة وكيف تتجنبها

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

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

نصيحة أمان مهمة

لا تعتمد أبدًا على رسالة «تم الدفع» القادمة من تطبيق الزبون. يجب أن يتحقق خادمك من العملية مع مزود الدفع مباشرة قبل تجهيز الطلب؛ هذا يمنع أغلب محاولات الاحتيال.

جهّز متجرك أو تطبيقك للدفع الإلكتروني

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