VibeFox Netopia for OpenCart — المساعدة

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث، مع امتدادات OpenSSL وDOM وSimpleXML.

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

حساب Netopia: تحتاج إلى حساب بائع لدى Netopia Payments مع نقطة بيع. ومن إعداداته التقنية تحتاج إلى توقيع الحساب، ولكل بيئة تستخدمها (الاختبار والفعلية) إلى الشهادة العامة (.cer) والمفتاح الخاص (.key). لا يلزم إعداد أي شيء في Netopia: يُرسل عنوان IPN مع كل طلب دفع.

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

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

التثبيت

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

OpenCart 3

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

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

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

4. في لوحة إدارة Netopia، افتح نقطة البيع الخاصة بك، وانسخ توقيع الحساب، ونزّل الشهادة والمفتاح الخاص لبيئة الاختبار وللبيئة الفعلية. الصق التوقيع والمحتوى الكامل للملفات في الإعدادات (راجع Configuration).

5. فعّل Enable/Disable وانقر على Save. اختبر عملية دفع في وضع الاختبار (sandbox)، ثم أوقف Test mode لقبول المدفوعات الحقيقية.

OpenCart 4

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

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

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

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

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

الإعداد

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

عند الحفظ، يمكن أن يصل طول Title إلى 128 حرفاً، ويجب أن يكون Sort order عدداً صحيحاً (الأعداد السالبة مسموحة)، ويجب أن يكون Minimum total رقماً أكبر من 0 أو يساويه، ويجب أن تكون المنطقة الجغرافية وحالات الطلب موجودة؛ وإذا كان أي من هذه غير صحيح، فلن يُحفظ أي شيء. تُرفض الشهادة أو المفتاح الخاص غير الصالح مع رسالة خطأ بالأحمر، ويُحتفظ بالقيمة السابقة، بينما تُحفظ الحقول الأخرى (Settings saved, except the values shown in red.). وإذا كانت طريقة الدفع مفعّلة لكن البيئة النشطة غير مكتملة، يظهر تحذير عند الحفظ.

عنوان IPN (التأكيد)

يعرض القسم الأول IPN (confirm) URL للقراءة فقط. يبدو بالشكل التالي في OpenCart 3: https://your-store/index.php?route=extension/payment/wcp_netopia_gateway/notify، وفي OpenCart 4: https://your-store/index.php?route=extension/wcp_netopia_gateway/payment/wcp_netopia_gateway.notify. ويُبنى من عنوان واجهة متجرك في تثبيت OpenCart. يُرسل مع كل طلب دفع بوصفه عنوان التأكيد، لذلك لا تحتاج إلى إدخاله في لوحة إدارة Netopia. يرسل Netopia الـ IPN إلى هذا العنوان. تفكّ الإضافة تشفيره بالمفتاح الخاص للبيئة التي بدأ فيها الدفع، وتتحقق من توقيع حسابك وطلب الدفع. يُبلغ Netopia عن هذه الإجراءات:

يضبط الإشعار الذي يحمل رمز خطأ من Netopia (مثل بطاقة مرفوضة) الطلب المعلّق إلى حالة خطأ الدفع؛ ويبقى الطلب الذي لا حالة له بلا حالة، ويستطيع العميل الدفع مرة أخرى. تُرفض الإشعارات التي لا يمكن فك تشفيرها، أو التي تحمل توقيع حساب مختلفاً، أو التي لا تستجيب لطلب دفع لذلك الطلب في تلك البيئة، ولا تغيّر شيئاً. تُقبل الإشعارات الخاصة بعمليات دفع بدأت بالفعل حتى لو أوقفت طريقة الدفع.

Checkout

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

Title: عنوان طريقة الدفع المعروض في صفحة الدفع. وهو أيضاً اسم طريقة الدفع المحفوظ في الطلب. حتى 128 حرفاً؛ اتركه فارغاً لاستخدام القيمة الافتراضية. الافتراضي: Card Payment (Netopia).

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

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

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

Minimum total: إجمالي الطلب، بعملة المتجر الافتراضية، الذي يجب أن يصله الطلب قبل عرض Netopia. اتركه فارغاً إذا لم يكن هناك حد أدنى.

حساب Netopia

في لوحة إدارة Netopia، انتقل إلى Seller accounts > your point of sale > Technical settings: انسخ توقيع الحساب ونزّل الشهادة العامة (.cer) والمفتاح الخاص (.key) لكل بيئة. افتح الملفات في محرر نصوص والصق محتواها الكامل، بما في ذلك سطرا BEGIN وEND. يحتوي القسم على رابط إلى وثائق Netopia v1.

