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

المتطلبات

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

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

حساب Nets: تحتاج إلى المفاتيح السرية لحسابك في Nets Easy (للاختبار وللإنتاج). تُستخدم المفاتيح السرية فقط. لا حاجة إلى مفاتيح الدفع (checkout)، لأن العملاء يدفعون في صفحة الدفع المُستضافة لدى Nets.

العملات وطرق الدفع: لا تقيّد الإضافة العملات بنفسها. استخدم العملات المفعّلة في حساب Nets الخاص بك؛ وستُبلغ Nets بالعملة غير المدعومة عند إنشاء الدفعة. أما طرق الدفع التي يراها العميل فتعتمد على عقدك مع Nets وعلى البلد والعملة.

HTTPS لـ webhooks: لا تستدعي Nets إلا عناوين HTTPS عامة لا يتجاوز طولها 256 حرفًا ولا تحتوي على "&"، لذلك يحتاج متجرك إلى HTTPS لاستقبال webhooks. وبدونه يُؤكَّد الدفع عندما يعود العميل إلى المتجر، أو عند التحقق من الحالة في صفحة الطلب.

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

التثبيت

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

OpenCart 3

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

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

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

4. انسخ المفتاح السري للاختبار من بوابة الاختبار الخاصة بـ Nets Easy، والصقه في Test Secret Key (انظر الإعدادات). لا حاجة إلى إعداد أي شيء في بوابة Nets.

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

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص والمفاتيح السرية كما في الخطوات من 3 إلى 5 الخاصة بـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين، ويختلف عنوان الـ webhook فقط (انظر Webhooks).

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit. تُدرج الأقسام على اليسار؛ وزر Save أسفل القائمة يحفظ الصفحة كاملةً. وفوق الإعدادات، تُحذّرك الصفحة عند غياب المفتاح السري للوضع المحدد، مثل Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set.، وتعرض Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. طالما أن وضع الاختبار مفعّل. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

Nets Nexi (دول شمال أوروبا)

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

Title: عنوان طريقة الدفع الذي يُعرض على العملاء أثناء الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Nets Easy. مطلوب.

Description: النص الذي يراه العميل في خطوة Confirm Order. الافتراضي: Pay securely with Nets Easy.

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

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

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

مفاتيح API

انسخ المفاتيح السرية من بوابة Nets Easy ضمن Company > Integration: بوابة الاختبار (test.portal.dibspayment.eu) لمفتاح الاختبار، وبوابة الإنتاج (portal.dibspayment.eu) لمفتاح الإنتاج. ويتضمن القسم روابط إلى البوابتين. مفاتيح الدفع (checkout) غير مطلوبة.

Test Mode: يستخدم وضع الاختبار العنوان test.api.dibspayment.eu مع المفتاح السري للاختبار؛ ويستخدم وضع الإنتاج العنوان api.dibspayment.eu مع المفتاح السري للإنتاج. تستخدم عمليات الاسترداد والتحصيل لأي طلب دائمًا البيئة التي دُفع فيها. الافتراضي: مفعّل. وطالما هو مفعّل، يرى العملاء في خطوة Confirm Order العبارة Test mode: no real money will be charged.

Test Secret Key: المفتاح السري لواجهة API الخاصة ببيئة الاختبار في Nets.

Live Secret Key: المفتاح السري لواجهة API الخاصة ببيئة الإنتاج في Nets.

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

الدفع

Webhooks: تُسجَّل إشعارات Nets (webhooks) تلقائيًا مع كل دفعة. لا يوجد ما يلزم ضبطه في بوابة Nets. يعرض الحقل العنوان الذي تُرسل إليه، وهو يبدو في OpenCart 3 مثل https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook، وفي OpenCart 4 مثل https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook، ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك. إذا لم يكن عنوانًا عامًا بتقنية HTTPS، فإن الحقل يحذّرك من أن المتجر لا يستقبل webhooks؛ وعندئذ تُؤكَّد الدفعات عندما يعود العميل إلى المتجر، أو عبر Nets: check payment status and capture في صفحة الطلب. وتُسجَّل الأحداث التالية:

