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

المتطلبات

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

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

العملة: الصول البيروفي (PEN) أو الدولار الأمريكي (USD). تُعرض طريقة الدفع فقط للسلال المقوّمة بإحدى هاتين العملتين. وبالنسبة للعملات الأخرى تُخفى عند إتمام الشراء.

حساب Niubiz: تُصدر Niubiz معرّف تاجر (código de comercio) وAPI user وAPI password لكل بيئة. تأتي بيانات اعتماد البيئة التجريبية من فريق التكامل لدى Niubiz، أما بيانات اعتماد البيئة الفعلية فتأتي بعد أن تعتمد Niubiz تكاملك. لا حاجة إلى إعداد أي webhook: تردّ Niubiz على التفويض فورًا.

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

التثبيت

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

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

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

4. أبقِ Sandbox mode مفعّلًا وأدخل merchant ID وAPI user وAPI password الخاصة بالبيئة التجريبية (انظر الإعدادات).

5. فعّل Enable/Disable وانقر على Save ثم أجرِ بعض المدفوعات التجريبية ببطاقات الاختبار الخاصة بـ Niubiz.

6. بعد أن تعتمد Niubiz تكاملك، أدخل بيانات اعتماد البيئة الفعلية وألغِ تفعيل Sandbox mode.

عند التثبيت تُنشئ الوحدة حالة الطلب Niubiz payment on hold. يربط PrestaShop وحدة الدفع الجديدة بجميع العملات ومجموعات العملاء والدول النشطة في تلك اللحظة. يمكنك تغيير ذلك من Payment > Preferences. تحقّق هناك من أن الصول البيروفي أو الدولار الأمريكي مسموح به للوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Niubiz Payment > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول تحذّرك الصفحة إذا لم تكن هناك عملة PEN أو USD مفعّلة في المتجر، أو إذا كانت بيانات اعتماد الوضع الحالي غير مكتملة (وفي الحالتين تُخفى طريقة الدفع عند إتمام الشراء). وإذا لم تكن العملة الافتراضية للمتجر PEN ولا USD، تُعلمك الصفحة بأن Niubiz متاحة فقط للسلال المقوّمة بـ PEN أو USD. وطالما أن وضع Sandbox مفعّل، تعرض الصفحة الرسالة التالية: وضع Sandbox مفعّل: تُرسل المدفوعات إلى بيئة Niubiz التجريبية ولا يُخصم أي مبلغ فعلي.

Niubiz

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

Title: اسم طريقة الدفع الذي يراه العملاء عند إتمام الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit or debit card (Niubiz). مطلوب: لا يُحفظ العنوان الفارغ، ويبقى العنوان السابق.

Description: النص الذي يظهر أسفل طريقة الدفع عند إتمام الشراء. الافتراضي: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

بيانات اعتماد Niubiz

تمنحك Niubiz معرّف تاجر وAPI user وAPI password للبيئة التجريبية، وبعد الاعتماد للبيئة الفعلية. وتوثيق المطوّرين موجود على desarrolladores.niubiz.com.pe.

Sandbox mode: يستخدم بيئة Niubiz التجريبية (QA)، ولا تُخصم أي مبالغ فعلية. ويغيّر نقاط نهاية الواجهة ومجموعة بيانات الاعتماد أدناه معًا. الافتراضي: مفعّل. عطّله للمدفوعات الفعلية. وطالما هو مفعّل يرى العملاء أسفل طريقة الدفع وفي صفحة الدفع الرسالة: وضع SANDBOX: استخدم بطاقات اختبار Niubiz — لا يُخصم أي مبلغ فعلي.

Sandbox merchant ID: رمز التاجر لحساب البيئة التجريبية، أرقام فقط. تُحذف المسافات. إذا احتوت القيمة على أحرف أخرى، تعرض الصفحة خطأ وتحتفظ بالقيمة السابقة. تُحفظ الحقول الأخرى.

Sandbox API user: معرّف API user للبيئة التجريبية.

Sandbox API password: كلمة مرور API للبيئة التجريبية.

