VibeFox Paymob for PrestaShop — المساعدة

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

حساب Paymob: حساب تاجر في إحدى الدول المدعومة: مصر أو الإمارات العربية المتحدة أو المملكة العربية السعودية أو عُمان أو باكستان. تحتاج إلى أربع قيم من لوحة Paymob: API key، وintegration ID لتكامل الدفع الإلكتروني، وiFrame ID لصفحة الدفع، وHMAC secret.

العملة: يجب أن تكون عملة السلة هي عملة دولة Paymob التي تتبعها: EGP لمصر، وAED للإمارات العربية المتحدة، وSAR للمملكة العربية السعودية، وOMR لعُمان، وPKR لباكستان. مع عملة أخرى تُخفى طريقة الدفع في صفحة الدفع. حسابات Paymob متعددة العملات غير مدعومة.

مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد.

التثبيت

1. في لوحة الإدارة، انتقل إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، اضغط Configure، أو ابحث لاحقًا عن VibeFox Paymob Pay في قائمة الوحدات واضغط Configure.

3. أدخل مفتاح ترخيص VibeFox في الحقل License key داخل كتلة الترخيص أعلى صفحة Configure، ثم اضغط Activate (انظر مفتاح الترخيص).

4. اختر Paymob country وأدخل API key وintegration ID وiFrame ID وHMAC secret (انظر الإعدادات).

5. في لوحة Paymob، اضبط عناوين callback لتكاملك على العنوان الظاهر في صفحة Configure (انظر Callbacks).

6. فعّل Enable/Disable واضغط Save. اختبر دفعة بمعرّف تكامل تجريبي لدى Paymob، ثم أدخل معرّف تكاملك الفعلي.

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting Paymob payment وPaymob payment on hold. يفعّل PrestaShop وحدة دفع جديدة افتراضيًا لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences. يجب أيضًا تحديد أي دولة تفعّلها في متجرك لاحقًا هناك لهذه الوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Paymob Pay > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول تحذرك الصفحة عندما تكون إحدى القيم الأربع لدى Paymob ناقصة (وحتى ذلك الحين تكون Paymob مخفية في صفحة الدفع)، وعندما لا تقبل دولة Paymob المختارة عملة المتجر الافتراضية. يعرض مربع Callbacks عنوان callback مع زر Copy ورابطًا إلى لوحة Paymob للدولة المختارة.

Paymob

Enable/Disable: Enable Paymob يفعّل طريقة الدفع أو يعطّلها. الافتراضي: معطّل.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Paymob.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely by card or mobile wallet on the Paymob payment page. اتركه فارغًا إذا لا تريد إظهار أي نص.

حساب Paymob

جميع القيم موجودة في لوحة التاجر لدى Paymob. لا يوجد وضع اختبار منفصل: للدفعات التجريبية أدخل integration ID لتكامل في وضع الاختبار. لا تتغير أي إعدادات أخرى.

Paymob country: دولة حساب Paymob لديك. تحدد خادم واجهة البرمجة وصفحة الدفع، ويجب أن تكون عملة السلة عملة هذه الدولة. الافتراضي: Egypt.

API key: في لوحة Paymob تحت Settings > Account info > API Key.

Integration ID: في لوحة Paymob تحت Developers > Payment Integrations: المعرّف الرقمي لتكامل البطاقة أو المحفظة الإلكترونية عبر الإنترنت. طرق الدفع المعروضة في صفحة Paymob هي طرق هذا التكامل.

iFrame ID: في لوحة Paymob تحت Developers > iframes: المعرّف الرقمي لإطار الدفع iFrame.

HMAC secret: في لوحة Paymob تحت Settings > Account info > HMAC. مطلوب: لا تُنشأ الطلبات كمدفوعة إلا من استدعاءات موقّعة بهذا المفتاح.

يجب أن يحتوي Integration ID وiFrame ID على أرقام فقط. تُحذف المسافات. أي قيمة أخرى تُرفض عند الحفظ مع رسالة أن الحقل must contain digits only — the previous value was kept. تُحفظ الحقول الأخرى.

لا يُعرض API key وHMAC secret المحفوظان مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها.

Clear saved secrets: حدّد API key أو HMAC secret واضغط Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

Callbacks

تُبلغ Paymob متجرك بكل معاملة. في لوحة Paymob افتح Developers > Payment Integrations، واختر تكاملك، واضغط Edit، واضبط كلًا من Transaction processed callback وTransaction response callback على العنوان المعروض في مربع Callbacks. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_paymob_pay/callback، وربما مع رمز لغة مثل /en/. يُنشأ العنوان بلغة المتجر الافتراضية. انسخه بزر Copy. اضبط العناوين في كل تكامل تستخدمه، بما في ذلك التكامل التجريبي.

