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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

العملة: الروبية الهندية (INR). تحصّل PayU India بالروبية فقط. ويحتاج متجرك إلى عملة INR (System > Localisation > Currencies). وبالنسبة إلى الطلبات بعملات أخرى، تُخفى طريقة الدفع في صفحة الدفع.

رقم الهاتف: تشترط PayU رقم هاتف لكل دفعة. احتفظ بحقل Telephone في صفحة الدفع لديك حتى يكون للطلب رقم هاتف. لا يطلب الدفع في OpenCart 4 رقم الهاتف افتراضيًا: وعندما لا يكون للطلب رقم هاتف، تعرض الإضافة حقلها الخاص Phone في خطوة التأكيد (راجع الدفع).

حساب PayU India: تحتاج إلى Merchant Key وMerchant Salt (v1) من PayU Dashboard > Payment Gateway > Key Salt Details. انقل اللوحة إلى Test Mode لترى زوج الاختبار. واستخدم Salt v1 وليس Salt v2.

الوصول إلى الإنترنت لمتجرك: مطلوب للـ webhook الاختياري. ومن دونه تُؤكَّد الطلبات عندما يعود العميل من PayU.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل Merchant Key وSalt الخاصين بالاختبار، وMerchant Key وSalt الخاصين بالإنتاج (انظر الإعدادات).

5. موصى به: في PayU Dashboard > Webhooks، أضف عنوان URL للـ webhook المعروض في صفحة الإعدادات للدفعات الناجحة والفاشلة.

6. اختر Mode، وفعّل Enable/Disable، ثم انقر على Save. جرّب دفعة في وضع Test، ثم انتقل إلى Live.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص وبيانات اعتماد PayU والـ webhook كما في الخطوات 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. العنوانان المختلفان فقط هما عنوانا Return وwebhook (راجع Return and webhook URLs).

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox PayU India Payment Gateway > Edit. تظهر الأقسام على اليسار؛ ويحفظ الزر Save الموجود أسفل القائمة الصفحة كاملة. وفوق الإعدادات، تحذّرك الصفحة عندما يكون المفتاح أو الـ salt الخاص بالوضع الحالي مفقودًا، وتعرض في وضع Test الرسالة وضع الاختبار نشط: تُرسل المدفوعات إلى test.payu.in ولا يُخصم أي مبلغ حقيقي.، وتعرض خطأً عندما تكون العملة الافتراضية لمتجرك غير INR: وعندها لا تظهر البوابة في صفحة الدفع إلا إذا دفع العميل بالروبية. وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

PayU India

يبدأ القسم بملاحظة قصيرة: البطاقات وNetBanking وUPI والمحافظ في صفحة الدفع المستضافة لدى PayU؛ ولا تُقبل النتائج إلا بتوقيع PayU صالح؛ والروبية فقط.

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

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

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

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

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

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

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

انسخ Merchant Key وMerchant Salt (v1) من PayU Dashboard > Payment Gateway > Key Salt Details. انقل اللوحة إلى Test Mode للحصول على زوج الاختبار. ويحتوي القسم على رابط Open the PayU Dashboard.

Mode: بيئة PayU التي تستخدمها المدفوعات الجديدة.

تحتفظ المدفوعات التي بدأت بالفعل بالوضع الذي بدأت فيه: تُفحص نتائجها بمفتاح ذلك الوضع وsalt الخاص به، وتُرسل استردادها بالمفتاح والـ salt الخاصين بذلك الوضع، حتى بعد أن تغيّر الوضع.

Live Merchant Key: مفتاح Merchant الإنتاجي لدى PayU.

Live Merchant Salt (v1): Merchant Salt (v1) الإنتاجي لدى PayU. وهو يوقّع الطلبات ويتحقق من ردود PayU. احتفظ به سرًّا.

Test Merchant Key: مفتاح Merchant الخاص باختبار PayU، ويُستخدم في وضع Test فقط.

Test Merchant Salt (v1): Merchant Salt (v1) الخاص باختبار PayU، ويُستخدم في وضع Test فقط.

لا تُعرض الـ salts المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للإبقاء عليه. اكتب قيمة جديدة فقط إذا أردت تغييرها. ولإزالة salt محفوظ، ضع علامة على Clear the saved salt on save أسفل الحقل، ثم انقر على Save.

عناوين URL للعودة والـ webhook

Return URL: في OpenCart 3 بالشكل https://your-store/index.php?route=extension/payment/wcp_payu_india_payment/back، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_payu_india_payment/payment/wcp_payu_india_payment.back. وتُرسل تلقائيًا إلى PayU مع كل دفعة؛ ولا يلزم ضبط أي شيء.