Production merchant ID: رمز التاجر لحسابك الفعلي (المنتسب)، أرقام فقط، مع التحقق نفسه.

Production API user: معرّف API user للبيئة الفعلية.

Production API password: كلمة مرور API للبيئة الفعلية.

لا تُعرض كلمات المرور المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — اتركه فارغًا للاحتفاظ بها. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved passwords: ضع علامة على كلمة مرور وانقر على Save لحذفها. الحقل الفارغ يُبقي القيمة المحفوظة.

نموذج الدفع

Logo URL: عنوان HTTPS اختياري لشعارك يُعرض في نموذج الدفع الخاص بـ Niubiz، بمقاس نحو 187 × 40 بكسل. وبدونه يُعرض اسم المتجر. العنوان الذي لا يكون عنوان https:// صالحًا يُرفض مع خطأ ويبقى العنوان السابق.

متقدم

Debug log: يسجّل استدعاءات API الخاصة بـ Niubiz في logs/niubiz_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون هذا المفتاح معطّلًا. لا تُسجَّل بيانات الاعتماد أو الرموز أو بيانات البطاقة أو العميل أبدًا. الافتراضي: معطّل.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وسجلها. أما بيانات الدفع المحفوظة للطلبات (محاولات Niubiz وملاحظات الطلب) وحالة الطلب فتبقى دائمًا. الافتراضي: معطّل.

إتمام الشراء

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit or debit card (Niubiz)) ويقدّم الطلب. تطلب الوحدة من Niubiz رمز وصول وجلسة دفع بإجمالي السلة بعملة السلة، ثم تفتح صفحة الدفع Niubiz payment في متجرك. لا يوجد أي طلب في هذه المرحلة.

في صفحة الدفع يُفتح نموذج الدفع الخاص بـ Niubiz تلقائيًا. وتقول الصفحة: أكمل الدفع في نموذج الدفع الآمن لـ Niubiz — تُدخَل بيانات بطاقتك في Niubiz، وليس في هذا الموقع. كما تحتوي على زر Pay يعرض إجمالي السلة لإعادة فتح النموذج، ورابط Choose another payment method. يلزم تفعيل JavaScript. وإذا تعذّر تحميل نموذج Niubiz، تعرض الصفحة: تعذّر تحميل نموذج الدفع الخاص بـ Niubiz. يُرجى تحديث الصفحة أو المحاولة لاحقًا.

يُدخل العميل بطاقته في نموذج Niubiz. تُعيد Niubiz إلى متجرك رمزًا لمرة واحدة، وتعتمده الوحدة على الخادم بالمبلغ والعملة ورقم الشراء الخاصين بالجلسة، وفي البيئة التي أُنشئت فيها الجلسة. يُخصم المبلغ فورًا. لا يُعلَّم الطلب كمدفوع إلا عندما توافق Niubiz على الدفعة وتتطابق الاستجابة مع السلة. بعد ذلك يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية.

البطاقة المرفوضة: لا يُنشأ أي طلب. يعود العميل إلى صفحة الدفع مع تم رفض دفعتك: والسبب الصادر عن Niubiz، ويمكنه المحاولة مرة أخرى بالبطاقة نفسها أو ببطاقة أخرى. لا يُعاد فتح النموذج فوق الرسالة؛ ينقر العميل على Pay.

لا توجد استجابة من Niubiz: إذا لم تعطِ Niubiz ردًا نهائيًا (انتهاء المهلة، خطأ في الخادم، استجابة غير مقروءة)، يُنشأ الطلب في حالة Niubiz payment on hold، وتعرض صفحة التأكيد: تعذّر علينا تأكيد دفعتك مع Niubiz. يُرجى عدم الدفع مرة أخرى — سيتحقق المتجر من الدفعة وسيتواصل معك. وإذا وافقت Niubiz على دفعة لا تطابق السلة، تعرض الصفحة: تم استلام دفعتك وهي قيد المراجعة من المتجر. سنتواصل معك إذا لزم أي شيء آخر.

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

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

