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

المتطلبات

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

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

العملة: إحدى العملات PLN وEUR وCZK وHUF وRON وBGN وGBP وUSD وCHF وDKK وNOK وSEK وUAH. يجب أيضًا تفعيل العملة لنقطة البيع الخاصة بك لدى PayU. بالنسبة للعملات الأخرى، يُخفى خيار الدفع في صفحة إتمام الشراء.

وصول متجرك إلى الإنترنت: ترسل PayU إشعارات الدفع إلى متجرك، لذا يجب أن يكون متاحًا من الإنترنت (وألا يكون خلف مصادقة HTTP أو جدار حماية). حتى دون إشعارات، تُفحص المدفوعات عند عودة العميل من PayU.

حساب PayU: تحتاج إلى أربعة مفاتيح لنقطة البيع (POS): POS ID وSecond key (MD5) وOAuth client_id وOAuth client_secret. تجدها في لوحة التاجر في PayU ضمن Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. مفاتيح Sandbox تأتي من حساب PayU sandbox منفصل.

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

التثبيت

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

2. عند انتهاء الرفع، انقر Configure، أو ابحث لاحقًا عن VibeFox PayU Payment في قائمة الوحدات وانقر Configure.

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

4. أدخل المفاتيح الأربعة لـ Sandbox والمفاتيح الأربعة لـ Live (انظر الإعدادات). لا يلزم إعداد رابط إشعار في PayU.

5. فعّل Enable/Disable وانقر Save. أبقِ Test Mode مفعّلًا حتى تُجري دفعة تجريبية، ثم أوقفه لقبول المدفوعات الحقيقية بمفاتيح Live.

عند التثبيت، تُنشئ الوحدة حالتين للطلب: Awaiting PayU payment confirmation وPayU payment on hold. تُفعّل PrestaShop وحدة الدفع الجديدة لكل العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox PayU Payment > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول، تحذرك الصفحة أثناء تفعيل وضع sandbox (وضع Sandbox (الاختبار) مفعّل: تُرسل المدفوعات إلى sandbox الخاص بـ PayU ولا يُخصم أي مبلغ حقيقي. لا ترسل طلبات مدفوعة في وضع الاختبار.)، وعند غياب أحد المفاتيح الأربعة للوضع الحالي، وعندما لا تقبل PayU العملة الافتراضية للمتجر. في الحالتين الأخيرتين لا يظهر PayU في صفحة الدفع.

عند الحفظ، تُزال المسافات وفواصل الأسطر من جميع المفاتيح، لأن نسخها من لوحة PayU يضيفها غالبًا. لا يُحفظ حقل Title الفارغ: تعرض الصفحة أدخل عنوانًا لطريقة الدفع.

PayU

Enable/Disable: Enable PayU payment gateway يُفعّل خيار الدفع أو يعطّله. الافتراضي: معطّل.

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

Description: وصف طريقة الدفع الذي يراه العميل في صفحة الدفع. الافتراضي: Pay securely via PayU.

بيانات اعتماد API

تجد المفاتيح في لوحة التاجر في PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. مفاتيح Sandbox تأتي من حساب PayU sandbox منفصل. يجب تعبئة المفاتيح الأربعة لكل وضع.

Test Mode: يستخدم sandbox الخاص بـ PayU ومفاتيح Sandbox أدناه. لا يُخصم أي مبلغ حقيقي. وطالما هو مفعّل، يرى العملاء أسفل خيار الدفع: وضع Sandbox: لا يتم تنفيذ أي دفعة حقيقية. أوقفه لقبول المدفوعات الحقيقية بمفاتيح Live. الافتراضي: مفعّل.

Live POS ID: معرّف نقطة البيع POS ID (merchantPosId) الخاصة بنقطة البيع الإنتاجية.

Live Second Key (MD5): يُستخدم للتحقق من توقيع إشعارات PayU.

Live OAuth Client ID: معرّف عميل OAuth (client_id) لنقطة البيع.

Live OAuth Client Secret: السرّ الخاص بعميل OAuth (client_secret) لنقطة البيع.

Sandbox POS ID: معرّف نقطة البيع POS ID لنقطة البيع الخاصة بـ PayU sandbox.

Sandbox Second Key (MD5): يُستخدم للتحقق من توقيع إشعارات PayU sandbox.

Sandbox OAuth Client ID: معرّف عميل OAuth (client_id) لنقطة بيع sandbox.

