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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث مع امتدادي OpenSSL وDOM.

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

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل Enable/Disable. اختبر عملية دفع في وضع sandbox، ثم ألغِ تحديد Test mode لاستقبال مدفوعات حقيقية.

الإعداد

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

IPN (confirm) URL

يظهر للقراءة فقط في أعلى الإعدادات. ويبدو هكذا: https://your-site/wc-api/netopia_payment_callback/. يُرسل مع كل طلب دفع بوصفه عنوان التأكيد، لذا لا تحتاج إلى إدخاله في لوحة Netopia. ترسل Netopia الإشعار IPN إلى هذا العنوان؛ وتفكّ الإضافة تشفيره بالمفتاح الخاص للبيئة النشطة، وتتحقق من توقيع حسابك وطلب الدفع. وتبلغ Netopia عن الإجراءات التالية:

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

الدفع

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

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: Use the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys. يبدّل صفحة الدفع وزوج المفاتيح. الافتراضي: مفعّل. عطّله لاستقبال مدفوعات حقيقية بمفاتيح الإنتاج.

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

Sandbox private key (.key): محتوى ملف المفتاح الخاص لبيئة sandbox. يُستخدم لفك تشفير الإشعار IPN. لا يُعرض بعد الحفظ مرة أخرى؛ ويعرض الحقل A private key is saved. اتركه فارغًا للاحتفاظ بالمفتاح المحفوظ، أو الصق مفتاحًا جديدًا لاستبداله.

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

Live private key (.key): محتوى ملف المفتاح الخاص لبيئة الإنتاج. لا يُعرض بعد الحفظ مرة أخرى؛ اتركه فارغًا للاحتفاظ بالمفتاح المحفوظ.

الطلبات

Order status after payment: حالة الطلب المدفوع الذي يحتاج إلى شحن. الطلبات التي تحتوي على منتجات افتراضية أو قابلة للتنزيل فقط يُكمِلها WooCommerce في كل الأحوال. تُضبط الحالة بتغيير واحد وبريد إلكتروني واحد للعميل.

متقدم

Debug log: Log requests and IPN processing يكتب في WooCommerce > Status > Logs، بالمصدر wcp_netopia_gateway. لا تُسجَّل بيانات البطاقات أو المفاتيح أو بيانات العملاء. وتُسجَّل الأخطاء، مثل الإشعارات IPN المرفوضة، دائمًا حتى لو كان الخيار معطّلًا. الافتراضي: معطّل.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (orders are kept). الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Card Payment (Netopia)) ويقدّم الطلب. تعرض الصفحة التالية Redirecting you to Netopia for secure payment… وتنقل العميل تلقائيًا إلى صفحة الدفع لدى Netopia، مع زرّي Proceed to payment وCancel order كخيار بديل. يُشفَّر طلب الدفع بشهادة Netopia الخاصة بك، ويتضمن إجمالي الطلب بعملة الطلب، وOrder # مع رقم الطلب، وبيانات الاتصال للفوترة والشحن. وفي وضع 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. وبالنسبة إلى طلب في حالة On hold تعرض 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.

إذا رُفضت البطاقة يُعلَّم الطلب بأنه Failed، ويستطيع العميل إعادة الدفع من صفحة الطلب. وإذا لم تكن الإضافة مُعدّة بشكل صحيح، تعرض صفحة الدفع Netopia gateway is not configured properly. Please contact the store administrator.

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

تقبل الإضافة مدفوعات البطاقات عبر بروتوكول Netopia v1 للبطاقات فقط. لا توفر استردادًا أو تحصيلًا من WooCommerce، ولا بطاقات محفوظة أو دفعًا بنقرة واحدة، ولا اشتراكات أو تقسيطًا أو رسائل SMS أو تحويلات مصرفية أو مدفوعات بالعملات المشفّرة، ولا تدعم Netopia API v2.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Netopia، أو لم ترسل Netopia الإشعار IPN بعد.

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

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

Failed: أبلغت Netopia عن خطأ، مثل رفض البطاقة. يستطيع العميل إعادة الدفع.

Cancelled: ألغت Netopia الدفعة، أو نقر العميل على Cancel order قبل الانتقال إلى Netopia.

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

الاستردادات

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

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

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

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

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

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

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

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

تمت الدفعة لكن الطلب ما زال في Pending payment: لم يصل الإشعار IPN إلى متجرك أو رُفض. تحقق من أن عنوان IPN (التأكيد) في الإعدادات متاح من الإنترنت (دون وضع الصيانة أو المصادقة الأساسية أو جدار حماية يمنعه). فعّل Debug log وابحث عن أسطر IPN في WooCommerce > Status > Logs بالمصدر wcp_netopia_gateway. فعودة العميل وحدها لا تُعلّم الطلب كمدفوع أبدًا.

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

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

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

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

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

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

A refund made in Netopia does not appear on the order: لم يصل إشعار IPN الخاص بالائتمان إلى المتجر أو رُفض. راجع السجل. وإذا لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce.

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

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

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

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