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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على الإصدار 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث، مع امتداد cURL.

العملة: يجب أن تكون عملة الدفع لدى العميل إحدى العملات التالية: 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.

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

التثبيت

التنزيل ملف zip واحد يحتوي على حزم الإصدارين من OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt وحزمة OpenCart 3 wcp_payu_payment-oc3-(version).ocmod.zip وحزمة OpenCart 4 wcp_payu_payment.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_payu_payment-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. ويمكنك بدلًا من المثبّت نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox PayU Payment وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة الخاص بك إلى صلاحية تعديل قائمة إضافات الدفع.

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

4. أدخل المفاتيح الأربعة لبيئة Sandbox والمفاتيح الأربعة لبيئة Live (انظر الإعدادات). لا حاجة إلى ضبط عنوان URL للإشعارات في PayU.

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

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_payu_payment.ocmod.zip. لا تُغيّر اسم الملف: يستمد OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي يُعاد تسميتها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (الزر الأخضر +) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox PayU Payment، وانقر على Install (الزر الأخضر +)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح PayU كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو عنوان الإشعارات (راجع Payment notifications).

يبدأ التثبيت الجديد بتعطيل طريقة الدفع وتفعيل وضع الاختبار.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox PayU Payment > Edit. تظهر الأقسام على اليسار؛ ويحفظ الزر Save الموجود أسفل القائمة الصفحة كاملة. وفوق الإعدادات، تحذّرك الصفحة عندما يكون وضع الحماية (sandbox) مفعّلًا (وضع Sandbox (الاختبار) مفعّل: تُرسل المدفوعات إلى بيئة PayU التجريبية ولا يُخصم أي مبلغ حقيقي. لا تشحن الطلبات المدفوعة في وضع الاختبار.)، وعندما يفتقد المفاتيح الأربعة للوضع الحالي أحدها (وعندها لا تظهر PayU في صفحة الدفع)، وعندما لا تقبل PayU العملة الافتراضية للمتجر (وعندها تُخفى PayU للطلبات بتلك العملة). وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، تُزال المسافات وفواصل الأسطر من جميع المفاتيح، لأن النسخ من لوحة PayU يُدخلها غالبًا. ولا يمكن أن يكون Title فارغًا أو أطول من 128 حرفًا (تعرض الصفحة أدخل عنوانًا لطريقة الدفع (128 حرفًا كحد أقصى).)، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من 0 أو يساويه، ويجب أن توجد المنطقة الجغرافية وحالات الطلب. وإلا فلن يُحفظ شيء. كما يؤدي حفظ الإعدادات إلى مسح رموز الوصول المخزنة مؤقتًا لدى PayU.

PayU

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: PayU. حقل إلزامي، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via PayU.

Sort Order: ترتيب PayU بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض PayU فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي صفحة الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض PayU. اتركه فارغًا لعرض PayU مهما كان المبلغ.

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

تجد المفاتيح في لوحة التاجر لدى PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. وتأتي مفاتيح الاختبار (sandbox) من حساب منفصل لاختبار PayU. ويجب ملء المفاتيح الأربعة لكل وضع. ويتضمن هذا القسم روابط إلى وثائق مطوّري PayU.

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

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

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

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

Live OAuth Client Secret: client_secret لنقطة البيع في OAuth.

Sandbox POS ID: معرّف نقطة البيع لبيئة PayU التجريبية الخاصة بك.

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

Sandbox OAuth Client ID: معرّف client_id لنقطة البيع التجريبية في OAuth.

Sandbox OAuth Client Secret: client_secret لنقطة البيع التجريبية في OAuth.

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

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

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

حالات الطلب

يُنشئ OpenCart الطلب في خطوة Confirm Order بلا حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن تؤكد PayU الدفع، إما بإشعار موقّع أو بفحص الحالة عند عودة العميل. ولا توجد في OpenCart حالة On hold: فحالات الانتظار تكون Pending افتراضيًا، وتشرح تبويب PayU الخاص بالطلب وملاحظاته السبب. يسرد كل حقل أدناه حالات طلبات OpenCart لديك؛ ويمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses.

Order Status After Payment: يُضبط عندما تؤكد PayU الدفع (COMPLETED) ويتطابق المبلغ والعملة. الافتراضي: Processing.

Awaiting PayU Payment Confirmation: الدفعة مُصرَّح بها وتنتظر الاستلام (الاستلام التلقائي متوقف أو فشل). استخدم Receive PayU payment أو Cancel PayU payment في تبويب PayU الخاص بالطلب. الافتراضي: Pending.

PayU Payment On Hold: المبلغ المدفوع أو العملة لا يطابقان الطلب، أو اكتمل دفع لطلب ملغى. لا يُعلَّم الطلب كمدفوع؛ وتشرح الملاحظة السبب. الافتراضي: Pending.

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