Sandbox OAuth Client Secret: السرّ الخاص بعميل OAuth (client_secret) لنقطة بيع sandbox.

لا تُعرض مرة أخرى المفاتيح الثانية Second Keys والأسرار client secrets المحفوظة. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للاحتفاظ به. اكتب قيمة جديدة فقط إذا أردت تغييرها. تُعرض معرّفات POS IDs ومعرّفات العملاء client IDs كما هي محفوظة.

Clear saved secrets: حدّد سرًا ثم انقر Save لإزالته. يُبقي الحقل الفارغ القيمة المحفوظة.

تتذكر كل دفعة بيئتها. تستخدم إشعارات الدفعة وفحوصات حالتها واستردادها دائمًا مفاتيح تلك البيئة، لذا تستمر المدفوعات السابقة في العمل بعد تبديل الوضع. لا يُقبل إشعار موقّع بمفتاح sandbox أبدًا لدفعة حقيقية، والعكس صحيح.

إشعارات الدفع

Notification URL: يعرض العنوان الذي ترسل إليه PayU الإشعارات. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_payu_payment/webhook، وربما مع رمز لغة. ترسله الوحدة إلى PayU مع كل دفعة، لذلك لا يلزم إعداد شيء في لوحة PayU. تأكد من أنه متاح من الإنترنت (غير محجوب بجدار حماية أو مصادقة HTTP). تعمل الإشعارات أيضًا أثناء وضع الصيانة للمتجر، ولا يحجبها قيد الدول الخاص بمتجرك.

متقدم

Receive payments automatically: يستلم تلقائيًا المدفوعات بانتظار التأكيد. لا يهم هذا الخيار إلا إذا كان الاستلام التلقائي معطّلًا لنقطة البيع في لوحة PayU: عندئذ تنتظر المدفوعات التأكيد (WAITING_FOR_CONFIRMATION). عند تفعيل هذا الخيار، تستلم الوحدة هذه المدفوعات فورًا وينشأ الطلب عندما تبلغ PayU باكتمال الدفعة. وعند تعطيله، أو عند فشل الاستلام، يُنشأ الطلب في Awaiting PayU payment confirmation، وتستلم الدفعة أو تلغيها بالأزرار الموجودة في كتلة PayU بالطلب. الافتراضي: مفعّل.

Logging: يكتب الأحداث التقنية (أرقام السلة والطلب، ومعرّفات طلبات PayU، والحالات، والأخطاء، دون مفاتيح أو بيانات شخصية) في الملف logs/wc_pu_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائمًا؛ أما الأحداث الأخرى فتُسجَّل فقط عند تفعيل هذا الخيار. الافتراضي: معطّل.

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

Delete data on uninstall: يحذف إعدادات الوحدة والسجلات عند إلغاء تثبيتها. الطلبات وبيانات دفعها (معاملات PayU والاستردادات وحالات الطلبات) لا تُحذف أبدًا. الافتراضي: معطّل.

إتمام الشراء

في خطوة الدفع، يختار العميل خيار الدفع (افتراضيًا PayU) ويرى الوصف والملاحظة سيتم توجيهك إلى PayU لإتمام الدفع (BLIK، أو تحويل مصرفي، أو بطاقة، وطرق أخرى). بعد التأكيد، تنشئ الوحدة طلب PayU بإجمالي السلة بعملة السلة، بالوصف Cart # ورقم السلة واسم متجرك، مع البنود والشحن وتغليف الهدايا لعرضها في صفحة PayU. تُرسل بريد العميل الإلكتروني واسمه وهاتفه إلى PayU. تتبع لغة صفحة PayU لغة المتجر حين تدعمها PayU، وإلا فالإنجليزية. يُوجَّه العميل إلى صفحة PayU، ويختار هناك طريقة ويدفع. لا يوجد طلب في هذه المرحلة.

تحصل كل محاولة دفع على طلب PayU خاص بها. عندما يعيد العميل المحاولة، يُلغى دفع PayU السابق غير المكتمل للسلة لدى PayU، لذا لا يمكن سداد رابط دفع قديم مرتين. وإذا تبيّن أن الدفعة السابقة مدفوعة بالفعل، يُنشأ الطلب بدلًا من دفعة جديدة.