يجب أن يحمل كل webhook السر العشوائي الذي أنشأته الإضافة لتلك الدفعة. تُرفض الـ webhooks التي لا تحمل السر الصحيح. ولا يخبر الـ webhook الإضافةَ إلا بالدفعة التي تغيّرت؛ أما الدفعة نفسها فتُقرأ دائمًا من واجهة Nets API باستخدام المفتاح السري للبيئة التي تمت فيها.

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود، missing order). ولا يحصل الطلب على حالة إلا بعد قراءة الدفعة مجددًا من واجهة Nets API (webhook، أو عودة العميل، أو Nets: check payment status and capture في صفحة الطلب) وبعد تحصيل الحجز المطابق. ويسرد كل حقل حالة في الأسفل حالات الطلبات الخاصة بـ OpenCart لديك.

Order Status After Payment: حالة الطلب بعد أن تؤكد Nets الدفعة وتحصّلها. الافتراضي: Processing. اختر Complete لوضع علامة "مكتمل" على الطلبات المدفوعة.

Nets Payment On Hold Status: تُستخدم عندما يختلف المبلغ أو العملة عن الطلب، أو يفشل التحصيل، أو يدفع العميل بعد إلغاء الطلب. لا يُحصَّل أي شيء تلقائيًا، وتشرح ملاحظة السبب. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Cancelled Status: تُعيَّن عند إلغاء حجز الطلب في بوابة Nets. الافتراضي: Canceled.

Refunded Status: تُعيَّن بعد استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: Refunded.

متقدم

Debug log: يسجّل استدعاءات API وتغييرات حالة الدفع في nng_debug.log.php ضمن مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح وبيانات العملاء. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون الخيار معطّلًا. الافتراضي: معطّل.

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Nets Easy). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the Nets payment page to pay securely. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. عندما ينقر العميل على Confirm Order، تنشئ الإضافة دفعة Nets بإجمالي الطلب بعملة الطلب، وتمرّر المنتجات والشحن وبقية إجماليات الطلب (القسائم، والكوبونات، والرسوم) كبنود للطلب، ثم ترسل العميل إلى صفحة الدفع المُستضافة لدى Nets. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. مرجع الدفعة لدى Nets هو رقم طلب OpenCart. وتُرسل بريد العميل الإلكتروني واسمه وعنوان الشحن ورقم هاتفه إلى Nets عندما تقبل Nets صيغتها. ويُربط في صفحة Nets بصفحة شروط الدفع في متجرك (أو الصفحة الرئيسية للمتجر إن لم تُحدَّد صفحة).

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Nets: تقرأ الإضافة الدفعة من واجهة Nets API، وتقارن المبلغ والعملة المحجوزين بالطلب، وتحصّل الحجز، ثم تُعيّن حالة الطلب. ويحدث ذلك عبر الـ webhook أو عند عودة العميل، أيهما يأتي أولًا. ثم يحصل الطلب على حالته بالطريقة المعيارية في OpenCart، مع بريد الطلب المعتاد وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وإذا تعذّر تأكيد الدفعة بعد (إذ لم يمكن الوصول إلى Nets، أو كان طلب آخر يؤكدها في تلك اللحظة)، تعرض صفحة Payment confirmation الرسالة Your Nets payment is being confirmed. Your order will be updated as soon as it is confirmed — please do not pay again. مع الزرين Check again وBack to checkout.

إذا ألغى العميل في صفحة Nets، فإنه يعود إلى الدفع مع الرسالة The Nets payment was cancelled. You can try again or choose another payment method. وإذا لم يُدفع أي مبلغ، فالرسالة هي The payment was not completed. You can try again or choose another payment method. وفي OpenCart 4 تُعرض هذه الرسائل فوق صفحة الدفع. ويُحتفظ بالسلة. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيُبقي طلبًا واحدًا للدفع، ويدفع الطلب نفسه مجددًا بدفعة Nets جديدة. وعند المحاولة من جديد، تتحقق الإضافة أولًا من الدفعات السابقة للسلة؛ فإن كانت إحداها مدفوعة، تُؤكَّد تلك الدفعة بدلًا من بدء دفعة جديدة. وإلا، تُغلق جلسات Nets السابقة قبل بدء جلسة جديدة. وإذا كان طلب آخر من السلة نفسها مدفوعًا أو معلّقًا، ينتقل العميل إلى صفحة النجاح.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. وإذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا لأنك ألغيته، أو بعد إلغاء الحجز في بوابة Nets)، يُعاد العميل إلى الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، ويحدث ذلك أيضًا عند عودة العميل من Nets، ويدفع Confirm Order التالي طلبًا جديدًا. ولم يعد طلب السلة الذي دُفع ثم أُلغي أو استُرد يحتجز السلة.