Webhook URL: في OpenCart 3 بالشكل https://your-store/index.php?route=extension/payment/wcp_payu_india_payment/webhook، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_payu_india_payment/payment/wcp_payu_india_payment.webhook. وهو اختياري لكنه موصى به: يؤكد المدفوعات حتى لو أغلق العميل المتصفح قبل أن يعود. أضفه في PayU Dashboard > Webhooks للدفعات الناجحة والفاشلة. انسخ العنوان تمامًا كما تعرضه صفحة الإعدادات. ويجب أن يكون متاحًا من الإنترنت (من دون مصادقة أساسية أو حجب بجدار حماية). ولا يحجبه وضع الصيانة في المتجر.

يحمل الـ webhook النتيجة الموقّعة نفسها التي تصل مع عودة العميل. وتُرفض الـ webhooks التي لا تحمل hash صالحًا من PayU.

الطلبات

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

Order Status After Payment: دفعة ناجحة بالمبلغ المتوقع بالروبية، مؤكدة بواسطة verify_payment عندما يكون Verify Payment مفعّلًا. الافتراضي: Processing.

Awaiting PayU Payment Status: تُبلغ PayU بأن الدفعة معلّقة (UPI collect، أو NetBanking قيد التنفيذ). ويحصل الطلب على حالة ما بعد الدفع عندما تؤكد PayU ذلك. الافتراضي: Pending.

On Hold (Review) Status: أبلغت PayU عن دفعة ناجحة تحتاج إلى مراجعة يدوية (راجع حالات الطلب). الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. ويمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment Error Status: دفعة معلّقة أبلغت PayU لاحقًا أنها فشلت. الافتراضي: Failed.

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

Cancelled Order Status: الحالة التي يستخدمها متجرك للطلبات الملغاة. وتؤدي الدفعة المستلمة لمثل هذا الطلب إلى وضعه في المراجعة بدلًا من تعليمه كمدفوع. ولا تضبط الإضافة هذه الحالة أبدًا. الافتراضي: Canceled.

متقدم

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

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

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

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

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

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

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

الدفع

في خطوة Payment Method، يختار العميل طريقة الدفع (افتراضيًا PayU India). وفي خطوة Confirm Order، يرى العميل وصفك؛ وينشئ OpenCart الطلب في هذه الخطوة، ما يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وإذا لم يكن للطلب رقم هاتف، تعرض كتلة التأكيد في OpenCart 4 أيضًا حقل Phone مع التلميح PayU India requires the phone number of the payer. ويُرسل الرقم المُدخَل إلى PayU ويُحفظ للمحاولة التالية، ويكون لرقم هاتف الطلب الأولوية. وعندما ينقر العميل على Confirm Order، تتحقق الإضافة من العملة وبيانات اعتماد الوضع الحالي ورقم هاتف الطلب. وإذا لم يكن هناك رقم هاتف، يبقى العميل في الخطوة ويرى تشترط PayU India وجود رقم هاتف. يرجى إدخال رقم هاتفك والمحاولة مرة أخرى. وفي الحالات الأخرى تنشئ الإضافة طلب دفع موقّعًا بإجمالي الطلب بالروبية، ويرسله المتصفح فورًا إلى صفحة الدفع المستضافة لدى PayU. وتعرض الصفحة سيتم تحويلك إلى PayU لإكمال الدفع. وزر Pay with PayU في حال لم يتابع المتصفح تلقائيًا. وفي صفحة PayU يدفع العميل بالبطاقة أو NetBanking أو UPI أو المحفظة.

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

ترسل PayU النتيجة مع العميل، وكذلك عبر الـ webhook إن كان مُعدًّا. ولا تُقبل النتيجة إلا إذا كان فيها hash صالح من PayU أُنشئ بمفتاح الوضع الذي بدأت فيه الدفعة وsalt الخاص به، ولمعرّف معاملة صدر لذلك الطلب تحديدًا. وعند تفعيل Verify Payment تُتحقق النتيجة الناجحة أيضًا عبر واجهة verify_payment لدى PayU. ويجب أن يساوي المبلغ المدفوع مبلغ المحاولة وإجمالي الطلب تمامًا، حتى أصغر وحدة (paisa)، بالروبية. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد PayU ذلك بهذه الطريقة، ثم يحصل على حالته بالطريقة المعتادة في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون. وتتعامل الإضافة مع نتائج PayU التالية:

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

