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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبت ومفعّل. ترفض الإضافة التفعيل بدونه؛ وإذا تم إيقاف WooCommerce لاحقًا، فلا تقوم الإضافة بأي إجراء وتُظهر تنبيهًا في لوحة الإدارة.

PHP: 8.0 أو أحدث.

عملة المتجر: إحدى العملات التالية: 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 sandbox منفصل.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل مفاتيح Sandbox الأربعة ومفاتيح Live الأربعة (انظر قسم الإعدادات). لا يلزم ضبط أي رابط إشعار في PayU.

6. فعّل الخيار Enable/Disable. اترك Test Mode مفعّلًا حتى تجري دفعة تجريبية، ثم ألغِ تحديده لقبول مدفوعات حقيقية باستخدام مفاتيح Live.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > PayU. أعلى الحقول، تحذّرك الصفحة طالما كان وضع sandbox مفعّلًا، أو إذا كان أحد المفاتيح الأربعة للوضع الحالي مفقودًا، أو إذا كانت PayU لا تقبل عملة المتجر. وفي الحالتين الأخيرتين، لا تظهر PayU في صفحة الدفع.

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

عام

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

Title: عنوان طريقة الدفع المعروض للعميل. الافتراضي: PayU.

Description: وصف طريقة الدفع المعروض للعميل. الافتراضي: Pay securely via PayU.

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

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

Test Mode: الخيار Enable sandbox (test) mode. يستخدم بيئة PayU sandbox ومفاتيح Sandbox الموضحة أدناه. لا يُخصم أي مال حقيقي. في صفحة الدفع الكلاسيكية وفي كتلة Checkout يرى العميل Sandbox mode — no real money is charged. أوقف تشغيله لقبول مدفوعات حقيقية بمفاتيح Live. الافتراضي: تشغيل.

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

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

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

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

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

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

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

Sandbox OAuth Client Secret: سر OAuth client_secret لنقطة بيع sandbox.

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

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

يعرض هذا القسم رابط الإشعار، والذي يبدو على النحو https://your-site/wc-api/wc_pu_payment/. ترسله الإضافة إلى PayU مع كل عملية دفع، لذا لا يلزم إعداد أي شيء في لوحة PayU. تأكد من إمكانية الوصول إليه من الإنترنت (ألا يكون محجوبًا بجدار حماية أو وضع صيانة أو مصادقة HTTP).

متقدم

Receive payments automatically: الخيار Automatically receive payments waiting for confirmation. يهم هذا الخيار فقط إذا كان الاستلام التلقائي معطلًا لنقطة البيع الخاصة بك في لوحة PayU؛ حيث تنتظر المدفوعات حينها التأكيد (WAITING_FOR_CONFIRMATION). عند تفعيل هذا الخيار، تستلم الإضافة تلك المدفوعات فورًا. وعند إيقافه، توضع تلك الطلبات في «في الانتظار» وتستلم أنت الدفعة أو تلغيها بإجراءات الطلب Receive PayU payment وCancel PayU payment. الافتراضي: تشغيل.

Logging: الخيار Enable logging يكتب الأحداث التقنية (أرقام الطلبات، ومعرّفات طلبات PayU، والحالات، والأخطاء، دون مفاتيح أو بيانات شخصية) إلى WooCommerce > Status > Logs، المصدر wcp_payu_payment. الافتراضي: إيقاف.

Delete data on uninstall: الخيار Delete the plugin settings and logs when the plugin is deleted. لا تُحذف الطلبات وبيانات دفعها أبدًا. وإلغاء تفعيل الإضافة يحتفظ بكل شيء. الافتراضي: إيقاف.

صفحة الدفع

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

تحصل كل محاولة دفع على طلب PayU خاص بها. وعندما يدفع العميل مجددًا (بعد دفع فاشل أو ملغى، أو من صفحة Pay for order)، يُلغى دفع PayU السابق غير المكتمل لدى PayU، فلا يمكن سداد رابط دفع قديم مرتين.

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

في صفحة استلام الطلب، وطالما كان الطلب لا يزال في حالة «بانتظار الدفع»، يرى العميل الرسالة We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again: أو بعد دفع فاشل يرى The payment was not completed. You can try again:، ولكل منهما زر Pay again. وبالنسبة لطلب موضوع في الانتظار، تكون الرسالة Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

إذا تعذر على PayU بدء الدفع، يرى العميل Payment error. Please try again or choose another payment method. يُسجَّل السبب التقني (رمز HTTP وحالة PayU) في السجل وفي ملاحظة الطلب PayU payment could not be started:. وإذا كانت مفاتيح الوضع الحالي مفقودة، تكون الرسالة Payment gateway is not configured properly. Please contact the administrator.

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

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

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