إذا تعذّر على Nets بدء الدفعة، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة، مثل Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method. أو This payment method is temporarily unavailable. Please choose another payment method. أو The payment service could not be reached. Please try again in a moment. ويعرض إجمالي الطلب الذي يساوي صفرًا الرسالة The order total must be greater than zero to pay with Nets. وتُكتب التفاصيل في السجل.

يعمل الـ webhook أيضًا أثناء وجود المتجر في وضع الصيانة، لأن OpenCart 3 يسمح بمرور طلبات إضافات الدفع، أما OpenCart 4 ففيه إجراء عند بدء التشغيل (startup action) تضيفه الإضافة لهذا الغرض، وهو ما يسمح أيضًا للعميل بالعودة من Nets.

تستخدم الإضافة صفحة الدفع المُستضافة فقط. ولا تتضمن دفع Nets مضمّنًا في الصفحة، ولا الاشتراكات أو المدفوعات المتكررة، ولا البطاقات المحفوظة، ولا رسوم الفواتير، ولا وضع التفويض فقط، ولا التحصيل الجزئي لكل شحنة.

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

حالات الطلب

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

Order Status After Payment (default Processing): أكدت Nets الدفعة وحصّلتها. تعرض ملاحظة معرّف الدفعة ومعرّف التحصيل وطريقة الدفع.

Nets Payment On Hold Status (default Pending): المبلغ أو العملة في Nets يختلفان عن الطلب (لم يُحصَّل)، أو رُفض التحصيل، أو دفع العميل بعد إلغاء الطلب (مُحجوز، غير مُحصَّل). تشرح الملاحظة ذلك. لا يُحصَّل أي شيء تلقائيًا. بعد مراجعة الطلب، حصّله باستخدام Nets: check payment status and capture، أو ألغِ الحجز في بوابة Nets.

Cancelled Status (default Canceled): أُلغي حجز الطلب، مثلًا في بوابة Nets.

Refunded Status (default Refunded): استُرد المبلغ بالكامل عبر الإضافة.

عندما ينقل webhook أو عودة العميل طلبًا من حالة التعليق إلى حالة مدفوع، أو يلغيه، يُخطر OpenCart العميل. ولا تؤدي الـ webhooks المتكررة وإعادة تحميل الصفحة أبدًا إلى تحصيل مزدوج أو إضافة ملاحظات مكررة، ولا يُغيَّر الطلب المدفوع مجددًا بأحداث Nets. وإذا اكتملت رابط دفع قديم لطلب مدفوع بالفعل، أو لطلب آخر من السلة نفسها، يُحرَّر الحجز الثاني تلقائيًا؛ وإذا كان قد حُصِّل من قبل، تطلب منك ملاحظة استرداده في بوابة Nets. وإذا عُلِّم الطلب كمدفوع بطريقة أخرى، فلا يُحصَّل الدفع المحجوز في Nets وتذكر ملاحظة ذلك.

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

تبويب VibeFox Nets Nexi Gateway

في Sales > Orders افتح طلبًا دُفع عبر Nets. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Nets Nexi Gateway كتلة Nets Easy payment: معرّف الدفعة، ومعرّف التحصيل، والبيئة (مع الوسم Test environment لدفعات الاختبار)، والحالة وطريقة الدفع، والمبالغ المحجوزة والمحصّلة لدى Nets، وإجمالي الطلب والمبلغ المسترد، ونموذج الاسترداد، وسجل الاسترداد، وNets notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة؛ وتتطلب أزراره صلاحية تعديل الإضافة (وتُضبط في System > Users > User Groups).

Nets: check payment status and capture: يظهر للطلبات غير المدفوعة بعد. يقرأ الدفعة من Nets ويحصّل الحجز المطابق للطلب، حتى بعد فشل التحصيل أو بعد مراجعة طلب معلّق. وإذا لم يتغير شيء، تشرح ملاحظة السبب، مثلًا أن العميل لم يُكمل الدفع بعد. والحالة التي يضبطها هذا الزر، مثل الحالة التي يضبطها الاسترداد، تُغيَّر مباشرةً كتغيير يدوي للحالة، دون رسائل بريد إلكتروني ولا حركات مخزون.

الاسترداد

