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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. انسخ المفتاح السري للاختبار من بوابة اختبار Nets Easy، والصقه في Test Secret Key (انظر قسم الإعداد).

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

الإعداد

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Nets Nexi (Nordics). وفوق الحقول تحذرك الصفحة إذا كان المفتاح السري للوضع المحدد مفقودًا (فتُخفى طريقة الدفع حينها في صفحة الدفع)، وتعرض Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. طالما وضع الاختبار مفعّل. وفي قائمة طرق الدفع يُوسم Nets Nexi بأنه يحتاج إلى إعداد حتى يكون للوضع المحدد مفتاح سري.

عام

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

Title: عنوان طريقة الدفع الذي يظهر للعملاء في صفحة الدفع. الافتراضي: Nets Easy.

Description: وصف طريقة الدفع الذي يظهر للعملاء في صفحة الدفع. الافتراضي: Pay securely with Nets Easy.

مفاتيح API

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

Test Mode: Enable test mode. يستخدم وضع الاختبار المضيف test.api.dibspayment.eu مع المفتاح السري للاختبار؛ ويستخدم وضع الإنتاج المضيف api.dibspayment.eu مع المفتاح السري للإنتاج. وتستخدم الاستردادات والتحصيلات الخاصة بالطلب دائمًا البيئة التي دُفع فيها الطلب. الافتراضي: مفعّل.

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

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

الدفع

تُسجَّل إشعارات Nets (الـ Webhooks) تلقائيًا مع كل دفعة. ولا يوجد ما يُضبط في بوابة Nets. يعرض هذا القسم عنوان Webhook، وهو بالشكل https://your-site/wc-api/nng_nets_nexi/. وإذا لم يكن العنوان عنوان HTTPS عامًا، يحذرك القسم من أن الموقع لا يستقبل الـ Webhooks؛ وعندها تُؤكَّد المدفوعات عند عودة العميل إلى المتجر أو عبر إجراء الطلب Nets: check payment status and capture. وتُسجَّل الأحداث التالية:

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

Order Status After Payment: حالة الطلب بعد أن تؤكد Nets الدفعة وتحصّلها. تُضبط الحالة فورًا حتى يتلقى العميل بريدًا إلكترونيًا واحدًا.

متقدم

Debug log: Enable debug logging يسجّل استدعاءات API وتغييرات حالة الدفع في WooCommerce > Status > Logs، بالمصدر wcp_nets_nexi_gateway. وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل المفاتيح وبيانات العملاء. الافتراضي: معطّل.

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف أي شيء أبدًا. وتبقى بيانات الدفع المحفوظة في الطلبات دائمًا. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Nets Easy) ويقدّم الطلب. تُنشئ الإضافة دفعة Nets بأسطر الطلب والشحن والرسوم بعملة الطلب، وتنقل العميل إلى صفحة الدفع المستضافة لدى Nets. وتُمرَّر بيانات العميل من البريد الإلكتروني والاسم والعنوان ورقم الهاتف إلى Nets عندما تقبل Nets صيغتها؛ ويُربط رابط صفحة الشروط والأحكام الخاصة بك في صفحة Nets. وفي وضع الاختبار تعرض صفحة الدفع Test mode: no real money will be charged.

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

إذا ألغى العميل في صفحة Nets، فإنه يعود إلى صفحة الدفع أو صفحة Pay for order مع الرسالة The Nets payment was cancelled. You can try again or choose another payment method. ويستطيع العميل إعادة دفع طلب غير مدفوع. تتحقق الإضافة أولًا من الدفعة السابقة؛ فإذا كانت مدفوعة، يُؤكَّد الطلب. وإلا تُغلق جلسة Nets السابقة قبل بدء جلسة جديدة. وإذا احتُجزت دفعة للطلب لمراجعتها من المتجر، يرى العميل A payment for this order is already being reviewed by the shop. Please contact us instead of paying again.

إذا لم تتمكن Nets من بدء الدفع، يرى العميل رسالة قصيرة، مثل Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method. أو The payment service could not be reached. Please try again in a moment. وتُكتب التفاصيل في السجل.

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Nets ولم يدفع بعد. تعرض ملاحظة الطلب معرّف دفعة Nets والمبلغ والبيئة.

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

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

Cancelled: أُلغي حجز آخر دفعة للطلب، مثلًا في بوابة Nets.

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

إجراء الطلب

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

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Nets Easy (يستخدم الزر عنوان طريقة الدفع). وتُدعم الاستردادات الكاملة والجزئية بعد تحصيل الدفعة؛ ويمكن إلغاء الدفعة المحجوزة فقط في بوابة Nets. ويُطبَّق الاسترداد على تحصيل الطلب في البيئة التي دُفع فيها. وإذا لم تقبل Nets الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف استرداد Nets.

لا تتحول الاستردادات التي تُجرى مباشرة في بوابة Nets إلى استردادات WooCommerce. وإذا لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Nets Easy.

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

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

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

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

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

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

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

تمت الدفعة لكن الطلب ما زال في Pending payment: لم يصل الـ Webhook إلى متجرك. تحقق من أن الموقع يستخدم HTTPS وروابط دائمة واضحة، بحيث يكون عنوان الـ Webhook في قسم Payment عنوان HTTPS عامًا دون "&"، ومن أن المفتاح السري لبيئة الدفعة مضبوط. ثم استخدم إجراء الطلب Nets: check payment status and capture. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى صفحة استلام الطلب.

Webhook answers Unauthorized: لم يحمل الـ Webhook سر هذا الطلب. ولا تُقبل الـ Webhooks إلا بالسر المسجَّل مع الدفعة.

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

يرى العميل خطأ عند تقديم الطلب: فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_nets_nexi_gateway. وتعني This payment method is temporarily unavailable. Please choose another payment method. غالبًا وجود مفتاح سري خاطئ أو مفقود. وتُبلغ Nets عن العملة المرفوضة في السجل.

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

Refund via Nets Easy مفقود أو يفشل: الاستردادات ممكنة فقط بعد تحصيل الدفعة. تحقق من تحصيلها في ملاحظة الطلب. ويستخدم الاسترداد المفتاح السري للبيئة التي دُفع فيها الطلب، لذا يجب أن يكون ذلك المفتاح مضبوطًا.

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

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

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

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