حالات الطلب

Pending payment: تم توجيه العميل إلى PayU ولم يدفع بعد. تُظهر ملاحظة الطلب معرّف طلب PayU والبيئة (sandbox أو live).

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

On hold: المبلغ أو العملة المسددة لا تطابق الطلب، أو تم سداد دفعة لطلب كان ملغيًا، أو تنتظر الدفعة تأكيدك (الاستلام التلقائي معطل أو تعذر الاستلام). توضح ملاحظة الطلب الحالة والإجراء المطلوب اتخاذه.

Failed: أُلغيت أحدث دفعة PayU أو رُفضت. يمكن للعميل محاولة السداد مرة أخرى.

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

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

بالنسبة لطلب غير مدفوع يتضمن دفعة بانتظار التأكيد، تقدم شاشة الطلب إجراءين: Receive PayU payment (waiting for confirmation) وCancel PayU payment (release the funds). اختر أحدهما وانقر زر التحديث. يُضاف الإجراء إلى ملاحظات الطلب مع اسم المستخدم الخاص بك، وتُطبَّق حالة PayU الجديدة فورًا.

الاستردادات

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

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

تحتفظ الطلبات الموضوعة «في الانتظار» بسبب عدم تطابق المبلغ أو العملة بمعرّف طلب PayU كمعرّف معاملة لها، مما يتيح استرداد الدفعة من WooCommerce وكذلك من لوحة PayU.

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

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

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

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

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

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

لا تظهر PayU في صفحة الدفع: تأكد من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن المفاتيح الأربعة للوضع الحالي مكتملة: مفاتيح Sandbox في وضع sandbox، ومفاتيح Live في وضع live. وتحقق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) إحدى العملات المدعومة. تعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشاكل.

تم الدفع لكن الطلب ما زال بانتظار الدفع: لم تسلّم PayU الإشعار بعد، ولم يكتشف فحص الحالة في صفحة العودة دفعة مكتملة. تأكد من إمكانية الوصول إلى رابط الإشعار المعروض في الإعدادات عبر الإنترنت. فعّل Logging لمعرفة ما يرد من بيانات.

يرد الإشعار بـ Invalid signature: لم يُوقَّع الإشعار بالمفتاح الثاني Second Key لأي من البيئتين. راجع Live Second Key (MD5) وSandbox Second Key (MD5). والرد Invalid signature for this payment يعني أن الإشعار وُقّع بمفتاح البيئة الأخرى غير البيئة التي تم فيها الدفع.

يرد الإشعار بـ Ignored: لا ينتمي طلب PayU إلى أي طلب في هذا المتجر تم سداده بواسطة PayU، كأن ينتمي لمتجر آخر على نفس نقطة البيع POS. وتتوقف PayU عن إعادة المحاولة.

لم يُنشأ الدفع: فعّل Logging وافحص WooCommerce > Status > Logs، المصدر wcp_payu_payment. يعرض السجل رمز HTTP وحالة PayU. والرسالة Could not authenticate with PayU (check the OAuth client ID / secret). تعني وجود خطأ في مفاتيح OAuth للوضع الحالي.

الطلب في حالة «في الانتظار»: اقرأ ملاحظة الطلب. يرجع السبب إلى عدم تطابق المبلغ أو العملة، أو دفع بعد إلغاء الطلب، أو دفع ينتظر التأكيد. وفي الحالة الأخيرة استخدم إجراءات الطلب Receive PayU payment أو Cancel PayU payment.

فشل الاسترداد: الرسالة This order has no completed PayU payment. Cannot process refund. تعني أن الطلب لا يحتوي على طلب PayU مكتمل السداد. وتشير رسالة نقص مفاتيح Sandbox أو Live إلى أن الدفع تم في تلك البيئة ومفاتيحها غير مضبوطة؛ أدخلها وأعد المحاولة.

عملات أخرى: يمكن للمطورين تعديل قائمة العملات عبر الفلتر wc_pu_supported_currencies وتعديل أيقونة صفحة الدفع عبر الفلتر wc_pu_icon.

تعرض كتلة الترخيص خطأً: اتبع التعليمات الواردة في رسالة الكتلة. مثلًا، إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، حرّر مكانًا في حسابك بـ vibefox.net وانقر Check now. وإذا تغير عنوان الموقع، انقر Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذر الاتصال بخادم التراخيص، تستمر الإضافة في العمل وفق آخر حالة معلومة.

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

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

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