Account signature: توقيع حساب البائع (بصيغة XXXX-XXXX-XXXX-XXXX-XXXX)، وهو نفسه للاختبار والبيئة الفعلية.

Test mode: يستخدم بيئة Netopia التجريبية (sandboxsecure.mobilpay.ro) ومفاتيحها. الافتراضي: مفعّل. أوقفه لتحصيل مدفوعات حقيقية بالمفاتيح الفعلية (secure.mobilpay.ro). ما دام مفعّلاً، يرى العميل Test mode (Netopia sandbox): no real money is charged. في خطوة Confirm Order.

Sandbox public certificate (.cer): محتوى ملف الشهادة العامة للبيئة التجريبية. يُستخدم لتشفير طلب الدفع.

Sandbox private key (.key): محتوى ملف المفتاح الخاص للبيئة التجريبية. يُستخدم لفك تشفير الـ IPN.

Live public certificate (.cer): محتوى ملف الشهادة العامة للبيئة الفعلية.

Live private key (.key): محتوى ملف المفتاح الخاص للبيئة الفعلية.

لا تُعرض المفاتيح الخاصة المحفوظة مرة أخرى أبداً. يبقى الحقل فارغاً، ويبدأ نص المساعدة فيه بالعبارة A private key is saved. اترك الحقل فارغاً للاحتفاظ بالمفتاح المحفوظ، أو الصق مفتاحاً جديداً لاستبداله. لحذف مفتاح محفوظ، فعّل خانة Clear the saved private key on save أسفل الحقل، ثم انقر على Save. ويؤدي ترك حقل الشهادة فارغاً إلى حذف الشهادة.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا عندما يُبلغ Netopia عن عملية الدفع. لا تملك OpenCart حالات طلبات خاصة بـ Netopia، لذلك تسرد كل خانة أدناه حالات الطلبات في OpenCart الخاصة بك. وتشرح الملاحظات على الطلب كل تغيير.

Order status after payment: حالة الطلب المدفوع.

Processing status: الافتراضي: قيد المعالجة.

Completed status: الافتراضي: مكتمل.

Awaiting Netopia payment: تفويض مسبق بانتظار التحصيل في لوحة إدارة Netopia، أو عملية دفع قيد المراجعة لدى Netopia. الافتراضي: قيد الانتظار.

Netopia payment on hold: تحتاج عملية الدفع إلى مراجعتك (راجع Order statuses). الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة معلّق. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا. تفصل الإضافة بين حالتي "قيد الانتظار" و"معلّق" حتى عندما تستخدمان الحالة نفسها.

Canceled status: ألغى Netopia عملية دفع طلب قيد الانتظار. الافتراضي: ملغى.

Payment error status: أبلغ Netopia عن خطأ، مثل بطاقة مرفوضة، لطلب قيد الانتظار. الافتراضي: فشل.

Refunded status: لم يبقَ شيء لاسترداده بعد عمليات الاسترداد التي تمت في لوحة إدارة Netopia. الافتراضي: مُسترَد.

متقدم

Debug log: يكتب الطلبات ومعالجة الـ IPN في netopia_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى netopia_p_debug.old.log.php. لا تُسجَّل بيانات البطاقات والمفاتيح وتفاصيل العملاء. تُسجَّل الأخطاء، مثل الـ IPN المرفوضة، دائماً حتى عندما يكون الخيار معطّلاً. الافتراضي: معطّل.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تُحفظ سجلات الدفع الخاصة بـ Netopia والطلبات دائماً. الافتراضي: معطّل.

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

Export: يحفظ Download JSON الإعدادات، مع الشهادات، في ملف JSON. لا تُصدَّر المفاتيح الخاصة.

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضياً Card Payment (Netopia)). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the Netopia secure page to pay with your card. ينشئ OpenCart الطلب في هذه الخطوة، ما زال بدون حالة. عندما ينقر العميل على Confirm Order، تبني الإضافة طلب الدفع، وتشفّره بشهادة Netopia الخاصة بالبيئة النشطة، وتنقل العميل مباشرة إلى صفحة دفع Netopia. يحتوي الطلب على إجمالي الطلب بعملة الطلب، وOrder # مع رقم الطلب، وبيانات الاتصال للفوترة والشحن مع هاتف الطلب. في وضع الاختبار (sandbox) يُرسل إلى بيئة Netopia التجريبية. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