بعد دفعة غير ناجحة يعود العميل إلى صفحة الدفع مع رسالة: لم يكتمل الدفع. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع مختلفة.، أو أُلغي الدفع. يمكنك المحاولة مرة أخرى.، أو عندما تعذّر التحقق من النتيجة، تعذّر علينا تأكيد نتيجة الدفع. إذا خُصم مبلغ من حسابك، يرجى التواصل معنا قبل الدفع مرة أخرى. وإذا كانت النتيجة ما تزال قيد المعالجة عند عودة العميل، تعرض صفحة نحن نؤكد دفعتك عبر PayU. إذا أتممت الدفع، سيُحدَّث طلبك قريبًا — يرجى عدم الدفع مرة أخرى. مع الزرين Check again وBack to checkout. وفي OpenCart 4 تُعرض رسائل الدفع هذه أعلى صفحة الدفع.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تُعرض صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا عند فشل دفعته المعلّقة أو عند إلغائه)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled or its payment failed. Please confirm the order again. وإذا كان الطلب قد دُفع ثم ألغاه المتجر أو استرده لاحقًا، تكون الرسالة Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. وإذا كان قد دُفع لسلة سابقة وتغيّرت السلة منذ ذلك الحين، تكون الرسالة Your previous order has already been paid. Your cart has changed since — please confirm the order again to pay for the current cart. وتدفع خطوة Confirm Order التالية طلبًا جديدًا. ولا يُعرض طلب مغلق أبدًا على أنه مدفوع.

يعمل الـ webhook أيضًا عندما يكون المتجر في وضع الصيانة، لأن OpenCart يسمح بمرور طلبات إضافات الدفع (في OpenCart 4 تضيف الإضافة إجراء بدء التشغيل الخاص بها لهذا الغرض، وهو يسمح أيضًا بعودة العميل من PayU).

تحصّل الإضافة بالروبية فقط ولا تدعم المعالجة متعددة العملات (MCP). ولا تتضمن بطاقات محفوظة أو ترميزًا للبطاقات، ولا اشتراكات، ولا نموذج بطاقة مدمجًا في الموقع (seamless)، ولا إدارة لأقساط EMI أو العروض، ولا دفعًا بنقرة واحدة من PayU.

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

حالات الطلب

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

Order Status After Payment (الافتراضي Processing): تم تأكيد الدفع. وتعرض الملاحظة PayU payment successful. Transaction ID: …, Mode: …, Bank: …

Awaiting PayU Payment Status (الافتراضي Pending): دفعة UPI أو NetBanking ما تزال معلّقة لدى PayU. ويحصل الطلب على حالة الدفع عندما تؤكد PayU ذلك.

On Hold (Review) Status (الافتراضي Pending): المبلغ المدفوع أو العملة يختلفان عن الطلب، أو تعذّر الوصول إلى واجهة verify_payment أو لم تؤكد الدفع بعد، أو وصلت دفعة لطلب في حالة Cancelled Order Status. وتوضح الملاحظة السبب. تحقق من المعاملة في PayU Dashboard، ثم اضبط حالة الدفع، أو ألغِ الطلب واسترد الدفعة. وإذا فشل التحقق وحده، فسيُدفع الطلب تلقائيًا عند التسليم التالي للنتيجة.

Payment Error Status (الافتراضي Failed): رُفضت دفعة معلّقة أو أُلغيت لاحقًا. ومع ذلك تسدّد نتيجة ناجحة لاحقة الطلب.

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

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

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

تبويب VibeFox PayU India Payment Gateway

في Sales > Orders افتح طلبًا مدفوعًا عبر PayU India. وفي أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox PayU India Payment Gateway الحقل PayU transaction ID (mihpayid)، وStore transaction ID (txnid)، والحقل Environment مع شارة Test mode لمدفوعات الاختبار، وStatus لدى PayU، وMode / bank للدفعة، والمبالغ Paid / refund requested (INR)، ونموذج الاسترداد، وسجل الاستردادات، وPayU notes للطلب. وبالنسبة إلى طلب في المراجعة، يعرض تذكيرًا بمراجعة الدفعة. ويُعرض التبويب للمستخدمين الذين لديهم حق الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox PayU India Payment Gateway أدخل Amount (تُملأ تلقائيًا بالمبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via PayU. أكّد السؤال Refund this amount through PayU? This cannot be undone. والاستردادات الكاملة والجزئية مدعومة؛ ويجب أن يكون المبلغ أكبر من صفر ولا يتجاوز الباقي القابل للاسترداد من المبلغ الذي حصّلته PayU. ويلزمك امتلاك صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). ويُرسل الاسترداد عبر واجهة الاسترداد لدى PayU بمفتاح الوضع الذي تمت فيه الدفعة وsalt الخاص به، لذلك يجب ضبط بيانات الاعتماد هذه. ولا يعمل إلا طلب واحد لدى PayU في كل مرة لكل طلب. وإذا رفضت PayU الاسترداد، يعرض التبويب PayU refund failed: مع رسالة PayU، ولا يُسجَّل أي استرداد.

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

