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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث مع امتداد cURL. ترفض الوحدة التثبيت على إصدارات PHP الأقدم أو بدون cURL.

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

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

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

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

التثبيت

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

2. عند اكتمال الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Nets Nexi Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت، تنشئ الوحدة حالة الطلب Nets payment on hold. يربط PrestaShop وحدة الدفع الجديدة فقط بالبلدان النشطة وقت التثبيت. راجع العملات والبلدان ومجموعات العملاء الخاصة بالوحدة في Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. لكل قسم زر 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. طالما وضع الاختبار مفعّل.

Nets Nexi (دول الشمال)

يعرض عنوان القسم TEST أو LIVE للوضع المحدد.

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

Title: عنوان وسيلة الدفع الذي يراه العملاء أثناء الدفع. وهو أيضًا اسم وسيلة الدفع المحفوظ في الطلب. الافتراضي: Nets Easy. مطلوب: يؤدي العنوان الفارغ إلى الخطأ Enter a title for the payment method. ولا يُحفظ أي شيء.

Description: وصف وسيلة الدفع الذي يراه العملاء أثناء الدفع. الافتراضي: Pay securely with Nets Easy.

مفاتيح API

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

Test Mode: يستخدم وضع الاختبار test.api.dibspayment.eu مع المفتاح السري للاختبار، ويستخدم وضع الإنتاج api.dibspayment.eu مع المفتاح السري للإنتاج. وتستخدم الاستردادات والتحصيلات الخاصة بالطلب دائمًا البيئة التي دُفع فيها. الافتراضي: on. وما دام مفعّلًا، يرى العملاء تحت وسيلة الدفع الرسالة 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 saved secrets: ضع علامة على مفتاح ثم انقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع

Webhooks: تُسجَّل إشعارات Nets (الـ Webhooks) تلقائيًا مع كل دفعة. لا يوجد ما يلزم إعداده في بوابة Nets. يعرض القسم العنوان الذي تُرسل إليه. ومع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_nets_nexi_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. إذا لم يكن العنوان HTTPS عامًا، يحذّرك القسم من أن المتجر لا يستقبل الـ Webhooks؛ عندها تُؤكَّد المدفوعات عند عودة العميل إلى المتجر أو عبر Nets: check payment status and capture: في صفحة الطلب. وتُسجَّل الأحداث التالية:

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

Order Status After Payment: حالة الطلب بعد أن تؤكد Nets الدفعة وتحصّلها.

متقدم

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

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

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

الدفع

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

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Nets: تقرأ الوحدة الدفعة من واجهة Nets البرمجية، وتقارن المبلغ المحجوز والعملة بالسلة، وتحصّل الحجز، ثم تنشئ الطلب عندها فقط. ويحدث ذلك عبر الـ Webhook أو عند عودة العميل، أيهما يأتي أولًا. ثم يرى العميل صفحة تأكيد الطلب القياسية. وإذا تعذّر تأكيد الدفعة بعد (تعذّر الوصول إلى Nets، أو كان طلب آخر يؤكدها في تلك اللحظة)، تعرض صفحة Payment confirmation الرسالة Your Nets payment is being confirmed. Your order will be created 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. وتبقى السلة محفوظة. وعند المحاولة من جديد، تتحقق الوحدة أولًا من الدفعة السابقة؛ فإذا كانت مدفوعة بالفعل، يُنشأ الطلب بدلًا من دفعة جديدة. وإلا تُغلق جلسة Nets السابقة قبل بدء جلسة جديدة.

إذا تعذّر على 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. أو 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. وتُكتب التفاصيل في السجل.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Nets ولم يدفع، أو أن الدفعة لم تُؤكَّد بعد. لا توجد إلا السلة.

Payment accepted or Delivered: أكدت Nets الدفعة وحصّلتها. وتتبع الحالة Order Status After Payment. تُسجَّل الدفعة بمعرّف دفعة Nets كمعرّف للمعاملة، وتعرض ملاحظة معرّف الدفعة ومعرّف التحصيل ووسيلة الدفع.

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

Canceled: أُلغي حجز طلب معلّق، مثلًا في بوابة Nets.

Refunded: استُرد المبلغ كاملًا عبر الوحدة.

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

كتلة الدفع Nets Easy

تعرض صفحة الطلب كتلة Nets Easy payment تتضمن معرّف الدفعة، ومعرّف التحصيل، والبيئة (مع شارة Test environment للمدفوعات التجريبية)، والحالة، والمبالغ المحجوزة والمحصّلة لدى Nets، ومجموع الطلب والمبلغ المسترد، وسجل الاستردادات، وNets notes الخاصة بالطلب. وتعمل أزرار الكتلة لكل موظف يستطيع تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات Modules.

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

الاستردادات

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

لا تنشئ الوحدة إشعارات دائنة. ولا تعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب المال عبر Nets. ولا تتم مزامنة الاستردادات التي تُجرى في بوابة Nets؛ حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

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

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

تمت الدفعة لكن لم يُنشأ أي طلب: لم يصل الـ Webhook إلى متجرك. تحقق من أن المتجر يستخدم HTTPS والروابط الودية، بحيث يكون العنوان في Webhooks عنوان HTTPS عامًا بدون "&"، وأن المفتاح السري لبيئة الدفعة مضبوط. يُنشأ الطلب أيضًا عند عودة العميل إلى المتجر بعد الدفع.

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

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

يردّ الـ Webhook بـ Order could not be created, retry later: تعذّر إنشاء الطلب، مثلًا لأن الوحدة معطّلة. فعّل Debug log لمعرفة السبب.

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

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

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

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

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Nets Nexi Gateway، واختر Uninstall. يُزال مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Delete Data on Uninstall مفعّلًا، تُحذف إعدادات الوحدة وسجلها. وإذا كان معطّلًا، تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. وتبقى بيانات دفع Nets للطلبات (الدفعات والتحصيلات والاستردادات) وحالة الطلب Nets payment on hold محفوظة دائمًا، بحيث يمكن استرداد الطلبات المدفوعة سابقًا حتى بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها ومعرّفات المعاملات.

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