يُرسَل Transaction processed callback من خادم Paymob. ويعيد Transaction response callback العميل إلى متجرك. يُوقَّع الاثنان بـ HMAC secret الخاص بك ويتحقق منهما الوحدة. الاستدعاءات بدون توقيع صالح تُرفض ولا تغيّر شيئًا. إذا تأخر استدعاء الخادم أو ضاع، فإن عودة العميل الموقّعة تؤكد الدفع أيضًا. يعمل استدعاء الخادم أثناء وضع الصيانة للمتجر، ولا يتأثر بقيد الدول في متجرك.

متقدم

Debug log: يكتب خطوات الدفع والاستدعاءات في logs/paymob_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والاستدعاءات المرفوضة دائمًا، حتى عندما يكون الخيار معطّلًا. لا تُكتب المفاتيح والرموز ولا بيانات العملاء أبدًا. الافتراضي: معطّل.

Log: يعرض حجم السجل وأحدث إدخالاته. اضغط Clear log لتفريغه.

Clean uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وسجلاتها. تُحفظ دائمًا معرّفات Paymob المحفوظة للطلبات (محاولات الدفع) وحالات الطلبات. الافتراضي: معطّل.

صفحة الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Paymob) ويؤكد. تسجّل الوحدة طلب Paymob جديدًا بإجمالي السلة بعملة السلة، وتمرر إلى Paymob اسم العميل وبريده الإلكتروني وهاتفه وعنوان الفوترة، وترسل العميل إلى صفحة الدفع لدى Paymob في دولتك. هناك يدفع العميل بإحدى طرق تكاملك، مثل البطاقة أو المحفظة الإلكترونية. لا يوجد طلب في هذه المرحلة بعد.

بعد الدفع يعود العميل إلى متجرك. لا يُوسم الطلب مدفوعًا إلا بعد أن تؤكد Paymob الدفع بمعاملة موقّعة. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية. الدفع المعلّق (مثل النقد أو الكشك) أو الدفع المعتمد ينشئ الطلب أيضًا في حالة انتظار، ويقود إلى صفحة التأكيد.

إذا كان الطلب يُؤكَّد عبر استدعاء Paymob في اللحظة نفسها، يرى العميل صفحة تحتوي على Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. وبالنسبة إلى الدفع المعلّق يكون النص: Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. تحتوي الصفحة على زر Check again وزر Back to checkout.

إذا رُفض الدفع، يعود العميل إلى صفحة الدفع بالسلة نفسها ويرى الرسالة Your Paymob payment was not completed. Please try again or choose another payment method. تسجّل كل محاولة جديدة طلب Paymob خاصًا بها، لذلك يمكن للعميل دفع السلة مرة أخرى. وإذا تعذّر التحقق من رد Paymob، يرى العميل We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.

إذا تعذّر على Paymob بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. أو Could not connect to Paymob. Please try again in a moment. يُكتب السبب التقني في السجل.

تعالج الوحدة المدفوعات لمرة واحدة في صفحة Paymob. لا توجد بطاقات محفوظة، ولا اشتراكات، ولا نموذج بطاقة مضمّن في موقعك، ولا استرداد من لوحة الإدارة.

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى Paymob ولم يدفع، أو رُفض الدفع، أو لم تؤكد Paymob الدفع بعد. توجد السلة فقط.

Payment accepted: أكدت Paymob الدفع. يُسجَّل الدفع بمعرّف معاملة Paymob كمعرّف للمعاملة، وتعرض ملاحظة المعاملة والمبلغ ونوع البطاقة مع آخر أربعة أرقام.

Awaiting Paymob payment: الدفع معلّق لدى Paymob، مثل الدفع النقدي أو عبر الكشك. ينتقل الطلب إلى Payment accepted عندما تؤكد Paymob الدفع.

Paymob payment on hold: اعتمدت Paymob المبلغ فقط ولم تحصّله (حصّله في لوحة Paymob؛ ينتقل الطلب إلى Payment accepted عند وصول استدعاء التحصيل)؛ أو أن المبلغ المدفوع أو العملة يختلفان عن السلة (مثلًا تغيّرت السلة بعد بدء الدفع)؛ أو وصل دفع لطلب أُلغي. توضح الملاحظة السبب. راجع الطلب ونفّذه، أو استرد الدفع من لوحة Paymob.

إذا وصل دفع ناجح ثانٍ لطلب مدفوع بالفعل، لا يتغير الطلب. تطلب ملاحظة استرداد المكرر في لوحة Paymob. أما الدفع لطلب ملغى كان مدفوعًا من قبل، أو لطلب مُسترد، فيضيف ملاحظة فقط: لا يُعاد فتح الطلب. والدفع المرفوض لطلب غير مدفوع بعد يضيف ملاحظة فقط.

كتلة دفع Paymob

