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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل بيانات اعتماد الاختبار وبيانات اعتماد الإنتاج (راجع التهيئة). لا يلزم إعداد عنوان URL للتأكيد في PayU.

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

التهيئة

كل الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > PayU LATAM. تعرض الصفحة فوق الحقول تحذيرًا عند تفعيل وضع الاختبار (Sandbox mode. تُرسَل المدفوعات إلى بيئة اختبار PayU ولا تُخصم أموال حقيقية.)، وعند غياب معرّف التاجر أو معرّف الحساب أو مفتاح API للبيئة الحالية، وعندما لا تعالج PayU LATAM عملة المتجر. في الحالتين الأخيرتين، لا تظهر PayU LATAM في صفحة الدفع. وفي قائمة طرق الدفع، تُعلَّم PayU LATAM بأنها تحتاج إلى إعداد حتى تُملأ بيانات الاعتماد الثلاثة للبيئة الحالية. تُتجاهَل المسافات في بداية بيانات الاعتماد أو نهايتها.

عام

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

Title: عنوان طريقة الدفع الذي يظهر للعميل أثناء الدفع. الافتراضي: PayU LATAM.

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

البيئة

Sandbox: Enable the PayU sandbox (test mode). تُرسَل المدفوعات إلى بيئة اختبار PayU باستخدام بيانات اعتماد الاختبار أدناه، ولا تُخصم أموال حقيقية. عند الإيقاف، تُستخدم بيانات اعتماد الإنتاج وصفحة الدفع الفعلية لدى PayU. الافتراضي: on.

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

تجدها في وحدة PayU: Settings > Technical configuration (معرّف التاجر ومفتاح API) وAccounts (معرّف حساب البلد الذي تبيع فيه). يتضمن القسم رابطًا إلى لوحة التاجر لدى PayU.

Merchant ID: المعرّف الرقمي لتجارتك في PayU.

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

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

بيانات اعتماد الاختبار

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

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

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

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

تتذكر كل محاولة دفع بيئتها. يُتحقق من تأكيد دفعة الاختبار بمفتاح API ومعرّف التاجر للاختبار، ومن تأكيد دفعة الإنتاج بقيم الإنتاج، لذلك تستمر المدفوعات المعلّقة في العمل بعد التبديل. عند التحديث من الإصدار 1.0 الذي كان يستخدم مجموعة واحدة من بيانات الاعتماد، تُنسخ القيم القديمة إلى حقول الاختبار إذا كانت بيئة الاختبار مفعّلة. راجع الإعدادات بعد التحديث.

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

يعرض هذا القسم عنوان URL الذي تبلغ فيه PayU عن نتيجة كل دفعة. يكون على نحو https://your-site/wc-api/payu_lp/. ترسله الإضافة إلى PayU مع كل دفعة، فلا يوجد ما يلزم إعداده في PayU. يجب أن تكون الصفحة متاحة من الإنترنت. توقّع PayU التأكيد بمفتاح API الخاص بك. تُرفض التأكيدات التي لا تحمل توقيعًا صالحًا، أو تحمل معرّف تاجر آخر، أو مرجع دفع لم يصدره هذا المتجر للطلب. تعالج الإضافة حالات معاملات PayU التالية:

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

6 (declined), 5 (expired), 104 (error): فشل الدفع. يُعلَّم الطلب غير المدفوع الخاص بالمحاولة الأخيرة بحالة فشل.

7 and other pending states: الدفع معلّق، مثل دفعة نقدية أو مصرفية لم يكملها العميل بعد. يوضع الطلب قيد الانتظار.

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

متقدم

Debug log: يسجّل Log payment requests and PayU notifications التفاصيل في WooCommerce > Status > Logs، بالمصدر wcp_payu_latam_payment، بلا مفاتيح أو بيانات شخصية. تُسجّل الأخطاء والإشعارات المرفوضة دائمًا. الافتراضي: off.

Delete data: Delete the settings and logs when the plugin is deleted. إيقاف الإضافة لا يحذف أي شيء أبدًا. تبقى بيانات PayU المحفوظة في الطلبات. الافتراضي: off.

الدفع

