VibeFox Nexi XPay for PrestaShop — المساعدة

المتطلبات

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

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

العملة: يجب أن تكون عملة السلة EUR. مع العملات الأخرى تُخفى طريقة الدفع عند إتمام الشراء.

حساب Nexi XPay: تحتاج إلى حساب تاجر لدى Nexi XPay (تكامل إعادة التوجيه «Pagamento Semplice») مع الاسم المستعار (alias، أي معرّف الجهاز الطرفي) ومفتاح MAC لجهازك الطرفي. بيانات الاعتماد التجريبية والفعلية منفصلة: بيانات الاختبار تأتي من منطقة الاختبار في Nexi XPay أو من بوابة المطورين (developer.nexi.it)، وبيانات الوضع الفعلي تأتي من لوحة إدارة Nexi XPay بعد تفعيل حساب التاجر. لا شيء يُضبط في لوحة إدارة Nexi: عنوان الإشعار يُرسل مع كل دفعة.

الموقع العام: يجب أن يكون عنوان URL للإشعار متاحًا من الإنترنت، دون مصادقة أساسية أو قاعدة جدار ناري تمنع Nexi. وضع الصيانة في المتجر لا يمنعه. إذا تعذّر وصول الإشعار إلى المتجر، فإن الدفعة تُؤكَّد مع ذلك بعودة العميل الموقَّعة.

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

التثبيت

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

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

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

4. أبقِ Test Mode مفعّلًا وأدخل الاسم المستعار (alias) ومفتاح MAC التجريبيين (انظر الإعدادات).

5. فعّل Enable/Disable وانقر على Save ثم أنشئ طلب اختبار. عندما يعمل كل شيء، أدخل الاسم المستعار (alias) ومفتاح MAC الفعليين وأوقف Test Mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. فوق الحقول تعرض الصفحة Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. طالما كان وضع الاختبار مفعّلًا. وتُظهر تحذيرًا عندما تكون البوابة مفعّلة لكن الاسم المستعار (alias) أو مفتاح MAC للوضع الحالي فارغ، أو عندما لا تكون العملة الافتراضية للمتجر EUR. في هذه الحالات تُخفى طريقة الدفع عند إتمام الشراء. تُحذف المسافات وفواصل الأسطر حول القيم الملصوقة عند الحفظ.

Nexi XPay

Enable/Disable: Enable Nexi XPay Gateway يفعّل طريقة الدفع أو يوقفها. الافتراضي: off.

Title: عنوان طريقة الدفع الذي يراه العميل عند إتمام الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit Card (Nexi). في وضع الاختبار تضيف صفحة الشراء والطلب (TEST MODE) إلى العنوان.

Description: وصف طريقة الدفع الذي يراه العميل عند إتمام الشراء. الافتراضي: Pay securely with your credit card via Nexi XPay.

بيئة الاختبار

تذهب المدفوعات التجريبية إلى int-ecommerce.nexi.it ولا تخصم أي بطاقة حقيقية أبدًا. احصل على الاسم المستعار (alias) ومفتاح MAC التجريبيين من منطقة الاختبار في Nexi XPay أو من بوابة المطورين (developer.nexi.it).

Test Mode: يستخدم بيئة الاختبار في Nexi XPay وبيانات الاعتماد التجريبية. أوقفه لاستقبال مدفوعات حقيقية ببيانات الوضع الفعلي. الافتراضي: on.

Test Alias: الاسم المستعار (alias، أي معرّف الجهاز الطرفي) لجهازك الطرفي التجريبي في Nexi XPay.

Test MAC Key: مفتاح حساب MAC لجهازك الطرفي التجريبي في Nexi XPay.

البيئة الفعلية

يظهر الاسم المستعار (alias) ومفتاح MAC الفعليان في لوحة إدارة Nexi XPay (ecommerce.nexi.it) بعد تفعيل حساب التاجر.

Live Alias: الاسم المستعار (alias، أي معرّف الجهاز الطرفي) لجهازك الطرفي الفعلي في Nexi XPay.

Live MAC Key: مفتاح حساب MAC لجهازك الطرفي الفعلي في Nexi XPay.

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

مسح البيانات السرية المحفوظة: ضع علامة على Test MAC Key أو Live MAC Key ثم انقر على Save لإزالة مفتاح محفوظ. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع

Notification URL: يُعرض للمرجعية فقط. يُرسل إلى Nexi مع كل دفعة، لذلك لا يلزم ضبط أي شيء في لوحة إدارة Nexi. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}، وقد يتضمن رمز لغة مثل /it/، ويُختم برقم السلة. يرسل Nexi نتيجة الدفع إلى هذا العنوان من خادم إلى خادم، ويمررها أيضًا مع عودة العميل. يُوقَّع الاثنان بالطريقة نفسها ويُتحقق منهما بمفتاح MAC للبيئة التي تمت فيها الدفعة، وباسم البيئة المستعار (alias)، وبرمز المعاملة الصادر لتلك السلة. النتائج التي لا تجتاز التحقق تُرفض ولا تغيّر شيئًا.

