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

المتطلبات

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

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

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

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

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

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

التثبيت

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

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox PayU LATAM Payment في قائمة الوحدات النمطية وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة النمطية حالتين للطلب، هما Awaiting PayU LATAM payment وPayU LATAM payment on hold. يوفّر PrestaShop طريقة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها في Payment > Preferences. يجب أيضًا تحديد أي دولة تُفعَّل لاحقًا هناك للوحدة النمطية.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة النمطية: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. تعرض الصفحة فوق الحقول: Sandbox mode. Payments go to the PayU sandbox and no real money is charged. عندما يكون وضع الاختبار مفعّلًا، وخطأً عند غياب معرّف التاجر أو معرّف الحساب أو مفتاح API للبيئة الحالية، وتحذيرًا عندما لا تعالج PayU LATAM العملة الافتراضية للمتجر. طالما بيانات الاعتماد ناقصة، لا تظهر PayU LATAM في صفحة الدفع. تُتجاهل المسافات في بداية بيانات الاعتماد أو نهايتها. لا تحفظ الصفحة حقل Title فارغًا، وتعرض Enter a title for the payment method.

PayU LATAM

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

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

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

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

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

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

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

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

Clear saved secrets: حدّد API Key أو Sandbox API key وانقر على Save لإزالة المفتاح المحفوظ. الحقل الفارغ يُبقي القيمة المحفوظة.

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

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

يعرض هذا القسم عنوان URL الذي تبلغ PayU عبره بكل نتيجة دفع. مع تفعيل الروابط الودية يبدو هكذا: https://your-shop/module/wcp_payu_latam_payment/confirmation، وقد يتضمن رمز لغة مثل /en/. تُرسله الوحدة النمطية إلى PayU مع كل دفعة، لذلك لا يوجد ما يُضبط في PayU. يجب أن يكون عنوان URL متاحًا من الإنترنت. يعمل أيضًا أثناء وضع الصيانة للمتجر، ولا يتأثر بقيود الدول في متجرك. توقّع PayU التأكيد بمفتاح API الخاص بك. تُرفض التأكيدات التي لا تحمل توقيعًا صالحًا، أو التي تحمل معرّف تاجر آخر، أو التي تتضمن مرجع دفع لم يصدره هذا المتجر. تتعامل الوحدة النمطية مع حالات المعاملات التالية لدى PayU:

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

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

7, 10, 12, 14, 15, 18 (pending): الدفعة معلّقة، مثل دفعة نقدية أو مصرفية لم يُكملها العميل بعد. يُنشأ الطلب في Awaiting PayU LATAM payment.

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

متقدم

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

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

Delete data: يحذف الإعدادات والسجلات عند إلغاء تثبيت الوحدة النمطية. تبقى بيانات PayU الخاصة بالطلبات (محاولات الدفع) وحالات الطلب محفوظة. الافتراضي: معطّل.

الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا PayU LATAM) ويؤكد. تعرض إحدى صفحات متجرك You are being redirected to PayU LATAM to complete the payment... وترسل نموذجًا موقعًا إلى صفحة PayU WebCheckout تلقائيًا. إذا لم يحدث ذلك، ينقر العميل على Pay with PayU LATAM، أو على Back to checkout للعودة. لا يوجد طلب في هذه المرحلة.

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

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

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده PayU بالتأكيد الموقّع. العميل العائد من 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.

الطلب موجود مسبقًا: يرى العميل صفحة تأكيد الطلب المعتادة. بالنسبة لطلب في Awaiting PayU LATAM payment تعرض 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. وبالنسبة لطلب في Payment error تعرض Your PayU LATAM payment was not approved. Please contact us.

لم تؤكد 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. ينشئ التأكيد الطلب فور وصوله.

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

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

الطلبات

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى PayU ولم يدفع، أو رُفضت الدفعة، أو لم ترسل PayU التأكيد بعد. لا توجد سوى السلة.

Payment accepted: أكدت PayU الدفعة، والمبلغ والعملة متطابقان. تُسجَّل الدفعة بمعرّف معاملة PayU، وتعرض ملاحظة المعاملة والمبلغ وطريقة الدفع و[sandbox] للدفعات التجريبية.

Awaiting PayU LATAM payment: تبلغ PayU عن الدفعة بأنها معلّقة (دفع نقدي أو مصرفي). ينتقل الطلب إلى Payment accepted عندما تؤكد PayU الدفعة.

PayU LATAM payment on hold: المبلغ المدفوع أو عملته لا يطابقان إجمالي السلة، أو وافقت PayU على دفعة لطلب أُلغي. تُسجَّل الدفعة إذا كانت بعملة الطلب. تحدد الملاحظة الحالة: تحقق من الدفعة في وحدة PayU، ثم عالج الطلب أو استعده أو استرد الدفعة.

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

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

كتلة الدفع في PayU LATAM

تعرض صفحة الطلب كتلة PayU LATAM payment تتضمن المرجع ومعرّف المعاملة ومرجع PayU والحالة وحالة PayU والمبلغ المطلوب والمبلغ الذي أبلغت عنه PayU وطريقة الدفع ورسالة PayU وشارة SANDBOX للدفعات التجريبية وقائمة جميع محاولات الدفع للسلة وPayU LATAM notes الخاصة بالطلب.

الاستردادات

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

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

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

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

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

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

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

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

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

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

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

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

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

يرى العميل This payment method is not available: الوحدة النمطية غير مسموح بها لدولة العميل أو عملته أو مجموعته في Payment > Preferences، أو أن Enable/Disable معطّل.

الطلب في PayU LATAM payment on hold: اقرأ الملاحظات في كتلة PayU LATAM payment. كان المبلغ المدفوع أو عملته مختلفًا عن السلة، أو وصلت الدفعة بعد إلغاء الطلب. تحقق من المعاملة في وحدة PayU.

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

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

PayU علامة تجارية مملوكة لصاحبها. هذه الوحدة النمطية غير تابعة لـ PayU ولا معتمدة من قِبلها.