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

المتطلبات

OpenCart: الإصدار 3.0.x (مُختبَر على 3.0.5.0) أو الإصدار 4.0.2 والإصدارات الأحدث (مُختبَر على 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

العملة: يجب أن يدفع العميل بعملة EUR، لذا يجب تفعيل عملة EUR في System > Localisation > Currencies. أما مع العملات الأخرى، فتكون طريقة الدفع مخفية في صفحة الدفع.

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم الخاصة بكلا إصداري OpenCart. فُكَّ ضغطه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_nexi_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_nexi_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص هو نفسه لكلا الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_nexi_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت، يمكنك نسخ محتويات مجلد upload الموجود في حزمة هذا الإصدار إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Nexi XPay Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

5. فعّل Enable/Disable، وانقر على Save، ثم أجرِ طلبًا تجريبيًا بعملة EUR. وعندما يعمل كل شيء، أدخل الاسم المستعار للإنتاج ومفتاح MAC للإنتاج، وألغِ تفعيل Test Mode.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_nexi_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي يُغيَّر اسمها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Nexi XPay Gateway، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص والأسماء المستعارة (alias) ومفاتيح MAC كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. ويختلف عنوان الإشعار وحده (انظر Notification URL).

تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.

الإعدادات

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

عند الحفظ، لا يجوز أن يتجاوز Title 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total عددًا أكبر من 0 أو مساويًا له، ويجب أن توجد المنطقة الجغرافية (geo zone) وحالات الطلب؛ وإذا كان أي منها غير صحيح فلن يُحفظ شيء. وتُزال المسافات حول الأسماء المستعارة والمفاتيح الملصوقة.

Nexi XPay

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order. الافتراضي: Pay securely with your credit card via Nexi XPay.

Sort Order: ترتيب Nexi XPay بين طرق الدفع عند الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Nexi XPay فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض Nexi XPay. اتركه فارغًا لعرضه لأي إجمالي.

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

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

Test Mode: يستخدم بيئة اختبار Nexi XPay وبيانات الاعتماد الخاصة بالاختبار. أوقفه لاستقبال دفعات حقيقية ببيانات الاعتماد الخاصة بالإنتاج. الافتراضي: مفعّل. وطالما هو مفعّل، يرى العملاء في خطوة Confirm Order العبارة TEST MODE: the payment goes to the Nexi XPay test environment, no real money is charged.

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.

لا تُعرض مفاتيح MAC المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح محفوظ، ضع علامة على Clear the saved MAC key on save أسفل الحقل، ثم انقر على Save.

الدفع

Notification URL: يُعرض للاستدلال فقط. في OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_nexi_gateway/s2s&nexi_order={order_id}، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_nexi_gateway/payment/wcp_nexi_gateway.s2s&nexi_order={order_id}، ورقم الطلب في نهايته، ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك. يُرسل إلى Nexi مع كل دفعة، لذلك لا يلزم إعداد شيء في لوحة إدارة Nexi. ترسل Nexi نتيجة الدفعة إلى هذا العنوان من الخادم إلى الخادم، وتمررها أيضًا مع عودة العميل. وكلاهما موقَّع بالطريقة نفسها ويُتحقق منهما بمفتاح MAC للبيئة التي تمت فيها الدفعة، وباسم مستعار تلك البيئة، ورمز المعاملة الصادر لذلك الطلب. وتُرفض النتائج التي لا تجتاز التحقق ولا تغيّر شيئًا.

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

Order Status After Payment: حالة الطلب بعد دفعة ناجحة. تُضبط حالات OpenCart المستخدمة لكل خيار في قسم Orders.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود، missing order). ولا يحصل الطلب على حالة إلا من نتيجة Nexi مُتحقَّق منها. ويسرد كل حقل في الأسفل حالات الطلبات الخاصة بـ OpenCart لديك. لا يملك OpenCart حالة On hold: افتراضيًا تُستخدم Pending، وتشرح ملاحظة الطلب السبب. ويمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Status: Processing: يُستخدم عندما يكون Order Status After Payment هو Processing. الافتراضي: Processing.