يختار العميل طريقة الدفع (افتراضيًا PayU LATAM) ويقدّم الطلب. في كتلة Checkout بوضع الاختبار، يرى العميل Sandbox mode: no real payment is made. يبقى الطلب بانتظار الدفع، وينتقل العميل إلى صفحة دفع في متجرك تحتوي على النص Thank you for your order. You are being redirected to PayU LATAM to complete the payment… ترسل الصفحة نموذجًا موقّعًا إلى صفحة PayU WebCheckout تلقائيًا. إن لم يحدث ذلك، ينقر العميل على Pay with PayU LATAM أو على Cancel order لإلغاء الطلب.

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

تبدأ كل زيارة لصفحة الدفع محاولة دفع جديدة بمرجع خاص بها (رقم الطلب وطابع زمني). تُحفَظ آخر 30 محاولة للطلب: إذا دفع العميل في علامة تبويب PayU قديمة، تُقبل الدفعة أيضًا.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد PayU عبر التأكيد الموقّع. عودة العميل من PayU لا تجعل الطلب مدفوعًا أبدًا. عند عودة العميل:

بعد رفض أو انتهاء صلاحية أو خطأ موقّع: يُعلَّم الطلب فورًا بحالة فشل، وتعرض WooCommerce صفحة الدفع الفاشل المعتادة مع خيار الدفع مجددًا.

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

في الحالات الأخرى: يرى العميل صفحة استلام الطلب. ما دام الطلب بانتظار الدفع، يظهر النص We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. وللطلب قيد الانتظار، يظهر النص 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.

إذا غابت بيانات اعتماد البيئة الحالية، يرى العميل PayU LATAM is not available right now. Please choose another payment method. ولعملة طلب غير مدعومة، تكون الرسالة PayU LATAM does not accept payments in متبوعة بالعملة. لا يُدفع الطلب المدفوع مرة أخرى: تعرض صفحة الدفع This order has already been paid.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية وكتلة Checkout وصفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى PayU ولم يدفع بعد، أو لم ترسل PayU التأكيد بعد.

Processing: أكدت PayU الدفع وتطابق المبلغ والعملة. تعرض ملاحظة الطلب معاملة PayU والمبلغ وطريقة الدفع و[sandbox] لمدفوعات الاختبار. معرّف معاملة الطلب هو معرّف معاملة PayU. تصبح الطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل بحالة مكتمل، وفق السلوك الافتراضي لـ WooCommerce.

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

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

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

الاستردادات

لا تُنفَّذ الاستردادات من WooCommerce. استرد المعاملة في وحدة PayU، وسجّل الاسترداد يدويًا في WooCommerce عند الحاجة.

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

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

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

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

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

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

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

تم الدفع لكن الطلب يظل Pending payment: لم يصل تأكيد PayU إلى متجرك أو رُفض. تحقق من أن عنوان URL للتأكيد الظاهر في الإعدادات متاح من الإنترنت (ليس موقعًا محليًا ولا محجوبًا بوضع صيانة أو جدار حماية أو حماية بكلمة مرور). راجع التأكيدات المرفوضة في WooCommerce > Status > Logs، بالمصدر wcp_payu_latam_payment. تعيد PayU إرسال التأكيد بعد أي رد بخطأ.

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

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

يتلقى التأكيد الرد Gateway not configured: ينقص مفتاح API أو معرّف التاجر لبيئة الدفع، مثل إزالة بيانات اعتماد الاختبار أثناء تعليق دفعة اختبار. أدخلها مجددًا؛ تعيد PayU محاولة التأكيد.

يتلقى التأكيد الرد Busy, retry later: كان طلب آخر يحدّث الطلب في الوقت نفسه. لم يتغير شيء، وترسل PayU التأكيد مجددًا.

يتلقى التأكيد الرد Unknown reference: لا ينتمي مرجع الدفع إلى طلب PayU LATAM في هذا المتجر، مثل تغيير طريقة دفع الطلب أو حذفه.

الطلب On hold: اقرأ ملاحظة الطلب. لا يزال الدفع معلّقًا لدى PayU (نقدي أو مصرفي)، أو اختلف المبلغ المدفوع أو العملة عن الطلب، أو وصل الدفع بعد إلغاء الطلب. راجع المعاملة في وحدة PayU.

عملات أخرى أو حقول النموذج: يمكن للمطوّرين تعديل قائمة العملات بالمرشح payu_lp_supported_currencies، وأيقونة الدفع بالمرشح payu_lp_icon، وحقول نموذج WebCheckout بالمرشح payu_lp_payment_fields.

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

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

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

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