انتهت صلاحية الجلسة: تبقى جلسة الدفع في Niubiz صالحة لمدة 20 دقيقة كحد أقصى. إذا استُخدمت الجلسة من قبل، أو بقي لها أقل من 5 دقائق، أو تنتمي إلى وضع أو merchant ID آخر، أو تغيّر إجمالي السلة، تُنشئ صفحة الدفع جلسة جديدة.

تحصل كل محاولة دفع على رقم شراء جديد: معرّف السلة متبوعًا برقم محاولة من ثلاثة أرقام (حتى 12 حرفًا)، لأن Niubiz تشترط رقم شراء فريدًا لكل تفويض.

تقبل الوحدة مدفوعات البطاقات لمرة واحدة فقط. لا توجد استردادات أو إلغاءات من PrestaShop، ولا بطاقات محفوظة أو اشتراكات أو مدفوعات متكررة، ولا اختيار للأقساط (cuotas)، ولا مدفوعات عبر PagoEfectivo أو Yape أو المحافظ الإلكترونية الأخرى أو QR. ولا تُعاد مراجعة الطلبات المعلّقة بسبب ضياع الاستجابة تلقائيًا.

الطلبات

حالات الطلب

No order yet: العميل في صفحة الدفع ولم يدفع، أو رُفضت البطاقة، أو رُفض الطلب. لا توجد سوى السلة. تُكتب حالات الرفض في سجل الوحدة.

Payment accepted: وافقت Niubiz على الدفعة وتطابقت الاستجابة مع السلة. تُسجَّل الدفعة بمعرّف معاملة Niubiz، وتعرض ملاحظة البيئة ومعرّف المعاملة ورمز التفويض ورقم الشراء وعلامة البطاقة مع رقم البطاقة المقنّع.

Niubiz payment on hold, approved but not matching: وافقت Niubiz على دفعة يختلف رقم شرائها أو مبلغها أو عملتها عن السلة، أو لا تحتوي استجابتها على المبلغ أو العملة. لا يُعلَّم الطلب كمدفوع. وإذا كانت الموافقة بعملة السلة، فيُسجَّل المبلغ المعتمد كدفعة مع معرّف معاملته. تسرد الملاحظة الفروق. تحقّق من المعاملة في وحدة تحكم Niubiz.

Niubiz payment on hold, no definitive answer: لم تردّ Niubiz بوضوح، لذلك ربما خُصم المبلغ من البطاقة. لا تُسجَّل أي دفعة. تذكر الملاحظة رقم الشراء. ابحث عنه في وحدة تحكم Niubiz: إذا كانت المعاملة معتمدة وصحيحة فاجعل الطلب Payment accepted، وإذا لم تكن كذلك فألغِه.

إذا وصلت استجابة لدفعة ثانية لسلة لها طلب بالفعل، فلا يُنشأ طلب ثانٍ. تعرض ملاحظة على الطلب رقم الشراء ومعرّف المعاملة والمبلغ، لتتمكن من التحقق منها في وحدة تحكم Niubiz واسترداد المبلغ أو إبطاله إذا لزم الأمر.

كتلة الدفع في Niubiz

تعرض صفحة الطلب كتلة Niubiz payment تتضمن رقم الشراء والبيئة (التجريبية أو الفعلية) ومعرّف المعاملة ورمز التفويض والبطاقة وملاحظات الطلب. وبالنسبة للطلب في حالة Niubiz payment on hold تذكّرك الكتلة بالتحقق من رقم الشراء في وحدة تحكم Niubiz. الكتلة للقراءة فقط.

الاستردادات

الاستردادات والإلغاءات غير متاحة من PrestaShop. استرد المعاملة أو ألغِها في وحدة تحكم Niubiz، ثم حدّث الطلب يدويًا. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Niubiz.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Niubiz Payment هي أول كتلة في صفحة Modules > Module Manager > VibeFox Niubiz Payment > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-niubiz والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل المفتاح غير موجود أو هذا المفتاح يخص منتجًا آخر أو تم بلوغ حد النطاقات أو انتهت صلاحية الترخيص في مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

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