في التبويب، أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via Nets. أكّد السؤال Refund this amount through Nets? This cannot be undone. الاسترداد الكامل والجزئي مدعومان بعد تحصيل الدفعة، حتى إجمالي الطلب؛ ويمكن إلغاء الدفعة المحجوزة فقط في بوابة Nets. يُطبَّق الاسترداد على تحصيل الطلب في البيئة التي دُفع فيها، لذلك يجب ضبط المفتاح السري لتلك البيئة. وإذا لم تقبل Nets الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع معرّف استرداد Nets. يضبط الاسترداد الكامل الطلب على Refunded Status؛ أما الاسترداد الجزئي فلا يغيّر الحالة.

لا تعيد مرتجعات المنتجات في Sales > Returns أموالًا عبر Nets. والاستردادات المنفذة في بوابة Nets لا تُزامَن؛ حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

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

لا يظهر Nets Nexi أثناء الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع المحدد لديه مفتاح سري: Test Secret Key في وضع الاختبار، وLive Secret Key في وضع الإنتاج. تعرض صفحة الإعدادات تحذيرًا عند غياب المفتاح. وتحقّق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت الدفعة، لكن الطلب يبقى دون حالة: لم يصل الـ webhook إلى متجرك. تحقّق من أن المتجر يستخدم HTTPS، بحيث يكون العنوان في Webhooks عنوان HTTPS عامًا، ومن أن المفتاح السري لبيئة الدفعة مضبوط. ويحصل الطلب على حالته أيضًا عندما يعود العميل إلى المتجر بعد الدفع، أو عبر Nets: check payment status and capture في تبويب الطلب.

يرد الـ webhook بـ Unauthorized: لم يحمل الـ webhook السر الخاص بتلك الدفعة. لا تُقبل الـ webhooks إلا مع السر المسجَّل مع الدفعة.

يرد الـ webhook بـ Unknown payment: لم تُنشئ هذه الدفعة بواسطة هذا المتجر.

يرد الـ webhook بـ Busy, retry later أو Payment lookup failed أو Payment not reserved yet: كان طلب آخر يؤكد السلة نفسها، أو تعذّر الوصول إلى Nets API، أو لم يكن الحجز ظاهرًا بعد. وتعيد Nets إرسال الـ webhook تلقائيًا.

يرد الـ webhook بـ Order could not be updated, retry later: تعذّر تعيين حالة الطلب. وتعيد Nets إرسال الـ webhook. فعّل Debug log لرؤية السبب.

يعرض عنوان الـ webhook في المتصفح Method not allowed: هذا طبيعي. العنوان يقبل الطلبات الصادرة من Nets فقط.

يرى العميل خطأً بعد Confirm Order: فعّل Debug log وراجع الحقل Log في صفحة الإضافة. تعني الرسالة This payment method is temporarily unavailable. Please choose another payment method. عادةً وجود مفتاح سري خاطئ أو مفقود. وتُبلغ Nets بالعملة المرفوضة في السجل. وتعني This payment method is not available. أن جلسة الدفع لم تعد مطابقة للطلب، أو أن طريقة الدفع أُوقفت في الأثناء: يُعيد العميل تحميل صفحة الدفع.

يرى العميل الرسالة We could not match this payment to an order: رابط العودة غير مكتمل أو يخص طلبًا آخر. وإذا خُصم من العميل مبلغ، فابحث عن الدفعة في بوابة Nets وراجع الطلب.

الطلب في حالة التعليق بعد الدفع: اقرأ Nets notes في التبويب. إذا رُفض التحصيل، فأعد المحاولة باستخدام Nets: check payment status and capture أو حصّل الدفعة في بوابة Nets. وإذا اختلف المبلغ أو العملة، فتحقّق من الدفعة في بوابة Nets. وإذا دفع العميل بعد الإلغاء، فراجع الطلب وحصّل الحجز أو ألغِه.

الزر Refund via Nets غير موجود أو يفشل: الاسترداد ممكن فقط بعد تحصيل الدفعة؛ وعندئذ يعرض التبويب معرّف التحصيل. يستخدم الاسترداد المفتاح السري لبيئة دفع الطلب، لذا يجب ضبط ذلك المفتاح؛ وإلا فسيذكر التبويب أي مفتاح بيئة مفقود.

للمطوّرين: قبل إنشاء الدفعة، تُطلق الإضافة حدث OpenCart الذي اسمه nng_create_payment_payload مع نص الطلب والطلب نفسه؛ ويغيّر nng_currency_decimals عدد المنازل العشرية لعملة ما.

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

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

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

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