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

المتطلبات

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

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

العملة: الروبية الهندية (INR). تخصم PayU India بالروبية فقط. بالنسبة إلى السلال المقومة بعملات أخرى، يتم إخفاء طريقة الدفع في صفحة الدفع.

رقم الهاتف: تشترط PayU وجود رقم هاتف لكل عملية دفع. اجعل حقل الهاتف في العنوان إلزاميًا، أو على الأقل ظاهرًا، في صفحة الدفع لديك.

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

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

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

التثبيت

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

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

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

4. أدخل Test Merchant Key وSalt، وLive Merchant Key وSalt (انظر قسم الإعدادات).

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

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

عند التثبيت تنشئ الوحدة حالتين للطلب: Awaiting PayU India payment وPayU India payment on hold. يوفّر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ لكن يجب أن تبقى عملة INR مسموحة للوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذّرك الصفحة إذا كان المفتاح أو Salt الخاص بالوضع الحالي مفقودًا، وتعرض Test mode is active: payments go to test.payu.in and no real money is charged. في وضع الاختبار، وتعرض خطأً إذا لم تكن العملة الافتراضية لمتجرك INR (وفي هذه الحالة تُخفى البوابة في صفحة الدفع).

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

PayU India

Enable/Disable: تقوم Enable PayU India Payment Gateway بتفعيل طريقة الدفع أو تعطيلها. الافتراضي: معطّل. إذا فعّلتها دون مفتاح وSalt الوضع الحالي، فستحذّرك الصفحة بعد الحفظ.

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

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

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

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

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

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

Live Merchant Key: مفتاح Merchant Key الخاص بك في PayU للإنتاج.

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

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

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

لا تُعرض رموز salt المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved salts: ضع علامة على salt ثم انقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

عناوين URL للعودة والويب هوك

Return URL: يبدو هكذا https://your-shop/module/wcp_payu_india_payment/return، وقد يحتوي على رمز لغة مثل /en/. يُرسل تلقائيًا إلى PayU مع كل دفعة؛ ولا يلزم إعداد أي شيء.

Webhook URL: يبدو هكذا https://your-shop/module/wcp_payu_india_payment/webhook، وقد يحتوي على رمز لغة. وهو اختياري لكنه موصى به: يؤكد الدفعات حتى لو أغلق العميل المتصفح قبل العودة. أضفه في PayU Dashboard > Webhooks للدفعات الناجحة والفاشلة. انسخ العنوان تمامًا كما تعرضه صفحة Configure. ويجب أن يكون متاحًا من الإنترنت (دون basic auth أو حجب من جدار الحماية). ولا يمنعه وضع الصيانة للمتجر ولا قيود الدول.

يحمل الويب هوك النتيجة الموقّعة نفسها التي تحملها عودة العميل. وتُرفض إشعارات الويب هوك التي لا تحمل هاش PayU صالحًا.

متقدم

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

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

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

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

صفحة الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا PayU India) ويؤكد. وإذا لم يكن لدى عنوان الفوترة ولا عنوان الشحن رقم هاتف ثابت أو محمول، يبقى العميل في صفحة الدفع ويظهر له PayU India requires a phone number. Please enter your phone number and try again. وإلا فسيرى صفحة قصيرة Thank you for your order. You will be redirected to PayU to complete your payment. تُرسل طلب دفع موقّعًا بإجمالي السلة إلى صفحة الدفع المستضافة لـ PayU. وإذا لم يتابع المتصفح تلقائيًا، فإن الصفحة تحتوي على زر Pay with PayU وزر Back to checkout. وفي صفحة PayU يدفع العميل بالبطاقة أو NetBanking أو UPI أو المحفظة. لا يوجد طلب في هذه المرحلة.

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

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

بعد الدفع الناجح أو المعلّق يرى العميل صفحة تأكيد الطلب القياسية. تضيف الدفعة المعلّقة الرسالة Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again.؛ ويضيف الطلب الموضوع قيد الانتظار الرسالة Your payment is being reviewed. We will contact you if anything else is needed.؛ ويعرض الطلب الذي في حالة Payment error أو Canceled الرسالة Your PayU payment was not completed. Please contact us about this order.

