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

المتطلبات

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

PHP: 8.0 أو أحدث.

العملة: يجب أن تكون عملة الدفع للعميل ARS أو BRL أو CLP أو COP أو MXN أو PEN أو USD، وهي العملات التي تعالجها PayU Latam في الأرجنتين والبرازيل وتشيلي وكولومبيا والمكسيك وبنما وبيرو. وبالعملات الأخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب PayU Latam: تحتاج إلى ثلاث قيم من حساب التاجر لدى PayU: معرّف التاجر (merchant ID)، ومعرّف الحساب (account ID) للدولة التي تبيع فيها، ومفتاح API. تجدها في لوحة تحكم التاجر لدى PayU ضمن Settings > Technical configuration (merchant ID, API key) وAccounts (account ID). ولأغراض الاختبار تنشر PayU بيانات اعتماد عامة لبيئة sandbox وبطاقات اختبار في صفحة "Test your solution" من وثائق المطورين لديها. لا تحتاج إلى API Login أو غيره من بيانات اعتماد API، لأن الدفع يتم في الصفحة المستضافة لدى PayU ولا تستدعي الإضافة واجهة PayU البرمجية أبدًا.

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة وبيئة sandbox مفعّلة.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ زر Save الموجود أسفل القائمة الصفحة كاملةً. تعرض الصفحة فوق الإعدادات Sandbox mode. Payments go to the PayU sandbox and no real money is charged. طالما أن sandbox مفعّلة، كما تعرض خطأً عند غياب معرّف التاجر أو معرّف الحساب أو مفتاح API للبيئة الحالية (وعندها لا تُعرض PayU Latam في صفحة الدفع)، وتحذيرًا عندما لا تعالج PayU Latam العملة الافتراضية للمتجر. وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب ألا يكون الحقل Title فارغًا أو أطول من 128 حرفًا (تعرض الصفحة Enter a title for the payment method (at most 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0، ويجب أن توجد المنطقة الجغرافية وحالات الطلب. وإلا فلن يُحفظ شيء. تُتجاهل المسافات في بداية بيانات الاعتماد أو نهايتها.

PayU LATAM

Enable/Disable: يؤدي Enable PayU LATAM إلى تفعيل طريقة الدفع أو تعطيلها. الافتراضي: معطّل.

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

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

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

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

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

البيئة

Sandbox: تُرسل المدفوعات إلى sandbox الخاصة بـ PayU ببيانات اعتماد sandbox، ولا يُخصم أي مبلغ حقيقي. عند التعطيل تُستخدم بيانات اعتماد الإنتاج وصفحة الدفع الحقيقية لدى PayU. الافتراضي: مفعّل. وطالما كان مفعّلًا يرى العميل في خطوة Confirm Order الرسالة Sandbox mode: no real money is charged.

بيانات اعتماد الإنتاج

اعثر عليها في لوحة تحكم التاجر لدى PayU: Settings > Technical configuration (merchant ID, API key) وAccounts (account ID للدولة التي تبيع فيها). يحتوي هذا القسم على رابط إلى لوحة تحكم التاجر لدى PayU.

Merchant ID: المعرّف الرقمي لحساب التاجر لدى PayU.

Account ID: معرّف حساب PayU. يوجد حساب واحد لكل دولة.

API Key: المفتاح السري المستخدم لتوقيع المدفوعات والتحقق من إشعارات PayU.

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

تنشر PayU بيانات اعتماد اختبار عامة وبطاقات اختبار لبيئة sandbox الخاصة بها. يحتوي هذا القسم على رابط إلى صفحة "Test your solution" في وثائق PayU.

Sandbox merchant ID: معرّف التاجر لبيئة sandbox الخاصة بـ PayU.

Sandbox account ID: معرّف الحساب لبيئة sandbox الخاصة بـ PayU.

Sandbox API key: مفتاح API لبيئة sandbox الخاصة بـ PayU.

لا تُعرض مفاتيح API المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح محفوظ، حدّد Clear saved secret on save أسفل الحقل ثم انقر على Save.

تحتفظ كل محاولة دفع ببيئتها. يُتحقق من تأكيد دفعة sandbox باستخدام مفتاح API ومعرّف التاجر الخاصين ببيئة sandbox، ويُتحقق من تأكيد الدفعة الحقيقية باستخدام القيم الحقيقية، لذلك تستمر المدفوعات المعلقة في العمل بعد تبديل البيئة. تُعلَّم مدفوعات sandbox كذلك في ملاحظات الطلب.

عنوان URL للتأكيد

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

4 (approved): تم الدفع. يُعلَّم الطلب كمدفوع عندما يطابق المبلغ والعملة الطلب.

6 (declined), 5 (expired), 104 (error): فشل الدفع. يبقى الطلب الذي بلا حالة بلا حالة، ويُحتفظ بسلة التسوق.

7, 10, 12, 14, 15, 18 (pending): الدفع في انتظار الإتمام، مثل دفعة نقدية أو تحويل بنكي لم يُكمله العميل بعد. يحصل الطلب على الحالة Awaiting Payment Status.

تُضاف الحالات الأخرى كملاحظة فقط. ومن دون التأكيد لا يحصل الطلب على أي حالة.

الطلبات

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

Order Status After Payment: دفعة معتمدة (حالة PayU رقم 4) بالمبلغ والعملة المتوقعين. الافتراضي: Processing.

Awaiting Payment Status: دفعة معلقة (الحالات 7 و10 و12 و14 و15 و18، مثل دفعة نقدية أو تحويل بنكي لم يكتمل بعد). يحصل الطلب على Order Status After Payment عندما تؤكدها PayU. الافتراضي: Pending.

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

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

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

متقدم

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

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا PayU LATAM). وفي خطوة Confirm Order يرى العميل وصفك؛ ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. عندما ينقر العميل على Confirm Order، تُعدّ الإضافة نموذج دفع موقّعًا، وتعرض الصفحة You are being redirected to PayU LATAM to complete the payment... وترسل النموذج تلقائيًا إلى صفحة PayU WebCheckout. وإذا لم يحدث ذلك، ينقر العميل على Pay with PayU LATAM.

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

كل نقرة على Confirm Order تبدأ محاولة دفع جديدة برقم مرجعي خاص بها (OC ورقم الطلب وطابع زمني). وفي OpenCart 4 تدفع كل محاولة جديدة الطلب نفسه في صفحة الدفع. تُتذكَّر المحاولات السابقة: إذا دفع العميل من تبويب PayU قديم، يبقى الدفع معترفًا به.

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده PayU بالتأكيد الموقّع. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون. لا يُعلِّم العميل العائد من PayU أي طلب كمدفوع أبدًا. وعندما يعود العميل:

بعد رفض أو انتهاء صلاحية أو خطأ موقّع: يعود العميل إلى صفحة الدفع مع Your PayU LATAM payment was not approved، وسبب PayU إن وُجد، وYou can try again or choose another payment method. ويُحتفظ بسلة التسوق.

دون معاملة PayU (غادر العميل صفحة PayU): يعود العميل إلى صفحة الدفع مع Your PayU LATAM payment was not completed. You can try again or choose another payment method.

للطلب حالة بالفعل: يرى العميل صفحة نجاح الطلب في OpenCart. وبالنسبة للدفعة المعلقة تظهر أيضًا الرسالة Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment. وبالنسبة لدفعة قيد المراجعة تظهر الرسالة We have received your PayU LATAM payment and are reviewing it. We will contact you if anything is needed. وإذا فشلت الدفعة المعلقة لاحقًا، يعود العميل إلى صفحة الدفع مع السبب.

لم تؤكد PayU بعد: تعرض الصفحة We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. (أو نص الانتظار المذكور أعلاه للدفعة النقدية أو التحويل البنكي) مع زر Check again وزر Back to checkout. ويضبط التأكيد حالة الطلب فور وصوله.

وفي OpenCart 4 تُعرض رسائل الدفع أعلى صفحة الدفع.

في OpenCart 3 ينشئ OpenCart طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، وفي OpenCart 4 يُحدَّث طلب الدفع، لكن سلة التسوق تُدفع مرة واحدة فقط: فإذا كان طلب آخر من السلة نفسها مدفوعًا أو بانتظار الدفع أو قيد المراجعة، فإن Confirm Order يقود مباشرة إلى صفحة النجاح. ويُعدّ أي تغيير في السلة، بما في ذلك الكمية الجديدة، سلةً جديدة تحتاج إلى دفعة خاصة بها. وإذا كانت بيانات اعتماد البيئة الحالية مفقودة، يرى العميل PayU LATAM is not available right now. Please choose another payment method.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تُعرض صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا فشل دفعه النقدي أو ألغيته)، يُعاد العميل إلى صفحة الدفع مع Your PayU LATAM payment was not approved وسبب PayU إن وُجد. وإذا كان قد دُفع ثم أغلقه المتجر، أو كان قد دُفع لسلة سابقة وتغيّرت السلة منذ ذلك الحين، تكون الرسالة Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. وتدفع خطوة Confirm Order التالية طلبًا جديدًا. ولا يُعرض طلب مغلق أبدًا على أنه مدفوع.

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

