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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 6.0 أو أحدث، مثبت ومفعّل. ترفض الإضافة التفعيل بدونه؛ وإذا تم تعطيل WooCommerce لاحقًا، تتوقف الإضافة عن العمل وتعرض إشعارًا في لوحة الإدارة.

PHP: 8.0 أو أحدث.

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

Phone number: تتطلب PayU رقم هاتف لكل عملية دفع. اجعل حقل الهاتف مطلوبًا، أو مرئيًا على الأقل، في صفحة الدفع الخاصة بك.

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

Internet access to your site: مطلوب لإشعار الويب هوك الاختياري. وبدونه، يتم تأكيد الطلبات عندما يعود العميل من PayU.

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

التثبيت

1. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد wcp_payu_india_payment إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > PayU India > Manage، أو انقر على Settings أسفل اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة وانقر على Activate.

5. أدخل Merchant Key وSalt للاختبار، وكذلك Merchant Key وSalt للإنتاج (راجع قسم الإعدادات).

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

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

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > PayU India. أعلى الحقول، تحذرك الصفحة عند فقدان المفتاح أو salt الخاص بالوضع الحالي، وتعرض Test mode is active: payments go to test.payu.in and no real money is charged. في وضع Test، كما تحذرك إذا لم تكن عملة المتجر هي INR (حيث يتم إخفاء بوابة الدفع في صفحة الدفع حينئذٍ).

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

عام

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

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 للحصول على زوج الاختبار.

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

تُرسل طلبات الاسترداد دائمًا إلى الوضع الذي تمت فيه عملية الدفع.

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

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

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

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

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

Return URL: يظهر بالشكل https://your-site/wc-api/payu_p_callback/. يُرسل تلقائيًا إلى PayU مع كل دفعة؛ ولا يلزم تكوين أي شيء يدويًا.

Webhook URL: يظهر بالشكل https://your-site/wc-api/payu_p_webhook/. اختياري لكن يُوصى به: يؤكد المدفوعات حتى إذا أغلق العميل المتصفح قبل العودة إلى المتجر. أضفه في PayU Dashboard > Webhooks للمدفوعات الناجحة والفاشلة. انسخ الرابط تمامًا كما تعرضه صفحة الإعدادات.

متقدم

Verify Payment: Double-check every successful payment with the PayU verify_payment API. يُوصى به. إذا تعذر إكمال التحقق، يُوضع الطلب في حالة «في الانتظار» بدلاً من تعليمه كمدفوع. الافتراضي: مفعّل.

Enable Logging: Log gateway events for troubleshooting. يُسجل في WooCommerce > Status > Logs، تحت المصدر wcp_payu_india_payment. تُسجل الأخطاء والتحذيرات دائمًا؛ ويضيف هذا الخيار الأحداث الأخرى. لا تُسجل المفاتيح أو رموز salt أو البيانات الشخصية للعملاء أبدًا. الافتراضي: معطل.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted (orders are never deleted). الافتراضي: معطل.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا 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 المستضافة. وهناك يدفع العميل بالبطاقة أو NetBanking أو UPI أو المحفظة الإلكترونية.

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

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

بعد الدفع الناجح أو المعلق، يرى العميل صفحة استلام الطلب. وبعد الدفع غير الناجح، يعود العميل إلى صفحة الدفع مع رسالة: 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. وتعمل هذه الرسائل في صفحة الدفع التقليدية ومكون الدفع.

تعمل طريقة الدفع في صفحة الدفع التقليدية، وفي مكون الدفع، وفي صفحة Pay for order. وهي متوافقة مع التخزين عالي الأداء للطلبات في WooCommerce (HPOS).

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

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

حالات الطلب

Pending payment: تم توجيه العميل إلى PayU ولم يدفع بعد.

Processing: تم تأكيد الدفع. تعرض ملاحظة الطلب معرّف معاملة PayU (mihpayid)، ووضع الدفع، ورمز المصرف. معرّف المعاملة للطلب هو PayU mihpayid. وتتحول الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى «مكتمل»، كما تفعل WooCommerce افتراضيًا.

