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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل.

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل Enable/Disable ونفّذ طلبًا تجريبيًا. عندما يعمل كل شيء، أدخل الاسم المستعار ومفتاح MAC الفعليين وألغِ تحديد Test Mode.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Nexi XPay. فوق الحقول تعرض الصفحة وضع الاختبار مفعّل: تُرسل المدفوعات إلى بيئة اختبار Nexi XPay ولا يُخصم أي مبلغ حقيقي. ما دام وضع الاختبار مفعّلًا، وتحذّرك عندما تكون البوابة مفعّلة لكن الاسم المستعار أو مفتاح MAC للوضع الحالي فارغ، أو عندما لا تكون عملة المتجر EUR. وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع. تُحذف المسافات وفواصل الأسطر المحيطة بالمفاتيح الملصوقة عند الحفظ.

عام

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

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

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

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

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

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

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

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

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

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

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

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

الدفع

يُرسل عنوان الإشعار إلى Nexi مع كل دفعة، لذلك لا يلزم ضبط أي شيء في لوحة الإدارة. يعرض هذا القسم العنوان؛ وهو بالشكل https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}، وينتهي بمعرّف الطلب. يرسل Nexi نتيجة الدفع إلى هذا العنوان من خادم إلى خادم، ويمررها أيضًا مع عودة العميل. يُوقَّع الاثنان بالطريقة نفسها ويُتحقق منهما بمفتاح MAC للبيئة التي تمت فيها الدفعة، وبالاسم المستعار لتلك البيئة، وبرمز المعاملة الصادر لذلك الطلب. تُرفض النتائج التي لا تجتاز التحقق ولا تغيّر شيئًا.

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

Immediate capture: تُحصَّل الدفعة فورًا ويُعلَّم الطلب كمدفوع (الافتراضي).

Deferred capture (authorize only): يتبع التحصيل ملف جهازك الطرفي. يبقى الطلب في حالة «قيد الانتظار» بوصفه مفوَّضًا حتى تحصّله بإجراء الطلب Capture Nexi XPay payment، أو تحصّله في لوحة إدارة Nexi ثم تغيّر حالة الطلب إلى «قيد المعالجة».

Order Status After Payment: حالة الطلب بعد دفعة ناجحة. تُضبط الحالة فورًا، بتغيير واحد للحالة ورسالة بريد إلكتروني واحدة.

قيد المعالجة (الافتراضي في WooCommerce): الافتراضي.

مكتمل: يصبح كل طلب مدفوع «مكتملًا».

في الانتظار: ينتظر كل طلب مدفوع مراجعتك اليدوية.

متقدم

Debug Log: Enable logging يسجّل أحداث الدفع في WooCommerce > Status > Logs، بالمصدر wcp_nexi_gateway. لا تُسجَّل مفاتيح MAC وبيانات البطاقات وعناوين البريد الإلكتروني. تُسجَّل الأخطاء والتحذيرات، مثل فشل التحقق من MAC، دائمًا حتى عندما يكون الخيار معطّلًا. الافتراضي: معطّل.

Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. الافتراضي: معطّل.

صفحة الدفع

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

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

إذا رُفضت الدفعة، أو ألغى العميل في صفحة Nexi، فإنه يعود إلى صفحة الدفع (أو إلى صفحة Pay for order إذا كانت السلة فارغة) ويرى إحدى هذه الرسائل: لم تكتمل عملية الدفع. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع مختلفة.، تم إلغاء الدفع. يرجى المحاولة مرة أخرى.، أو تعذّر علينا تأكيد الدفع. إذا تم خصم مبلغ من بطاقتك، فيرجى التواصل معنا قبل الدفع مرة أخرى. الإلغاء في صفحة Nexi يترك الطلب دون تغيير، لذا يستطيع العميل الدفع مرة أخرى.

إذا لم تكن الإضافة مُعدّة للوضع الحالي، يرى العميل طريقة الدفع هذه غير متاحة حاليًا. يرجى اختيار طريقة دفع أخرى.

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

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

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

حالات الطلب

بانتظار الدفع: أُرسل العميل إلى Nexi ولم يدفع بعد، أو ألغى في صفحة Nexi.

قيد المعالجة أو مكتمل أو في الانتظار: أكّد Nexi الدفعة. تتبع الحالة Order Status After Payment. تعرض ملاحظة الطلب رمز التفويض ورمز المعاملة وعلامة البطاقة ورسالة Nexi. معرّف المعاملة هو رمز المعاملة في Nexi.

في الانتظار (مفوَّض): تم اختيار التحصيل المؤجَّل والدفعة مفوَّضة فقط. حصّلها بإجراء الطلب Capture Nexi XPay payment.

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

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

فشل: رُفضت آخر محاولة دفع أو أُلغيت أو انتهت بخطأ. يستطيع العميل الدفع مرة أخرى.

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

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

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

الاستردادات

لا تُنفَّذ الاستردادات من WooCommerce، لذلك لا يوجد زر Refund via. نفّذ الاسترداد في لوحة إدارة Nexi XPay، ثم سجّله يدويًا في WooCommerce.

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

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

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

بدون مفتاح فعّال لا يظهر Nexi XPay للعملاء في صفحة الدفع. إذا بدأ الدفع رغم ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ويظل مديرو المتجر المسجلون الدخول يرون طريقة الدفع، مع علامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. يظهر تذكير في صفحة Plugins وفي صفحات WooCommerce. لا تتأثر الطلبات الحالية: تُؤكَّد المدفوعات التي بدأت بالفعل، ويمكن تحصيل المدفوعات المؤجَّلة.

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

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

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

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

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

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

يرد الإشعار بـ not_configured أو busy: الاسم المستعار أو مفتاح MAC لبيئة الدفعة فارغ، أو كان طلب آخر يحدّث الطلب في الوقت نفسه. يعيد Nexi إرسال الإشعار.

الطلب في حالة الانتظار بعد الدفع: اقرأ ملاحظة الطلب. التحصيل المؤجَّل مختار (حصّل الدفعة بإجراء الطلب)، أو لم يتطابق المبلغ أو العملة، أو وصلت دفعة لطلب ملغى، أو الدفعة معلّقة لدى Nexi، أو في الانتظار مختار كحالة بعد الدفع.

Capture Nexi XPay payment مفقود أو يفشل: يظهر الإجراء فقط للطلبات من Nexi المعلّقة كمفوَّضة مع التحصيل المؤجَّل. إذا فشل، اقرأ الخطأ في ملاحظات الطلب؛ يستخدم التحصيل مفاتيح البيئة التي تمت فيها الدفعة.

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

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

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

Nexi وXPay علامتان تجاريتان لمالكيهما. هذه الإضافة غير تابعة لـ Nexi ولا تحظى بتأييدها.