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

المتطلبات

WordPress: 6.2 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع المجلد wcp_paymob_pay إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > Paymob > Manage، أو انقر على Settings أسفل اسم الإضافة في صفحة Plugins.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، ثم انقر على Activate.

5. اختر Paymob country وأدخل مفتاح API ومعرّف التكامل ومعرّف iFrame ومفتاح HMAC السري (انظر قسم الإعداد).

6. في لوحة تحكم Paymob، اضبط عناوين URL لـ callback الخاصة بتكاملك لتكون العنوان الظاهر في صفحة الإعدادات (انظر قسم Callbacks).

7. فعّل Enable/Disable. اختبر دفعة باستخدام معرّف تكامل تجريبي من Paymob، ثم أدخل معرّف التكامل الفعلي.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Paymob. تعرض الصفحة فوق الحقول تحذيرًا عند غياب أي من القيم الأربع لـ Paymob (وإلى أن تُملأ، لا تظهر Paymob في صفحة الدفع)، وعند عدم قبول دولة Paymob المختارة لعملة المتجر. يعرض مربع عنوان callback مع زر Copy، ورابطًا إلى لوحة تحكم Paymob للدولة المختارة.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Paymob.

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

حساب Paymob

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

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. حقل إلزامي: لا تُعلَّم الطلبات كمدفوعة إلا عبر callbacks موقّعة بهذا المفتاح السري.

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

Callbacks

تبلغ Paymob متجرك بكل معاملة. في لوحة تحكم Paymob، افتح Developers > Payment Integrations، واختر تكاملك، وانقر على Edit، ثم اضبط كلًا من Transaction processed callback وTransaction response callback ليكون العنوان الظاهر في صفحة الإعدادات. يبدو العنوان هكذا: https://your-site/wc-api/paymob_pay/. انسخه باستخدام زر Copy. اضبط العناوين في كل تكامل تستخدمه، بما في ذلك التكامل التجريبي.

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

متقدم

Debug log: يكتب Log payment steps and callbacks خطوات الدفع والـ callbacks في WooCommerce > Status > Logs، بالمصدر wcp_paymob_pay. تُسجَّل الأخطاء والـ callbacks المرفوضة دائمًا. لا تُكتب المفاتيح أو الرموز أو بيانات العملاء أبدًا. الافتراضي: معطّل.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف أي شيء أبدًا. تبقى معرّفات Paymob المحفوظة على الطلبات. الافتراضي: معطّل.

الدفع

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

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Paymob ذلك بمعاملة موقّعة. والدفعة المكتملة أو المعلّقة أو المعتمَدة تنقل العميل إلى صفحة استلام الطلب.

إذا رُفض الدفع، يعود العميل إلى صفحة الدفع (أو إلى صفحة Pay for order إذا بدأ الدفع فيها) مع الرسالة 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. ويُكتب السبب التقني في السجل.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وفي صفحة Pay for order يُتحقق من عملة الطلب بدلًا من عملة المتجر. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى Paymob ولم يدفع بعد، أو لم تؤكد Paymob الدفع بعد.

Processing: أكدت Paymob الدفع. تتحول الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى حالة مكتمل، وهي الحالة الافتراضية في WooCommerce. تعرض ملاحظة الطلب معاملة Paymob والمبلغ ونوع البطاقة مع آخر أربعة أرقام منها. معرّف المعاملة هو معرّف المعاملة في Paymob.

On hold: الدفع معلّق لدى Paymob، مثل دفعة نقدية أو عبر كشك؛ أو أن Paymob اعتمدت المبلغ فقط ولم تحصّله (حصّله من لوحة تحكم Paymob، ويكتمل الطلب عند وصول callback التحصيل)؛ أو أن المبلغ المدفوع أو العملة يختلفان عن الطلب؛ أو وصلت دفعة لطلب أُلغي. توضح ملاحظة الطلب السبب.

Failed: رفضت Paymob دفع طلب معلّق. يمكن للعميل الدفع مرة أخرى.

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

الاستردادات

الاستردادات من WooCommerce غير مدعومة. استرد الدفعة أو ألغها من لوحة تحكم Paymob. عندما تبلغ Paymob عن استرداد أو إلغاء، تُضاف ملاحظة إلى الطلب، ولا تتغير حالة الطلب. حدّث الطلب يدويًا، مثلًا بإجراء استرداد يدوي في WooCommerce.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. تقع كتلة الترخيص أعلى صفحة WooCommerce > Settings > Payments > Paymob. الصق المفتاح في License key وانقر على Activate. تعرض الكتلة الحالة، مثل تاريخ انتهاء الترخيص ونطاقك. استخدم Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك على vibefox.net.

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

من دون مفتاح نشط، لا تظهر Paymob للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل الرسالة This payment method is not available. Please choose another one. ويظل مديرو المتجر المسجلون الدخول يرون طريقة الدفع، مع الوسم (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. يظهر تذكير في صفحة Plugins وفي صفحات WooCommerce. ولا تتأثر الطلبات الحالية: فالدفعات التي بدأت بالفعل تظل تُؤكَّد.

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

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

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

تم الدفع لكن الطلب ما زال في Pending payment: لا تصل الـ callbacks إلى متجرك. تحقق من أن Transaction processed callback وTransaction response callback في التكامل المستخدم يطابقان تمامًا العنوان الظاهر في صفحة الإعدادات، وأن HMAC secret يعود إلى حساب Paymob نفسه. تُسجَّل الـ callbacks المرفوضة كتحذيرات في WooCommerce > Status > Logs، بالمصدر wcp_paymob_pay، حتى عندما يكون سجل التصحيح معطّلًا.

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

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

يردّ الـ callback برسالة locked: كان طلب آخر يحدّث الطلب في اللحظة نفسها، مثل عودة العميل. ستعيد Paymob إرسال الـ callback.

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

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

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

تُظهر كتلة الترخيص خطأً: اتبع الرسالة المعروضة في الكتلة. فمثلًا إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، فحرّر خانة في حسابك على vibefox.net ثم انقر على Check now. وإذا تغير عنوان الموقع، فانقر على Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذر الوصول إلى خادم الترخيص، تستمر الإضافة بآخر حالة معروفة.

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

تعطيل الإضافة يحتفظ بجميع البيانات. ولإزالتها، عطّلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة والسجلات فلا تُحذف إلا إذا كان Clean uninstall مفعّلًا، وإلا فستبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات ومعرّفات Paymob.

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