Capture: متى يُخصم المبلغ.

Order Status After Payment: حالة الطلب بعد دفعة ناجحة.

متقدم

Debug Log: يسجل أحداث الدفع في logs/nexi_ip_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل مفاتيح MAC وقيم MAC وبيانات البطاقات وعناوين البريد الإلكتروني. تُسجَّل الأخطاء والتحذيرات، مثل فشل التحقق من MAC، دائمًا، حتى عندما يكون الخيار مغلقًا. الافتراضي: off.

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف جميع إعداداتها والسجل. تبقى بيانات الدفع في Nexi XPay الخاصة بالطلبات وحالات الطلبات. الافتراضي: off.

إتمام الشراء

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit Card (Nexi)) ويؤكد. تعرض الصفحة التالية Redirecting to Nexi XPay for payment... وتنقل العميل تلقائيًا إلى صفحة Nexi XPay، مع زر Pay Now كخيار احتياطي. تُرسل الدفعة باليورو لإجمالي السلة، برمز معاملة جديد، وبريد العميل الإلكتروني، ووصف Cart، ورقم السلة، واسم متجرك. تُفتح صفحة Nexi بلغة السلة إذا كانت الإيطالية أو الإنجليزية أو الإسبانية أو الفرنسية أو الألمانية أو اليابانية أو الصينية أو العربية أو الروسية أو البرتغالية، وإلا فبالإنجليزية. لا يوجد طلب بعد في هذه المرحلة.

يدفع العميل ويعود إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد نتيجة Nexi متحقَّق منها بالمبلغ والعملة المطابقين تمامًا للسلة: سواء من الإشعار من خادم إلى خادم أو من عودة العميل الموقَّعة، أيهما يصل أولًا. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your Nexi XPay payment has been received. إذا أبلغ Nexi بأن الدفعة قيد الانتظار، تعرض الصفحة Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed.. وبالنسبة لطلب في حالة الانتظار (تحصيل مؤجل أو مراجعة يدوية) تعرض We have received your Nexi XPay payment authorization. Your order will be processed shortly.. إذا فشلت الدفعة المعلقة لاحقًا، تعرض الصفحة The payment was not completed. Please contact us..

إذا لم تُعالج النتيجة بعد عند عودة العميل، تظهر صفحة تحمل الرسالة We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. وزر Check again. ينشئ الإشعار الطلب فور وصوله.

إذا رُفضت الدفعة، أو ألغى العميل في صفحة Nexi، يعود إلى صفحة إتمام الشراء ويرى إحدى هذه الرسائل: The payment was not completed. Please try again or choose a different payment method.، أو Payment was cancelled. Please try again.، أو We could not confirm the payment. If your card was charged, please contact us before paying again.. لا يُنشأ طلب وتُحفظ السلة، فيستطيع العميل الدفع مرة أخرى. إذا كان للسلة طلب بالفعل (مثلًا دُفع في تبويب آخر)، يُوجَّه العميل إلى تأكيد الطلب بدلًا من دفعة جديدة.

إذا لم تكن الوحدة مُعدّة للوضع الحالي، يرى العميل This payment method is not available right now. Please choose another payment method.

يعمل الإشعار أثناء وضع الصيانة في المتجر، ولا يحجبه قيد الدول في متجرك.

تقبل الوحدة المدفوعات في صفحة Nexi XPay فقط. لا توجد استردادات من PrestaShop، ولا بطاقات محفوظة أو OneClick، ولا اشتراكات أو مدفوعات متكررة، ولا Pay-By-Link، ولا حقول XPay Build المضمّنة، ولا طرق دفع تُختار في PrestaShop: تعرض صفحة Nexi الطرق المفعّلة على جهازك الطرفي.

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Nexi ولم يدفع أو يلغِ أو رُفضت دفعته، أو لم يؤكد Nexi الدفعة بعد. السلة فقط موجودة.

Payment accepted, Delivered or Nexi XPay payment on hold: أكد Nexi الدفعة. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة برمز معاملة Nexi كمعرّف للمعاملة، وتعرض ملاحظة رمز التفويض ورمز المعاملة وعلامة البطاقة ورسالة Nexi.

Nexi XPay payment on hold (authorized): التحصيل المؤجل مختار والدفعة مفوَّضة فقط. حصّلها بـCapture Nexi XPay payment في صفحة الطلب.

Awaiting Nexi XPay payment: أبلغ Nexi بأن الدفعة قيد انتظار التأكيد. يُحدَّث الطلب بالنتيجة النهائية.

Nexi XPay payment on hold after payment: المبلغ أو العملة الواردان من Nexi لم يطابقا السلة (لا يُعلَّم الطلب كمدفوع)، أو وصلت دفعة ناجحة لطلب أُلغي من قبل. توضح الملاحظة السبب. تحقق من الدفعة في لوحة إدارة Nexi XPay ثم عالج الطلب أو استرده.

خطأ في الدفع: فشلت دفعة معلقة. لا يمكن دفع السلة نفسها مرة أخرى، لذا يجب على العميل تقديم طلب جديد.

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