Cancelled Order Status: الدفعة المكتملة من PayU لطلب في هذه الحالة تضع الطلب في الانتظار بدلًا من إعادة فتحه بصمت. ولا تضبط الإضافة هذه الحالة أبدًا. الافتراضي: Canceled.

Refunded Status: يُضبط بعد استرداد الدفعة بالكامل من تبويب PayU الخاص بالطلب. الافتراضي: Refunded.

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

Notification URL: يعرض العنوان الذي ترسل إليه PayU الإشعارات. في OpenCart 3 يكون بالشكل https://your-store/index.php?route=extension/payment/wcp_payu_payment/notify، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_payu_payment/payment/wcp_payu_payment.notify. ويُبنى من عنوان واجهة متجرك في تثبيت OpenCart. وترسله الإضافة إلى PayU مع كل دفعة، لذلك لا يلزم ضبط أي شيء في لوحة PayU. تأكد من أنه متاح من الإنترنت (وألا تحجبه جدار حماية أو مصادقة HTTP). وتعمل الإشعارات أيضًا عندما يكون المتجر في وضع الصيانة (في OpenCart 4 عبر إجراء بدء التشغيل الخاص بالإضافة، الذي يسمح أيضًا بعودة العميل من PayU). وتُرفض الإشعارات التي لا تحمل توقيعًا صالحًا.

متقدم

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

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

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. ولا تُصدَّر الأسرار.

Import: الصق ملف JSON الذي صدّرته سابقًا وانقر على Import لاستعادة الإعدادات. وتبقى الأسرار المحفوظة كما هي.

الدفع

في خطوة Payment Method، يختار العميل طريقة الدفع (افتراضيًا PayU). وفي خطوة Confirm Order، يرى العميل وصفك والملاحظة سيتم تحويلك إلى PayU لإكمال الدفع (BLIK، والتحويل المصرفي، والبطاقة، وطرق أخرى). ينشئ OpenCart الطلب في هذه الخطوة، ما يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة طلب PayU بإجمالي الطلب بعملة الطلب، مع الوصف Order # ورقم الطلب واسم متجرك، ومع المنتجات وطريقة الشحن وسطور الإجمالي الأخرى للطلب لعرضها في صفحة PayU. وتُمرَّر إلى PayU بريد العميل الإلكتروني واسمه ورقم هاتفه، وتتبع لغة صفحة PayU لغة واجهة المتجر. ويُنقل العميل إلى صفحة PayU، حيث يختار طريقة ويدفع.

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

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

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

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

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تُعرض صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا عند إلغائه أو استرداده)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was closed (not paid, cancelled or refunded). Please confirm the order again to pay with a new order. وعندما يعود العميل من PayU إلى طلب أُغلق دون دفع، تكون الرسالة لم يكتمل الدفع. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وإذا كان هذا الطلب قد دُفع لسلة سابقة وتغيّرت السلة منذ ذلك الحين، يُعاد العميل إلى صفحة الدفع. وتدفع خطوة Confirm Order التالية في كل الحالات طلبًا جديدًا للسلة الحالية. ولا يُعرض طلب مغلق أبدًا على أنه مدفوع.

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

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

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى PayU ولم يدفع، أو أُلغيت الدفعة، أو لم تؤكد PayU الدفع بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا مع تعيين الفلتر Order Status إلى Missing Orders.

Order Status After Payment (الافتراضي Processing): تم تأكيد الدفع. وتعرض ملاحظة معرّف طلب PayU والمبلغ والبيئة (sandbox أو live).

Awaiting PayU Payment Confirmation (الافتراضي Pending): الدفعة مُصرَّح بها وتنتظر منك (الاستلام التلقائي متوقف، أو فشل الاستلام).

PayU Payment On Hold (الافتراضي Pending): المبلغ المدفوع أو العملة لم يطابقا الطلب، أو كانت دفعة تنتظر التأكيد بمبلغ مختلف، أو اكتمل دفع لطلب كان قد أُلغي. وتوضح الملاحظة أي حالة حدثت. تحقق من الطلب ونفّذه، أو استرد الدفعة.

Payment Error Status (الافتراضي Failed): أُلغيت دفعة لطلب كان ينتظر التأكيد أو رُفضت.

Refunded Status (الافتراضي Refunded): استُرد الدفع بالكامل عبر الإضافة.

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

الملاحظات مدخلات في History الخاص بالطلب، ولا يراها العميل.

تبويب VibeFox PayU Payment