On hold: الدفعة لا تزال معلقة لدى PayU (سواء UPI أو NetBanking)، أو يختلف المبلغ المدفوع أو العملة عن الطلب، أو تعذر الوصول إلى واجهة برمجة التطبيقات verify_payment أو لم تؤكد الدفع بعد، أو وصلت دفعة لطلب تم إلغاؤه سابقًا. توضح ملاحظة الطلب السبب. تحقق من المعاملة في PayU Dashboard وقم بتأكيدها أو استردادها. وعندما يفشل التحقق، يتم تأكيد الطلب تلقائيًا عند استلام النتيجة في المرة التالية.

Failed: تم رفض الدفع أو إلغاؤه. يمكن للعميل محاولة الدفع مرة أخرى.

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

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via PayU India (يُظهر الزر Title الخاص بك). يُدعم الاسترداد الكامل والجزئي؛ ويجب أن يكون المبلغ أكبر من الصفر. يُرسل الاسترداد عبر واجهة برمجة تطبيقات الاسترداد الخاصة بـ PayU باستخدام مفتاح وsalt الوضع الذي تم فيه الدفع، لذا يجب ضبط بيانات الاعتماد تلك. وإذا رفضت PayU الاسترداد، تعرض WooCommerce رسالة PayU ولا يُسجل أي استرداد.

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. تقع كتلة الترخيص في أعلى صفحة WooCommerce > Settings > Payments > PayU India. الصق المفتاح في License key وانقر على Activate. تعرض الكتلة الحالة، مثل تاريخ انتهاء صلاحية الترخيص ونطاقك. استخدم Check now للتحقق من الحالة مجددًا، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك في vibefox.net.

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

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

عند انتهاء صلاحية الترخيص، تستمر الإضافة في العمل، لكن التحديثات والدعم تتطلب تجديدًا. ويُعاد التحقق من الحالة تلقائيًا في الخلفية.

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

PayU India does not appear at checkout: تأكد من أن الترخيص فعّال، وأن Enable/Disable قيد التشغيل، وأن المفتاح وsalt لـ Mode المحدد قد تم ملؤهما. تحقق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي INR. تعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات.

The payment went through, but the order stays Pending payment: لم يعد العميل إلى المتجر، ولم يصل أي ويب هوك. أضف رابط الويب هوك من الإعدادات في PayU Dashboard > Webhooks للمدفوعات الناجحة والفاشلة، وتأكد من إمكانية الوصول إليه عبر الإنترنت.

Webhook answers invalid_signature: لم يتطابق هاش PayU. تأكد من صحة المفتاح وsalt الخاصين بوضع الدفع، ومن استخدام Salt v1 وليس Salt v2. ولا يتم تغيير الطلب.

Webhook answers not_configured: المفتاح أو salt الخاص بالوضع الذي بدأ فيه الدفع مفقود. أدخلهما وسيعيد PayU محاولة إرسال الويب هوك.

Webhook answers verify_unavailable: تعذر على واجهة verify_payment تأكيد الدفع حتى الآن. الطلب قيد الانتظار، وسيتحقق الإرسال التالي منه مجددًا.

The customer sees PayU India requires a phone number: اجعل حقل الهاتف مطلوبًا أو مرئيًا في صفحة الدفع. يُستخدم هاتف الفاتورة، أو هاتف الشحن عندما يكون هو الوحيد المملوء.

The order is On hold: اقرأ ملاحظة الطلب. السبب هو دفعة معلقة عبر UPI أو NetBanking، أو عدم تطابق المبلغ أو العملة، أو تحقق فاشل أو معلق، أو وصول دفعة لطلب ملغى.

Refund fails: PayU transaction ID not found for this order. تعني أن الطلب لا يحتوي على أي دفعة عبر PayU. والرسالة التي تفيد بعدم تعيين Merchant Key/Salt لوضع الدفع تعني أنه يجب عليك إدخال بيانات الاعتماد الخاصة بهذا الوضع أولاً.

Too little in the log: تُسجل الأخطاء والتحذيرات دائمًا؛ قم بتفعيل Enable Logging لرؤية كل طلب ونتيجة لـ PayU أيضًا.

Developer hooks: يغير الفلتر payu_p_request_fields حقول طلب الدفع قبل توقيعها؛ ويغير الفلتر payu_p_icon أيقونة صفحة الدفع.

The license block shows an error: اتبع الرسالة الظاهرة في الكتلة. على سبيل المثال، إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، فحرر خانة في حسابك على vibefox.net وانقر على Check now. وإذا تغيّر عنوان الموقع، فانقر على Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذر الوصول إلى خادم الترخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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