يدفع العميل بالبطاقة في صفحة Netopia ويعود إلى متجرك. ولا تدفع العودة نفسها أي طلب أبداً. لا يُعلَّم الطلب مدفوعاً إلا بعد أن يؤكد Netopia ذلك عبر الـ IPN. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسالة البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وبالنسبة إلى طلب قيد الانتظار، تعرض الصفحة Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. وبالنسبة إلى طلب معلّق، تعرض Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. وعندما يحصل طلب قيد الانتظار أو معلّق لاحقاً على حالته النهائية (مدفوع، أو خطأ في الدفع، أو ملغى)، يُرسَل إلى العميل بريد إلكتروني بالحالة الجديدة. وبالنسبة إلى طلب ملغى تعرض الصفحة The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. وبالنسبة إلى طلب فيه خطأ في الدفع تعرض The payment was declined by Netopia.

إذا لم يصل الـ IPN بعد عند عودة العميل، تعرض صفحة Payment confirmation النص نفسه "لم يُؤكَّد بعد" مع الزرين Check again وBack to checkout. يحصل الطلب على حالته بمجرد وصول الـ IPN.

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

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

إذا تعذّر بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة فوق الزر: Netopia gateway is not configured properly. Please contact the store administrator.، أو Netopia cannot process payments in مع العملة، أو This order has nothing to pay.، أو Payment encryption failed. Please try again or contact support. ويُكتب السبب التقني في السجل.

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

تقبل الإضافة مدفوعات البطاقات عبر بروتوكول البطاقات Netopia v1 فقط. لا توجد عمليات استرداد أو تحصيل من OpenCart، ولا بطاقات محفوظة أو مدفوعات بنقرة واحدة، ولا اشتراكات أو أقساط أو طرق دفع أخرى، ولا واجهة Netopia API v2.

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

Order statuses

No status (missing order): أُرسل العميل إلى Netopia ولم يدفع، أو لم يرسل Netopia الـ IPN بعد، أو أُلغيت عملية الدفع أو رُفضت قبل أي نتيجة. في Sales > Orders لا تظهر هذه الطلبات إلا مع تعيين المرشح Order Status على Missing Orders.

Processing or Completed status: أكّد Netopia عملية الدفع. تتبع الحالة Order status after payment. تعرض ملاحظة المبلغ والبطاقة المقنّعة ومعاملة Netopia؛ وتُعلَّم مدفوعات الاختبار بالعبارة [sandbox].

Awaiting Netopia payment: عملية الدفع تفويض مسبق بانتظار التحصيل في لوحة إدارة Netopia، أو هي قيد المراجعة لدى Netopia. ينتقل الطلب إلى حالة مدفوع عندما يؤكدها Netopia.

Netopia payment on hold: يختلف مبلغ الفاتورة أو عملتها عن الطلب، أو جرى تحصيل جزء فقط من الدفع، أو أكّد Netopia دفع طلب ملغى أو طلب دُفع بطريقة دفع أخرى، أو أُكّدت عملية دفع تجريبية (sandbox) بينما المتجر في الوضع الفعلي (لم يُستلم أي مال حقيقي). لا يُعلَّم الطلب مدفوعاً؛ وتشرح الملاحظة السبب. تحقق من المعاملة في لوحة إدارة Netopia، ثم نفّذ الطلب أو استرد الدفع هناك.

Payment error status: أبلغ Netopia عن خطأ، مثل بطاقة مرفوضة، لطلب قيد الانتظار.

Canceled status: ألغى Netopia عملية دفع طلب قيد الانتظار.

Refunded status: تم استرداد عملية الدفع بالكامل في لوحة إدارة Netopia.

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

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

تبويب VibeFox Netopia Gateway

في Sales > Orders افتح طلباً مدفوعاً عبر Netopia. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Netopia Gateway كتلة Netopia Payments: معاملة Netopia، والبيئة (الاختبار أو الفعلية)، وطلب الدفع، وحالة الطلب، وآخر إجراء للـ IPN، والبطاقة المقنّعة، والمبالغ المدفوعة والمُستردة والمتبقية، وسجل الاسترداد، وNetopia notes الخاصة بالطلب. التبويب للقراءة فقط، ويظهر للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

لا تتم عمليات الاسترداد والتحصيل من OpenCart: لا يحتوي بروتوكول البطاقات Netopia v1 على استدعاء للاسترداد. استرد المعاملة في لوحة إدارة Netopia. عندها يرسل Netopia إشعار IPN دائناً، وتسجّل الإضافة الاسترداد تلقائياً على الطلب مع الملاحظة Netopia refund processed: والمبلغ. يحتفظ الاسترداد الجزئي بحالة الطلب؛ وعندما لا يبقى شيء لاسترداده، يُضبط الطلب على Refunded status. بالنسبة إلى طلبات EUR وUSD وGBP، يُحوَّل المبلغ المُسترَد، الذي يبلّغ عنه Netopia بالـ RON، مرة أخرى إلى عملة الطلب. لا يُسجَّل الاسترداد مرتين أبداً، ولا يُسجَّل بمبلغ يزيد على المتبقي. وإذا أبلغ Netopia عن خطأ في الاسترداد، تُضاف ملاحظة فقط.