Status: Completed: يُستخدم عندما يكون Order Status After Payment هو Completed. الافتراضي: Complete.

Status: awaiting payment: تُبلغ Nexi عن الدفعة بأنها معلّقة (esito PEN). الافتراضي: Pending.

Status: on hold: عدم تطابق المبلغ أو العملة، أو دفعة وردت لطلب مُلغى، أو التحصيل المؤجَّل (مُفوَّض ولم يُحصَّل بعد)، أو ضبط Order Status After Payment على On hold. الافتراضي: Pending.

Status: payment failed: دفعة معلّقة فشلت لاحقًا. الافتراضي: Failed.

Status of cancelled orders: الحالة التي يستخدمها متجرك للطلبات الملغاة. تُوضع الدفعة الواردة لمثل هذا الطلب في الانتظار، ولا تُعلَّم أبدًا كمدفوعة. ولا تقرأ الإضافة هذه الحالة إلا، ولا تضبطها أبدًا. الافتراضي: Canceled.

متقدم

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

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

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

الاستيراد / التصدير

Export: يحفظ Download JSON الإعدادات في ملف JSON. ولا تُصدَّر مفاتيح MAC.

Import: الصق ملف JSON مُصدَّرًا وانقر على Import لاستعادة الإعدادات. لا تتغير مفاتيح MAC المحفوظة.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit Card (Nexi)). وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وفي خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. عندما ينقر العميل على Confirm Order، تعرض الصفحة Redirecting to the Nexi XPay payment page... وPlease do not close this window. ثم ترسل العميل تلقائيًا إلى صفحة Nexi XPay بعد ثانية واحدة، مع زر Pay with Nexi XPay كخيار بديل. يُرسل الدفع بعملة EUR بإجمالي الطلب، مع رمز معاملة جديد، وبريد العميل الإلكتروني، والوصف Order، ورقم الطلب، واسم متجرك. وتُفتح صفحة Nexi بلغة متجر العميل إذا كانت الإيطالية أو الإنجليزية أو الإسبانية أو الفرنسية أو الألمانية أو اليابانية أو الصينية أو العربية أو الروسية أو البرتغالية؛ وإلا فبالإنجليزية.

يدفع العميل ويعود إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد نتيجة Nexi مُتحقَّق منها بالمبلغ والعملة الدقيقين للطلب: من إشعار الخادم إلى الخادم أو من عودة العميل الموقّعة، أيهما يصل أولًا. ثم يحصل الطلب على حالته بالطريقة المعيارية في OpenCart، مع بريد الطلب المعتاد وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع العبارة 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. وبالنسبة لطلب في حالة الانتظار (تحصيل مؤجَّل أو مراجعة يدوية)، تعرض Your Nexi XPay payment has been received and is being reviewed. We will contact you if anything is needed.

إذا لم تكن النتيجة قد عولجت بعد عند عودة العميل، تعرض صفحة Payment confirmation الرسالة 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. وفي OpenCart 4 تُعرض هذه الرسائل أعلى صفحة الدفع. ويبقى الطلب دون حالة إذا لم تكن له حالة، وتُحفظ السلة، بحيث يستطيع العميل الدفع مجددًا. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيُبقي طلبًا واحدًا للدفع ويدفعه مجددًا برمز معاملة جديد؛ وعندما يكون طلب آخر من السلة نفسها مدفوعًا أو في انتظار الدفع أو معلّقًا، ينتقل العميل إلى صفحة النجاح بدلًا من دفعة جديدة.

يحتفظ OpenCart 4 بالطلب في الدفع حتى تُعرض صفحة النجاح. وإذا أُغلق ذلك الطلب دون دفع في الأثناء (مثلًا فشلت دفعة معلّقة، أو ألغيته أنت)، يُعاد العميل إلى صفحة الدفع مع Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، وكذلك عند عودته من Nexi، ويدفع Confirm Order التالي طلبًا جديدًا. وإذا دُفع الطلب ثم أغلقه المتجر (مثلًا بعد استرداد)، فالرسالة هي Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. وإذا كان طلب الدفع قد سُجّل بالفعل ثم تغيّرت السلة بعد ذلك، فالرسالة هي Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. ويُعد أي تغيير في السلة، بما في ذلك الكمية الجديدة، سلةً جديدة تحتاج إلى دفعة خاصة بها.

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

