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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتدادات OpenSSL وDOM وSimpleXML. ترفض الوحدة التثبيت بدونها.

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

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

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

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

التثبيت

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

2. عند انتهاء الرفع، انقر على Configure، أو اعثر لاحقًا على VibeFox Netopia Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تنشئ الوحدة حالتين للطلب هما Awaiting Netopia payment وNetopia payment on hold. يوفر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. ويمكنك تقييدها من Payment > Preferences.

الإعدادات

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

IPN (confirm) URL

يظهر للقراءة فقط في أعلى الصفحة. ومع الروابط الودية يبدو بالشكل https://your-shop/module/wcp_netopia_gateway/notify، وقد يحتوي على رمز لغة مثل /en/. يُرسل مع كل طلب دفع بوصفه رابط التأكيد، لذلك لا تحتاج إلى إدخاله في لوحة Netopia. ترسل Netopia الإشعار IPN إلى هذا الرابط. تفك الوحدة تشفيره بالمفتاح الخاص للبيئة التي بدأت فيها الدفعة، وتتحقق من توقيع حسابك وطلب الدفع. وتبلّغ Netopia عن هذه الإجراءات:

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

الدفع

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

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

Description: وصف طريقة الدفع الذي يظهر في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via Netopia.

حساب Netopia

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

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

Test mode: يستخدم sandbox لدى Netopia (sandboxsecure.mobilpay.ro) ومفاتيح sandbox. الافتراضي: on. أطفئه لاستقبال المدفوعات الحقيقية بمفاتيح الإنتاج.

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

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

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

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

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

Clear saved private keys: حدّد مفتاحًا وانقر على Save لحذفه. ويحتفظ الحقل الفارغ بالمفتاح المحفوظ.

الطلبات

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

متقدم

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

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

Delete data on uninstall: يحذف عند إلغاء تثبيت الوحدة إعدادات البوابة وسجلات الدفع الخاصة بـ Netopia لدى الوحدة والسجل. تبقى الطلبات. الافتراضي: off.

صفحة الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Card Payment (Netopia)) ويؤكد. تعرض الصفحة التالية Redirecting you to Netopia for secure payment… وتنقل العميل تلقائيًا إلى صفحة الدفع لدى Netopia، مع زري Proceed to payment وCancel (للعودة إلى صفحة الدفع) كخيار احتياطي. يُشفَّر طلب الدفع بشهادة Netopia الخاصة بك ويتضمن إجمالي السلة بعملة السلة، وCart # مع رقم السلة، وبيانات الاتصال للفوترة والشحن. وفي وضع sandbox يُرسل الطلب إلى sandbox لدى Netopia. لا يوجد طلب في هذه المرحلة.

يدفع العميل بالبطاقة في صفحة Netopia ثم يعود إلى متجرك. لا تنشئ العودة نفسها طلبًا ولا تدفعه أبدًا. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Netopia عبر IPN. وإذا كان الطلب موجودًا، يرى العميل صفحة تأكيد الطلب القياسية. وللطلب المعلّق تعرض الصفحة 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. تبقى السلة محفوظة. وكل محاولة جديدة هي طلب دفع جديد؛ وتبقى طلبات السلة السابقة صالحة، لذلك تُسجَّل أيضًا IPN متأخرة من محاولة سابقة.

إذا لم تكن الوحدة مُعدّة بشكل صحيح، يبقى العميل في صفحة الدفع مع الرسالة 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 أثناء وجود المتجر في وضع الصيانة، ولا يحجبها قيد الدول في متجرك.

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

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Netopia ولم يدفع بعد، أو لم ترسل Netopia إشعار IPN بعد. لا توجد إلا السلة.

Payment accepted or Delivered: أكدت Netopia الدفعة. تتبع الحالة Order status after payment. تُسجَّل الدفعة مع معاملة Netopia بوصفها معرّف المعاملة، وتعرض ملاحظة خاصة المبلغ ورقم البطاقة المُقنَّع ومعاملة Netopia؛ وتُعلَّم دفعات sandbox بالعلامة [sandbox].

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

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

Payment error: أبلغت Netopia عن خطأ، مثل رفض البطاقة، لطلب معلّق.

Canceled: ألغت Netopia دفعة طلب معلّق.

Refunded: استُرد المبلغ بالكامل في لوحة Netopia.

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

كتلة Netopia

تعرض صفحة الطلب كتلة Netopia Payments تتضمن معاملة Netopia، والبيئة (sandbox أو الإنتاج)، وطلب الدفع، وآخر إجراء لـ IPN، والبطاقة المُقنَّعة، والمبالغ المدفوعة والمستردة والمتبقية، وسجل الاستردادات. الكتلة للقراءة فقط.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة، ولا تعيد المنتجات إلى المخزون. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Netopia.

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

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

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

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

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

Netopia لا يظهر في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة النشطة مكتملة (Account signature إضافة إلى الشهادة والمفتاح الخاص لـ sandbox في وضع الاختبار، أو لبيئة الإنتاج في وضع الإنتاج)، وأن عملة السلة هي RON أو EUR أو USD أو GBP. تعرض صفحة الإعدادات تحذيرًا عند نقص أي عنصر. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ودولة العميل ومجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: لم تصل IPN إلى متجرك أو رُفضت. تحقق من أن رابط IPN (التأكيد) في الإعدادات متاح من الإنترنت (دون مصادقة أساسية أو جدار حماية). انظر إلى حقل Log في صفحة الوحدة: تُسجَّل الإشعارات IPN المرفوضة دائمًا. فعّل Debug log لرؤية كل إشعار IPN. وعودة العميل وحدها لا تنشئ طلبًا أبدًا.

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

يعرض السجل signature mismatch: Account signature يختلف عن نقطة البيع التي أرسلت IPN. انسخه من جديد من لوحة Netopia.

يعرض السجل unknown payment request: الإشعار IPN لا يستجيب لطلب دفع أنشأه متجرك لتلك السلة في تلك البيئة (sandbox أو الإنتاج). لا يتغير شيء.

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

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

خطأ عند الحفظ بشأن الشهادة أو المفتاح الخاص: النص الملصوق ليس شهادة أو مفتاحًا صالحًا. الصق محتوى الملف كاملًا، بما في ذلك سطرا BEGIN/END. وقد احتُفظ بالقيمة السابقة.

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

الاسترداد الذي أُجري في Netopia لا يظهر على الطلب: لم يصل إشعار IPN الدائن إلى المتجر أو رُفض. راجع السجل.

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Netopia Gateway، واختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Delete data on uninstall مفعّلًا، تُحذف إعدادات البوابة (بما فيها المفاتيح المحفوظة)، وسجلات الدفع الخاصة بـ Netopia لدى الوحدة (المعروضة في كتلة Netopia للطلبات)، والسجل. وإذا كان معطّلًا، يُحتفظ بكل شيء لإعادة التثبيت لاحقًا. ولا تُحذف الطلبات ولا حالتا الطلب Awaiting Netopia payment وNetopia payment on hold أبدًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات الخاصة بها.

Netopia Payments وmobilPay علامتان تجاريتان مملوكتان لأصحابهما. هذه الوحدة غير تابعة لـ Netopia Payments ولا تحظى بتأييدها.