كتلة دفع Nexi XPay

تعرض صفحة الطلب كتلة Nexi XPay payment تتضمن رمز المعاملة (codTrans)، والحالة ونتيجة Nexi، ووضع التحصيل، والمبلغ المُرسل إلى Nexi والمبلغ المستلم، ورمز التفويض، وعلامة البطاقة، ورسالة Nexi والتاريخ، وشارة Test environment للدفعات التجريبية، وNexi XPay notes الخاصة بالطلب.

التحصيل المؤجل

بالنسبة لطلب مفوَّض في حالة الانتظار، انقر على Capture Nexi XPay payment في الكتلة (يعرض الزر المبلغ) وأكّد السؤال Capture the authorized amount through Nexi XPay?. تحتاج إلى صلاحية تعديل الطلبات. تحصّل الوحدة المبلغ المفوَّض في بيئة الدفعة، بمفاتيح تلك البيئة، وتسجل الدفعة وتضبط الحالة وفق Order Status After Payment. إذا فشل التحصيل، تعرض الكتلة الخطأ وتُضاف ملاحظة ويبقى الطلب في حالة الانتظار. يُرفض التحصيل الثاني للدفعة نفسها.

الاستردادات

لا تُجرى الاستردادات من PrestaShop، لذلك لا يوجد زر استرداد لـ Nexi XPay. أجرِ الاسترداد في لوحة إدارة Nexi XPay، ثم سجّله يدويًا في PrestaShop. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترد الأموال عبر Nexi.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Nexi XPay Gateway هي أول كتلة في Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى الأجزاء، والحالة (مثل التاريخ الذي تبقى الرخصة فعالة حتى نهايته ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-nexi والرابط 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.

بدون مفتاح نشط لا يظهر Nexi XPay للعملاء عند إتمام الشراء. وإذا بدأت عملية الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند إتمام الشراء. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: الدفعات التي بدأت بالفعل ما زالت تُؤكَّد، والدفعات المفوَّضة ما زال يمكن تحصيلها.

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

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

لا يظهر Nexi XPay عند إتمام الشراء: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على بيانات الاعتماد كلها (Test Alias وTest MAC Key في وضع الاختبار، وLive Alias وLive MAC Key في الوضع الفعلي)، وأن عملة السلة EUR. تعرض صفحة الإعدادات تحذيرًا في هذه الحالات. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة EUR ولدولة العميل ولمجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: لم يُقبل لا الإشعار ولا عودة العميل. تحقق من أن المتجر يمكن الوصول إليه من الإنترنت، وأن مفتاح MAC والاسم المستعار (alias) يطابقان بيئة الدفعة (الاختبار أو الفعلية)، وفعّل Debug Log لترى ما أرسله Nexi في حقل Log في صفحة الوحدة.

يجيب الإشعار بـ invalid_mac أو invalid_alias: مفتاح MAC أو الاسم المستعار في الإعدادات لا يطابق الجهاز الطرفي الذي أرسل النتيجة. انسخهما مجددًا من منطقة الاختبار أو لوحة إدارة Nexi.

يجيب الإشعار بـ unknown_transaction: رمز المعاملة لم يُصدره هذا المتجر لتلك السلة. تُتجاهل النتيجة.

يجيب الإشعار بـ not_configured أو busy: الاسم المستعار (alias) أو مفتاح MAC لبيئة الدفعة فارغ، أو كان الطلب يُحدَّث من طلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطلة). يعيد Nexi محاولة الإشعار.

يعرض عنوان الإشعار method_not_allowed في المتصفح: هذا طبيعي. العنوان يقبل الطلبات الصادرة من Nexi فقط.

الطلب في حالة Nexi XPay payment on hold after payment: اقرأ Nexi XPay notes في كتلة الطلب. التحصيل المؤجل مختار (حصّل الدفعة بالزر)، أو المبلغ أو العملة لم يطابقا، أو وصلت دفعة لطلب مُلغى، أو Nexi XPay payment on hold مختار كحالة بعد الدفع.

Capture Nexi XPay payment غير موجود أو يفشل: يظهر الزر فقط لطلبات Nexi XPay المعلقة كمفوَّضة مع التحصيل المؤجل، ولموظفين يُسمح لهم بتعديل الطلبات. إذا كان الاسم المستعار (alias) أو مفتاح MAC لبيئة الدفعة فارغًا، تذكر الكتلة ذلك. إذا فشل التحصيل، فاقرأ الخطأ في الكتلة وفي الملاحظات، مثلًا Nexi XPay refused the capture مع رمز Nexi ورسالته.

المدفوعات التجريبية لا تؤكد دفعة فعلية: كل دفعة تُتحقق بمفاتيح البيئة التي بدأت فيها. بدّل Test Mode إلى الوضع الذي تريده واستخدم الاسم المستعار (alias) ومفتاح MAC لذلك الوضع.

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

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

Nexi وXPay علامتان تجاريتان مملوكتان لأصحابهما. هذه الوحدة غير تابعة لشركة Nexi ولا معتمدة من قبلها.