الطلبات

حالات الطلب

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

Order Status After Payment (default Processing): أكدت PayU الدفع، ويطابق المبلغ والعملة الطلب. تعرض ملاحظة المعاملة والمبلغ وطريقة الدفع، وما إذا كانت دفعة sandbox.

Awaiting Payment Status (default Pending): تُبلغ PayU عن الدفع بأنه معلّق (دفعة نقدية أو تحويل بنكي). ينتقل الطلب إلى Order Status After Payment عندما تؤكد PayU الدفع، أو إلى Failed Payment Status إذا فشل. ويُبلغ OpenCart العميل بهذه التغييرات.

On Hold (Review) Status (default Pending): المبلغ المدفوع أو العملة لا يطابقان إجمالي الطلب، أو وُوفق على دفع لطلب كان قد أُلغي. توضح الملاحظة الحالة المقصودة: راجع الدفع في لوحة تحكم PayU، ثم عالج الطلب أو استعده أو استرد الدفع.

Failed Payment Status (default Failed): دفعة معلقة من آخر محاولة رُفضت لاحقًا أو انتهت صلاحيتها أو انتهت بخطأ. تعرض الملاحظة رسالة PayU. ويُضاف رفض محاولة أقدم، أو رفض طلب لديه دفعة معتمدة بالفعل، كملاحظة فقط.

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

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