يعمل الإشعار أيضًا أثناء وجود المتجر في وضع الصيانة، لأن OpenCart 3 يسمح بمرور طلبات إضافات الدفع، وفي OpenCart 4 تضيف الإضافة إجراء startup لذلك، وهو يسمح للعميل أيضًا بالعودة من Nexi.

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

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

حالات الطلب

No status (missing order): أُرسل العميل إلى Nexi ولم يدفع، أو ألغى، أو رُفضت الدفعة، أو لم تؤكد Nexi الدفعة بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Status: Processing, Completed or on hold: أكدت Nexi الدفعة. وتتبع الحالة Order Status After Payment. وتعرض الملاحظة رمز التفويض، ورمز المعاملة، وعلامة البطاقة، ورسالة Nexi.

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

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

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

Status: payment failed: فشلت دفعة معلّقة.

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

الملاحظات هي إدخالات في History الخاص بالطلب، ولا يراها العميل.

تبويب VibeFox Nexi XPay Gateway

في Sales > Orders افتح طلبًا دُفع عبر Nexi XPay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Nexi XPay Gateway رمز المعاملة (codTrans) مع الوسم Test environment لدفعات الاختبار، والحالة ونتيجة Nexi، ووضع التحصيل وحالته، والمبلغ المُرسل إلى Nexi والمبلغ المستلم، ورمز التفويض، وعلامة البطاقة، ورسالة Nexi، والتاريخ، وNexi XPay notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

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

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

الاسترداد

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Nexi XPay Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفًى، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-nexi والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. ولا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify على الإضافة. وتتبع نصوص الكتلة لغة الإدارة (وتتضمن الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل 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. ويظل مستخدم الإدارة الذي سجّل الدخول إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع الوسم (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. وفي OpenCart 4 هذه المعاينة غير متاحة: فالمتجر لا يرى تسجيل دخول الإدارة، لذلك تبقى طريقة الدفع مخفية عن الجميع دون مفتاح نشط. وبعد فتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بالرمز × لإخفائه لمدة 7 أيام. ولا تتأثر الطلبات الحالية: فالدفعات التي بدأت من قبل تُؤكَّد، ويمكن تحصيل الدفعات المُفوَّضة.

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

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

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

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

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

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

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

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

يرى العميل الرسالة This payment method is not available. Please reload the checkout page.: جلسة الدفع لم تعد مطابقة للطلب، أو أن طريقة الدفع أُوقفت في الأثناء. يعيد العميل تحميل صفحة الدفع.

الطلب في حالة الانتظار بعد الدفع: اقرأ Nexi XPay notes في تبويب الطلب. التحصيل المؤجَّل محدد (حصّل الدفعة بالزر)، أو المبلغ أو العملة لم يتطابقا، أو وصلت دفعة لطلب مُلغى، أو أن Order Status After Payment مضبوط على On hold.

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

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

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Nexi XPay Gateway. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. ويحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات قسم Orders، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. ويُحذف حدث OpenCart الخاص بالإضافة أيضًا (وفي OpenCart 4 تُحذف أحداثه وإجراء startup الخاص به، الذي يسمح بمرور الإشعار في وضع الصيانة). وإذا كان Delete Data on Uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان والوصف ووضع الاختبار والاسم المستعار ومفاتيح MAC والتحصيل وحالة الطلب بعد الدفع وسجل التصحيح) والسجل. وإذا كان معطّلًا، فتُحفظ لإعادة التثبيت لاحقًا. وتُحتفظ دائمًا ببيانات دفعات Nexi XPay الخاصة بالطلبات (الدفعات والتحصيلات والاستردادات)، لذلك يمكن تحصيل الدفعات المُفوَّضة حتى بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، ولحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت وانقر على Uninstall (زر − البرتقالي) بجوار VibeFox Nexi XPay Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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