بدون مفتاح فعّال لا تظهر Niubiz للعملاء عند إتمام الشراء. وإذا بُدئ الدفع رغم ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند إتمام الشراء. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: المدفوعات التي بدأت بالفعل تظل مؤكدة.

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

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

لا يظهر Niubiz عند إتمام الشراء: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن merchant ID وAPI user وAPI password الخاصة بالوضع الحالي مملوءة (حقول البيئة التجريبية في وضع Sandbox، وحقول البيئة الفعلية في غير ذلك)، وأن عملة السلة PEN أو USD. تعرض صفحة الإعدادات تحذيرًا إذا كانت بيانات الاعتماد أو العملات خاطئة. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

تمّت الدفعة لكن لم يُنشأ أي طلب: لا تملك Niubiz webhook لنموذج الدفع هذا، لذلك لا يُنشأ الطلب إلا بالاستجابة للتفويض. إذا لم يُكمل العميل النموذج فلا يوجد طلب. وإلا فانظر إلى الحقل Log في صفحة الوحدة وابحث عن رقم الشراء في وحدة تحكم Niubiz. وإذا ردّت Niubiz لكن تعذّر إنشاء الطلب (مثلًا لأن الوحدة كانت معطّلة)، فسيرى العميل تم استلام دفعتك، لكن تعذّر إكمال الطلب تلقائيًا. يُرجى التواصل معنا — لا تدفع مرة أخرى.، وستحاول الوحدة إنشاء الطلب مرة أخرى عندما يفتح العميل صفحة الدفع مجددًا.

يرى العميل الرسالة «We could not connect to Niubiz»: تعذّر الحصول على رمز الوصول. تحقّق من API user وAPI password الخاصين بالوضع الحالي، ومن أن خادمك يستطيع الوصول إلى واجهة Niubiz البرمجية. فعّل Debug log للاطلاع على التفاصيل.

يرى العميل الرسالة «We could not start the Niubiz payment»: لم تُنشئ Niubiz جلسة الدفع. تحقّق من merchant ID الخاص بالوضع الحالي ومن السجل.

يرى العميل الرسالة «This payment attempt was already processed»: أُرسل النموذج نفسه مرتين. يبدأ العميل الدفع من جديد في صفحة الدفع؛ ولا يُخصم من البطاقة مرتين.

يرى العميل الرسالة «This order is already being paid»: طلب آخر يفوّض السلة نفسها في هذه اللحظة. ينتظر العميل قليلًا ويتحقق من بريده الإلكتروني قبل المحاولة مرة أخرى.

يُظهر السجل الرسالة «Niubiz reported a duplicate authorization»: تعرف Niubiz رقم الشراء هذا مسبقًا. تحقّق منه في وحدة تحكم Niubiz؛ ويمكن للعميل المحاولة مرة أخرى برقم شراء جديد.

الطلب في حالة Niubiz payment on hold: اقرأ الملاحظات في كتلة Niubiz payment. لم تعطِ Niubiz ردًا نهائيًا، أو وافقت على دفعة لا تطابق السلة. ابحث عن رقم الشراء في وحدة تحكم Niubiz واجعل الطلب Payment accepted أو ألغِه.

خطأ عند حفظ الإعدادات: يجب أن يحتوي merchant ID على أرقام فقط، ويجب أن يكون عنوان الشعار عنوان https:// صالحًا. تُحتفظ بالقيمة السابقة.

للمطوّرين: إذا طلبت Niubiz إرسال حقول مكافحة الاحتيال الخاصة بالتاجر (MDD)، يمكن لوحدة أخرى إضافتها عبر الخطاف actionNiubizPMerchantDefineData. ويمكن تعديل بيانات حامل البطاقة المرسلة مع جلسة الدفع عبر الخطاف actionNiubizPCardholderData.

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

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

Niubiz علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Niubiz ولا معتمدة من قِبلها.