في Sales > Orders افتح طلبًا مدفوعًا عبر PayU. وفي أسفل صفحة الطلب، بجوار History وAdditional، يعرض التبويب VibeFox PayU Payment الحقل PayU order ID مع علامة Sandbox لمدفوعات الاختبار، وextOrderId، وPayU status، وPayment amount، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل Refunds، وPayU payment attempts للطلب، وPayU notes. ويُعرض التبويب للمستخدمين الذين لديهم حق الوصول إلى الإضافة؛ وتتطلب إجراءاته صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups).

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

بالنسبة إلى طلب فيه دفعة تنتظر التأكيد، يعرض التبويب Receive PayU payment وCancel PayU payment. وبعد تأكيد السؤال، يُرسل الإجراء إلى PayU بمفاتيح بيئة الدفعة، ويُضاف إلى الملاحظات باسم المستخدم الخاص بك، ويُطبَّق الحالة الجديدة لـ PayU فورًا: فالدفعة المستلمة تضبط Order Status After Payment، والدفعة الملغاة تضبط Payment Error Status.

الاستردادات

في التبويب، أدخل Amount (تُملأ تلقائيًا بالمبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via PayU. أكّد السؤال Refund this amount through PayU? This cannot be undone. والاستردادات الكاملة والجزئية مدعومة. وتتوفر الاستردادات بعد أن تكمل PayU الدفع. ويُرسل الاسترداد للطلب الفعلي المدفوع لدى PayU، باستخدام مفاتيح بيئة الدفعة، لذا يجب ضبط تلك المفاتيح. وتُنفَّذ الاستردادات بالمبلغ والعملة اللذين خصمتهما PayU؛ لذلك بعد أي اختلاف في المبلغ أو العملة، يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. ويُرسل السبب كوصف للاسترداد. وإذا رفضت PayU الاسترداد، يعرض التبويب خطأ PayU ولا يُسجَّل أي استرداد. ويضبط الاسترداد الكامل الطلب على Refunded Status، من دون إخطار العميل ومن دون إعادة المنتجات إلى المخزون. أما الاسترداد الجزئي فلا يغيّر الحالة.

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

لا تعيد مرتجعات المنتجات في Sales > Returns أي مبلغ عبر PayU.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. وكتلة الترخيص License — VibeFox PayU Payment هي أول كتلة في Extensions > Extensions > Payments > VibeFox PayU Payment > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. وبعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: opencart-payment-payu ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify للإضافة. وتتبع نصوص الكتلة لغة الإدارة (وتتضمن الإنجليزية والروسية).

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

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

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

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

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

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

تمت عملية الدفع لكن الطلب بقي بلا حالة: لم تُسلّم PayU الإشعار بعد، ولم يجد فحص الحالة في صفحة العودة دفعة مكتملة. تحقق من أن عنوان 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 لمعرفة السبب.

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

يرى العميل Payment error بعد Confirm Order: فعّل Logging وانظر إلى الحقل Log في صفحة الإضافة. ويعرض السجل رمز HTTP وحالة PayU. وتعني الرسالة Could not authenticate with PayU (check the OAuth client ID / secret). أن مفاتيح OAuth للوضع الحالي غير صحيحة. وتعني This payment method is not available. أن جلسة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في الأثناء: يجب على العميل إعادة تحميل صفحة الدفع.

الطلب في PayU Payment On Hold: اقرأ الملاحظات في تبويب VibeFox PayU Payment (راجع حالات الطلب)، ثم نفّذ الطلب أو استرد الدفعة.

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

فشل الاسترداد أو لا يوجد نموذج استرداد: يوضح التبويب السبب. وتعني Refunds are available once PayU has completed the payment. أن PayU لم تكمل دفعًا للطلب بعد. وتعني رسالة فقدان مفاتيح Sandbox أو Live أن الدفعة تمت في تلك البيئة وأن مفاتيحها غير مضبوطة. أدخلها وأعد المحاولة. وإذا لم تكن لديك صلاحية تعديل الإضافة، يعرض التبويب You do not have permission to refund (modify this extension).

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox PayU Payment. تُزال دائمًا مفاتيح الترخيص وحالة الترخيص لهذه الإضافة. ويزيل OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Order statuses، وتعود هذه إلى قيمها الافتراضية عند إعادة التثبيت. ويُزال أيضًا حدث OpenCart الخاص بالإضافة ورموز الوصول المخزنة مؤقتًا لدى PayU (وفي OpenCart 4 تُحذف أيضًا أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور الإشعارات وعودة العميل في وضع الصيانة). وإذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان، والوصف، ووضع الاختبار، والمفاتيح، والاستلام التلقائي، والتسجيل) والسجل. وإذا كان معطّلًا، فتُحفظ لإعادة التثبيت لاحقًا. وتُحفظ معاملات PayU والاستردادات دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox PayU Payment في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

PayU علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ PayU ولا معتمدة من قبلها.