تبويب VibeFox PayU LATAM Payment

في Sales > Orders افتح طلبًا مدفوعًا عبر PayU LATAM. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض التبويب VibeFox PayU LATAM Payment الحقول Reference وTransaction ID وPayU reference وStatus وحالة PayU، والمبلغ Requested، وAmount reported by PayU، وPayment method، وPayU message، وشارة SANDBOX لدفعات sandbox، وقائمة بكل Payment attempts الخاصة بالسلة، وPayU LATAM notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

لا تُجرى الاستردادات من OpenCart. استرد المعاملة في لوحة تحكم PayU، ثم سجّل الاسترداد يدويًا في OpenCart.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PayU LATAM Payment هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit، فوق الإعدادات. ألصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-payu-latam والرابط 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 LATAM للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. ويظل مستخدم الإدارة المسجّل دخوله إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، معلّمة بـ (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. في OpenCart 4 لا تتوفر هذه المعاينة: فالمتجر لا يرى تسجيل دخول الإدارة، لذلك تُخفى طريقة الدفع عن الجميع دون مفتاح نشط. وبعد أن تفتح صفحة Edit مرة واحدة يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. ولا تتأثر الطلبات الحالية: فالدفعات التي بدأت بالفعل تظل تُؤكَّد بتأكيد PayU وعودة العميل.

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

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

لا تظهر PayU LATAM في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن معرّف التاجر ومعرّف الحساب ومفتاح API للبيئة الحالية مُدخلة: بيانات اعتماد sandbox عندما يكون Sandbox مفعّلًا، وبيانات اعتماد الإنتاج عندما يكون معطّلًا. تحقق أيضًا من أن عملة العميل هي ARS أو BRL أو CLP أو COP أو MXN أو PEN أو USD، وأن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمت عملية الدفع لكن الطلب يبقى بلا حالة: لم يصل تأكيد PayU إلى متجرك أو رُفض. تحقق من أن عنوان URL للتأكيد الظاهر في الإعدادات متاح عبر الإنترنت (لا موقع محلي ولا جدار حماية ولا حماية بكلمة مرور). انظر إلى الحقل Log في صفحة الإضافة للعثور على التأكيدات المرفوضة. ترسل PayU التأكيد مرة أخرى بعد أي رد خطأ.

يرد التأكيد بـ Invalid signature: لم يُوقَّع التأكيد بمفتاح API الخاص ببيئة الدفع. تحقق من API Key للمدفوعات الحقيقية، ومن Sandbox API key لمدفوعات sandbox.

يرد التأكيد بـ Merchant mismatch: معرّف التاجر في التأكيد يختلف عن Merchant ID أو Sandbox merchant ID لبيئة الدفع. أدخل معرّف التاجر لحساب PayU الذي يعالج المدفوعات.

يرد التأكيد بـ Gateway not configured: مفتاح API أو معرّف التاجر لبيئة الدفع مفقود، مثلًا لأن بيانات اعتماد sandbox حُذفت أثناء انتظار دفعة sandbox. أدخلها مرة أخرى، وستعيد PayU محاولة التأكيد.

يرد التأكيد بـ Retry: كانت سلة التسوق قيد المعالجة بطلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. سترسل PayU التأكيد مرة أخرى. انظر إلى Log لمعرفة السبب.

يرد التأكيد بـ Unknown reference: لم يُصدر هذا المتجر الرقم المرجعي للدفع.

يعرض عنوان URL للتأكيد Method not allowed في المتصفح: هذا طبيعي. فالعنوان يقبل الطلبات الصادرة من PayU فقط.

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

الطلب في حالة المراجعة: اقرأ الملاحظات في تبويب VibeFox PayU LATAM Payment. كان المبلغ المدفوع أو العملة مختلفًا عن الطلب، أو وصل الدفع بعد إلغاء الطلب. تحقق من المعاملة في لوحة تحكم PayU.

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

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

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

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