بعد دفعة لم تكتمل يعود العميل إلى صفحة الدفع مع رسالة: Payment was not completed. Please try again or choose a different payment method. أو Payment was cancelled. You may try again. أو، عندما يتعذّر التحقق من النتيجة، We could not confirm the payment result. If your account was charged, please contact us before paying again. وإذا كانت النتيجة ما زالت قيد المعالجة عند عودة العميل، تظهر صفحة تحمل We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. وزر Check again.

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

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

حالات الطلب

No order yet: أُعيد توجيه العميل إلى PayU ولم يدفع، أو فشلت الدفعة أو أُلغيت. لا يوجد سوى السلة.

Payment accepted: تم تأكيد الدفع. يُسجَّل الدفع بمعرّف المعاملة من PayU (mihpayid) كمعرّف للمعاملة، وتعرض ملاحظة PayU payment successful. Transaction ID: …, Mode: …, Bank: …

Awaiting PayU India payment: دفعة UPI أو NetBanking ما زالت معلّقة لدى PayU. يتحول الطلب إلى Payment accepted عندما تؤكدها PayU.

PayU India payment on hold: المبلغ أو العملة المدفوعة تختلف عن السلة، أو تعذّر الوصول إلى واجهة verify_payment أو لم تؤكد الدفعة بعد، أو وصلت دفعة لطلب سبق إلغاؤه. وتوضح الملاحظة السبب. تحقق من المعاملة في PayU Dashboard، ثم اضبط الطلب على Payment accepted أو ألغِ الطلب واسترد الدفعة. وعندما يفشل التحقق وحده، يُدفع الطلب تلقائيًا عند التسليم التالي للنتيجة.

Payment error: رُفضت دفعة معلّقة أو أُلغيت لاحقًا. ولا تزال أي نتيجة ناجحة لاحقة تدفع الطلب.

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

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

كتلة الدفع PayU India

تعرض صفحة الطلب كتلة PayU India payment تتضمن معرّف المعاملة من PayU (mihpayid)، ومعرّف المعاملة في المتجر (txnid)، والبيئة، وحالة PayU، والوضع والبنك الخاصان بالدفع، والمبلغ المدفوع ومبلغ الاسترداد المطلوب، وشارة Test mode لدفعات الاختبار، وسجل الاسترداد، وملاحظات الوحدة. وبالنسبة إلى الطلب المعلّق تعرض تذكيرًا بمراجعة الدفعة.

الاسترداد

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

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PayU India Payment Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مموّهًا، والحالة (مثلًا تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. أسفلها سطر Product: presta-payment-payu-india ورابط 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 India للعملاء في صفحة الدفع. إذا بدأت عملية دفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. واجهة المتجر لا تعرف أنك مسجّل الدخول إلى لوحة الإدارة، لذا تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها في صفحة الدفع. يظهر تذكير في Modules > Module Manager في تبويب Alerts. الطلبات الحالية لا تتأثر: الدفعات التي بدأت ما زالت تُؤكَّد عبر الإشعارات، وتعمل الاستردادات.

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

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

لا يظهر PayU India في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاح وSalt الخاصين بـ Mode المحدد مملوءان. تحقق من أن عملة السلة هي INR وأن الوحدة مسموح بها لتلك العملة ولدولة العميل ومجموعته في Payment > Preferences. وتعرض صفحة Configure تحذيرًا عند غياب بيانات الاعتماد وعند اختلاف عملة المتجر عن INR.

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

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

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

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

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

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

يرى العميل الرسالة PayU India requires a phone number: اجعل حقل الهاتف في العنوان إلزاميًا أو ظاهرًا في صفحة الدفع. يُستخدم عنوان الفوترة أولًا ثم عنوان الشحن.

الطلب في حالة PayU India payment on hold: اقرأ الملاحظات في كتلة PayU India payment. والسبب إما عدم تطابق المبلغ أو العملة، أو فحص فاشل أو معلّق، أو دفعة لطلب ملغى.

فشل الاسترداد: 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 أيضًا.

خطاف للمطورين (Hook): تغيّر actionPayuPRequestFields حقول طلب الدفع قبل توقيعها. ولا يمكن تغيير المفتاح ومعرّف المعاملة والمبلغ وعناوين العودة من خلاله.

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

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

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