لا تؤدي العودة إلى متجرك وحدها أبدًا إلى دفع الطلب. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد PayU: إما بإشعار موقّع بالمفتاح Second Key لبيئة الدفع، أو بفحص حالة طلب PayU من الخادم عند عودة العميل (مرة واحدة على الأكثر كل 10 ثوانٍ لكل سلة). يجب أن يكون طلب PayU قد أُنشئ لهذه السلة، ويجب أن يتطابق المبلغ والعملة. تتعامل الوحدة مع حالات PayU التالية:

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

إذا لم تؤكد PayU الدفعة بعد عند عودة العميل، تعرض صفحة Payment confirmation الرسالة لم نتلقَّ تأكيد الدفع من PayU بعد. إذا انقطعت عملية الدفع، يمكنك المحاولة مرة أخرى: (أو، عندما تبلغ PayU عن خطأ، لم تكتمل عملية الدفع. يمكنك المحاولة مرة أخرى:) مع الزرين Pay again وCheck again. يُنشأ الطلب فور وصول الإشعار. وإذا أُلغيت الدفعة، يعود العميل إلى صفحة الدفع مع لم تكتمل عملية الدفع. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وتبقى السلة محفوظة.

إذا لم تتمكن PayU من بدء الدفع، يبقى العميل في صفحة الدفع مع خطأ في الدفع. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. ويُكتب السبب التقني في السجل. إذا كانت مفاتيح الوضع الحالي مفقودة، تكون الرسالة بوابة الدفع غير مُعدّة بشكل صحيح. يرجى التواصل مع المسؤول.

إذا توقف قسيمة في السلة عن الصلاحية بين الدفع وتأكيده، تُزال من الطلب. ينتقل الطلب عندئذ إلى PayU payment on hold مع ملاحظة تذكر القسيمة، لأن العميل دفع السعر بعد الخصم.

يختار العميل طريقة الدفع في صفحة PayU، لا في صفحة الدفع الخاصة بمتجرك. لا تحتوي الوحدة على نموذج بطاقة في متجرك، ولا بطاقات محفوظة أو دفع بنقرة واحدة، ولا اشتراكات، ولا أدوات تقسيط أو تمويل PayU. تستخدم نقطة بيع واحدة لكل بيئة.

الطلبات والاسترداد

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى PayU ولم يدفع، أو لم تؤكد PayU الدفعة بعد. لا توجد سوى السلة.

Payment accepted: تم تأكيد الدفعة. تُسجَّل الدفعة بمعرّف طلب PayU كمعرّف للمعاملة، وتعرض الملاحظة معرّف طلب PayU والمبلغ والبيئة (sandbox أو live).

Awaiting PayU payment confirmation: الدفعة مُعتمدة وبانتظارك (الاستلام التلقائي معطّل، أو فشل الاستلام). لم تُسجَّل أي دفعة بعد.

PayU payment on hold: المبلغ أو العملة المدفوعة لم يتطابقا مع السلة (لا يُعلَّم الطلب كمدفوع)، أو أُزيلت قسيمة، أو كان للدفعة بانتظار التأكيد مبلغ مختلف، أو اكتمل دفع لطلب كان قد أُلغي (تُسجَّل الدفعة). تحدد الملاحظة أي حالة هي. افحص الطلب ثم نفّذه أو استرد الدفعة.

Payment error: أُلغيت الدفعة أو رُفضت لطلب بانتظار التأكيد.

Refunded: استُردّت الدفعة بالكامل عبر الوحدة.

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

كتلة دفع PayU

تعرض صفحة الطلب كتلة PayU payment تتضمن معرّف طلب PayU وextOrderId وحالة PayU والمبلغ المدفوع والمسترد وشارة Sandbox للمدفوعات التجريبية وسجل الاسترداد وPayU notes الخاصة بالطلب. تتطلب إجراءات الكتلة صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات الوحدات.

مدفوعات بانتظار التأكيد

بالنسبة لطلب فيه دفعة بانتظار التأكيد، تعرض الكتلة Receive PayU payment (waiting for confirmation) وCancel PayU payment (release the funds). بعد تأكيد السؤال، يُرسل الإجراء إلى PayU بمفاتيح بيئة الدفع، ويُضاف إلى الملاحظات مع اسمك، وتُطبَّق حالة PayU الجديدة فورًا: الدفعة المستلمة تضع الطلب على Payment accepted، والملغاة تضعه على Payment error.

الاسترداد