لا ترسل المرتجعات الخاصة بالمنتجات في Sales > Returns أي أموال عبر Netopia.

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

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

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

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

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

Netopia does not appear at checkout: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن البيئة النشطة مكتملة (Account signature مع الشهادة والمفتاح الخاص للبيئة التجريبية في وضع الاختبار، أو للبيئة الفعلية في الوضع الفعلي)، وأن العميل يدفع بعملة RON أو EUR أو USD أو GBP. تعرض صفحة الإعدادات تحذيراً عند غياب أي عنصر. وتحقّق أيضاً من أن عنوان الدفع موجود في Geo zone المحددة، وأن الطلب يبلغ Minimum total.

The payment went through, but the order stays without a status: لم يصل الـ IPN إلى متجرك أو رُفض. تحقق من أن عنوان IPN (التأكيد) في الإعدادات متاح من الإنترنت (بلا مصادقة أساسية أو جدار ناري). انظر إلى الحقل Log في صفحة الإضافة: تُسجَّل الـ IPN المرفوضة دائماً. فعّل Debug log لرؤية كل IPN. ولا تدفع مجرد عودة العميل أي طلب أبداً.

Log shows failed decrypting data: المفتاح الخاص لا يطابق الشهادة التي استخدمها Netopia. يُفك تشفير الـ IPN بالمفتاح الخاص المحفوظ لكل بيئة، لذلك احتفظ بمفتاح البيئة الأخرى محفوظاً ما دامت مدفوعاتها مفتوحة. يعيد Netopia محاولة الـ IPN.

Log shows signature mismatch: يختلف Account signature عن نقطة البيع التي أرسلت الـ IPN. انسخه مرة أخرى من لوحة إدارة Netopia.

Log shows unknown payment request: لا يستجيب الـ IPN لطلب دفع أرسله متجرك لذلك الطلب في تلك البيئة (الاختبار أو الفعلية). لا يتغير شيء.

Log shows gateway not configured: لا يوجد مفتاح خاص أو توقيع حساب محفوظ. يعيد Netopia محاولة الـ IPN، ويُسجَّل الدفع عند اكتمال الإعدادات.

Log shows busy, retry later or processing failed: كانت السلة تُعالَج بطلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. يعيد Netopia محاولة الـ IPN تلقائياً.

Error on save about the certificate or private key: النص الملصوق ليس شهادة أو مفتاحاً صالحاً. الصق المحتوى الكامل للملف، بما في ذلك سطرا BEGIN وEND. تم الاحتفاظ بالقيمة السابقة.

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

Order is in the on-hold status after payment: اقرأ الملاحظات في تبويب VibeFox Netopia Gateway (راجع Order statuses). كان المبلغ أو العملة مختلفين، أو جرى تحصيل جزء فقط، أو أُلغي الطلب، أو أُكّدت عملية دفع تجريبية بينما المتجر في الوضع الفعلي. تحقق من المعاملة في لوحة إدارة Netopia.

A refund made in Netopia does not appear on the order: لم يصل إشعار IPN الدائن إلى المتجر أو رُفض. تحقق من السجل.

للمطورين: يمكن تغيير قائمة العملات المقبولة بحدث OpenCart netopia_p_supported_currencies.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Netopia Gateway. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائماً. يحذف OpenCart دائماً إعدادات الإضافة الخاصة به: Enable/Disable، وSort order، وGeo zone، وMinimum total، وحالات الطلبات في قسم Orders التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 تُحذف أيضاً أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح للـ IPN بالمرور في وضع الصيانة). إذا كان Delete data on uninstall مفعّلاً، تُحذف بقية إعدادات البوابة (العنوان والوصف وتوقيع الحساب والوضع التجريبي والشهادات والمفاتيح الخاصة وحالة ما بعد الدفع والتسجيل) والسجل. وإذا كان معطّلاً، تُحفظ هذه البيانات لإعادة التثبيت لاحقاً. تُحفظ سجلات الدفع الخاصة بـ Netopia دائماً، بحيث يجد الـ IPN المتأخر لدفعة بدأت قبل إعادة التثبيت طلبه ما زال. تحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

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

Netopia Payments وmobilPay علامتان تجاريتان مسجلتان لمالكيهما. هذه الإضافة غير تابعة لـ Netopia Payments ولا معتمدة من قِبلها.