لا تعيد مرتجعات المنتجات في Sales > Returns أي مبلغ عبر PayU. ولا تُزامَن الاستردادات التي تُجرى في PayU Dashboard مرة أخرى مع OpenCart.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. وكتلة الترخيص License — VibeFox PayU India Payment Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox PayU India Payment Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. وبعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: opencart-payment-payu-india ورابط 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 India للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل 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 India في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاح والـ salt الخاصين بالـ Mode المحدد مملوءان. وتحقق من أن العميل يدفع بالروبية، وأن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات. وتعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد أو عندما تكون عملة المتجر غير INR.

تمت عملية الدفع لكن الطلب بقي بلا حالة: لم يعد العميل إلى المتجر، ولم يصل أي webhook. أضف عنوان URL للـ webhook من صفحة الإعدادات في PayU Dashboard > Webhooks للدفعات الناجحة والفاشلة، وتأكد من أنه متاح من الإنترنت.

الـ webhook يرد بـ invalid_signature: لم يتطابق hash الخاص بـ PayU. تحقق من أن المفتاح والـ salt الخاصين بوضع الدفعة صحيحان، وأن Salt v1 مستخدم وليس Salt v2. كما يُرفض ردّ دفعة حقيقية وُقّع بـ salt الاختبار، أو العكس. ولا يتغير أي شيء.

الـ webhook يرد بـ not_configured: المفتاح أو الـ salt الخاص بالوضع الذي بدأت فيه الدفعة مفقود. أدخلهما؛ وستعيد PayU محاولة الـ webhook.

الـ webhook يرد بـ verify_unavailable: لم تستطع واجهة verify_payment تأكيد الدفعة بعد. يبقى الطلب في المراجعة، وسيُعاد التحقق عند التسليم التالي.

الـ webhook يرد بـ busy أو retry: كانت عودة العميل بالسلة نفسها تُعالج في الوقت ذاته، أو تعذّر ضبط حالة الطلب. ستعيد PayU محاولة الـ webhook. ويُكتب السبب في السجل.

الـ webhook يرد بـ ignored_unknown_txnid: لم يبدأ هذا المتجر المعاملة، مثل متجر آخر يستخدم حساب PayU نفسه. ولا يتغير أي شيء.

يرى العميل الرسالة PayU India requires a phone number: الطلب لا يحتوي على رقم هاتف. احتفظ بحقل Telephone في صفحة الدفع لديك. وفي OpenCart 4 يمكن للعميل إدخال الرقم في حقل Phone ضمن كتلة التأكيد.

يرى العميل الرسالة This payment method is not available. Please reload the checkout page.: أُوقفت طريقة الدفع في الأثناء، أو بيانات الاعتماد مفقودة، أو صفحة الدفع لم تعد تطابق الطلب. ويجب على العميل إعادة تحميل صفحة الدفع.

الطلب في حالة المراجعة: اقرأ الملاحظات في تبويب VibeFox PayU India Payment Gateway. والسبب هو اختلاف في المبلغ أو العملة، أو تحقق فاشل أو معلّق، أو دفعة لطلب ملغى.

فشل الاسترداد: تعني PayU transaction ID not found for this order. أن الطلب ليس لديه دفعة PayU بعد. وتعني This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set. (أو Live mode) أنه يجب إدخال بيانات اعتماد ذلك الوضع أولًا. وتعني Invalid refund amount: at most … INR can be refunded. أن المبلغ يتجاوز باقي الدفعة.

معلومات قليلة في السجل: تُكتب الأخطاء والتحذيرات دائمًا؛ فعّل Enable Logging لترى أيضًا كل نموذج دفع وكل نتيجة من PayU.

للمطوّرين: قبل توقيع طلب الدفع، تُطلق الإضافة حدث OpenCart باسم payu_p_request_fields مع حقول الطلب والطلب نفسه. ولا يمكن تغيير المفتاح ومعرّف المعاملة والمبلغ وعناوين العودة عبره.

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

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

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

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