تعرض صفحة الطلب كتلة Paymob payment تضم كل محاولة Paymob للطلب: طلب Paymob، ومعرّف طلب التاجر والدولة، ومعرّف معاملة Paymob، والحالة، والمبلغ المطلوب، والمبلغ الذي أبلغت عنه Paymob للبطاقة، ورسالة Paymob. وتحتها Notes الوحدة لهذا الطلب.

المرتجعات

لا يُدعم الاسترداد من لوحة الإدارة. استرد الدفع أو ألغِه في لوحة Paymob. عندما تُبلغ Paymob عن استرداد أو إلغاء، تُضاف ملاحظة إلى الطلب ولا تتغير حالة الطلب. حدّث الطلب يدويًا، مثل حالته أو إشعار الائتمان (credit slip).

مفتاح الترخيص

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Paymob Pay هي أول كتلة في صفحة Modules > Module Manager > VibeFox Paymob Pay > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-paymob والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure لهذه الوحدة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تستمر الوحدة في العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. إزالة المفتاح من المتجر لا تحرّر خانة النطاق. حرّر الخانة من حسابك في vibefox.net.

بدون مفتاح نشط لا تُعرض Paymob للعملاء في صفحة الدفع. وإذا بدأت دفعة على أي حال، يرى العميل This payment method is not available. Please choose another one. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها في صفحة الدفع. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: الدفعات التي بدأت بالفعل ما زالت تُؤكَّد.

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

استكشاف الأخطاء وإصلاحها

لا تظهر Paymob في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن القيم الأربع (API key وintegration ID وiFrame ID وHMAC secret) مملوءة، وأن عملة السلة هي عملة Paymob country المختارة. تعرض صفحة الإعدادات تحذيرًا عند نقص أي شيء. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

اكتمل الدفع لكن لم يُنشأ طلب: الاستدعاءات لا تصل إلى متجرك. تحقق من أن Transaction processed callback وTransaction response callback للتكامل الذي تستخدمه مطابقان تمامًا للعنوان المعروض في مربع Callbacks، وأن HMAC secret يعود إلى الحساب نفسه لدى Paymob. تُكتب الاستدعاءات المرفوضة في السجل كتحذيرات، حتى عندما يكون Debug log معطّلًا. انظر حقل Log في صفحة الوحدة.

يرد الاستدعاء بـ Invalid signature: HMAC secret في الإعدادات لا يطابق حساب Paymob، أو أن حساب دولة أخرى مختار. انسخ HMAC secret مرة أخرى.

يرد الاستدعاء بـ Not configured: HMAC secret فارغ. أدخل المفتاح السري؛ وستعيد Paymob محاولة الاستدعاء.

يرد الاستدعاء بـ locked أو retry: كان الطلب يُحدَّث بطلب آخر في اللحظة نفسها، مثل عودة العميل، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة). ستعيد Paymob محاولة الاستدعاء. يُكتب السبب في السجل.

فتح عنوان الاستدعاء في المتصفح يقود إلى صفحة الدفع مع رسالة could not verify: هذا طبيعي. العنوان يقبل فقط الطلبات الموقّعة من Paymob.

يرى العميل خطأً عند اختيار Paymob: فعّل Debug log وراجع السجل. تعني Paymob payments are temporarily unavailable مفتاح API خاطئًا أو قيمة ناقصة. تعني Paymob could not start the payment أن Paymob رفض الطلب، مثلًا بسبب integration ID خاطئ أو بيانات فوترة غير مكتملة. تعني This order cannot be paid with Paymob أن إجمالي الطلب صفر. تعني Paymob does not accept payments in متبوعةً بعملة أن عملة السلة ليست عملة دولة Paymob المختارة.

الطلب في حالة Paymob payment on hold أو Awaiting Paymob payment بعد الدفع: اقرأ الملاحظات في كتلة Paymob payment. الدفع معلّق (نقدًا أو عبر الكشك)، أو المعاملة اعتُمدت فقط (حصّلها في لوحة Paymob)، أو لم يتطابق المبلغ أو العملة، أو وصل الدفع بعد إلغاء الطلب.

الدفعات التجريبية: أدخل معرّف تكامل تجريبي لدى Paymob في Integration ID، واضبط عناوين callback في ذلك التكامل. للدفعات الحقيقية أعد إدخال معرّف تكاملك الفعلي.

إلغاء التثبيت

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Paymob Pay، واختر Uninstall. تُحذف دائمًا مفتاح الترخيص وحالة الترخيص الخاصتان بهذه الوحدة. إذا كان Clean uninstall مفعّلًا تُحذف إعدادات الوحدة والسجل. وإذا كان معطّلًا تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ دائمًا محاولات دفع Paymob للطلبات وحالتا الطلب Awaiting Paymob payment وPaymob payment on hold. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات ومعرّفات Paymob الخاصة بها.

Paymob علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Paymob ولا تحظى بتأييدها.