في كتلة PayU payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا السبب، ثم انقر Refund via PayU. أكّد السؤال هل تريد استرداد هذا المبلغ عبر PayU؟ لا يمكن التراجع عن هذا الإجراء. الاسترداد الكامل والجزئي مدعومان. يُرسل الاسترداد لطلب PayU الذي دُفع فعليًا، بمفاتيح بيئة الدفع، لذا يجب أن تكون هذه المفاتيح مُعدّة. تتم الاستردادات بالمبلغ والعملة اللذين حصلت عليهما PayU، لذا بعد اختلاف المبلغ أو العملة يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب. يُرسل السبب كوصف للاسترداد. إذا رفضت PayU الاسترداد، تعرض الكتلة خطأ PayU ولا يُسجَّل أي استرداد. يضع الاسترداد الكامل الطلب على Refunded. أما الاسترداد الجزئي فلا يغيّر الحالة.

الاستردادات لدى PayU غير متزامنة. تضيف الوحدة فورًا ملاحظة تتضمن معرّف الاسترداد لدى PayU وحالته؛ وتصل الحالة النهائية لاحقًا كإشعار من PayU وتُضاف إلى الملاحظات وسجل الاسترداد. وإذا ألغت PayU الاسترداد، تذكر الملاحظة أن المال لم يُعَد إلى العميل، ويمكن استرداد المبلغ مرة أخرى.

لا تنشئ الوحدة إشعارات ائتمان. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترسل المال عبر PayU.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PayU Payment هي أول كتلة في صفحة Modules > Module Manager > VibeFox PayU Payment > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مموّهًا، والحالة (مثلًا تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. أسفلها سطر Product: presta-payment-payu ورابط 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.

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

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

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

لا يظهر PayU في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفاتيح الأربعة للوضع الحالي معبّأة: مفاتيح Sandbox في وضع sandbox، ومفاتيح Live في وضع live. تحقق من أن عملة السلة من العملات المدعومة. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل. تعرض صفحة الإعدادات تحذيرًا عند غياب المفاتيح أو عدم دعم عملة المتجر.

تمت عملية الدفع لكن لم يُنشأ أي طلب: لم تُسلِّم PayU الإشعار بعد، ولم يرَ فحص الحالة في صفحة العودة دفعة مكتملة. تحقق من أن Notification URL المعروض في الإعدادات متاح من الإنترنت. فعّل Logging لترى ما يصل. ويمكن للعميل أيضًا النقر على Check again في صفحة Payment confirmation.

يرد الإشعار بـ Invalid signature: لم يُوقَّع الإشعار بالمفتاح Second Key لأي من البيئتين. تحقق من Live Second Key (MD5) وSandbox Second Key (MD5). الرد Invalid signature for this payment يعني أن الإشعار وُقّع بمفتاح بيئة غير بيئة الدفعة.

يرد الإشعار بـ Ignored: unknown PayU order: لم تُنشئ هذا الطلب لدى PayU هذه المتجر، مثلًا متجر آخر على نقطة البيع نفسها. وتتوقف PayU عن إعادة المحاولة.

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

تعرض الرابط Notification URL في المتصفح الرسالة POST expected: هذا طبيعي. الرابط يقبل إشعارات PayU فقط.

يرى العميل Payment error عند اختيار PayU: فعّل Logging وانظر إلى الحقل Log في صفحة الوحدة. يعرض السجل رمز HTTP وحالة PayU. تعذّر التوثيق لدى PayU (تحقق من OAuth client ID / secret). تعني مفاتيح OAuth خاطئة للوضع الحالي.

الطلب في PayU payment on hold: اقرأ الملاحظات في كتلة PayU payment (انظر حالات الطلب)، ثم نفّذ الطلب أو استرد الدفعة.

الطلب في Awaiting PayU payment confirmation: الاستلام التلقائي معطّل لنقطة البيع الخاصة بك، والدفعة بانتظارك. استخدم Receive PayU payment أو Cancel PayU payment في كتلة PayU.

يفشل الاسترداد: لا يحتوي هذا الطلب على دفعة PayU مكتملة. تعذّرت معالجة الاسترداد. تعني أن PayU لم تُكمل دفعة للطلب بعد. أما رسالة نقص مفاتيح Sandbox أو Live فتعني أن الدفعة تمت في تلك البيئة وأن مفاتيحها غير مُعدّة. أدخلها وأعد المحاولة.

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

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

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