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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: الصول البيروفي (PEN) أو الدولار الأمريكي (USD). للعملات الأخرى تُخفى طريقة الدفع في صفحة الدفع.

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. أبقِ Sandbox mode مفعّلًا وأدخل merchant ID وAPI user وAPI password الخاصة بـ sandbox (انظر الإعداد).

6. فعّل Enable/Disable ونفّذ بعض المدفوعات التجريبية ببطاقات Niubiz التجريبية.

7. بعد أن تعتمد Niubiz تكاملك، أدخل بيانات الإنتاج وألغِ تحديد Sandbox mode.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Niubiz. فوق الحقول تحذّرك الصفحة عندما لا تكون عملة المتجر PEN أو USD، أو عندما تكون بيانات الاعتماد الخاصة بالوضع الحالي غير مكتملة (وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع)، وتعرض وضع sandbox مفعّل: تُرسل المدفوعات إلى sandbox الخاص بـ Niubiz، ولا تُجرى أي خصومات حقيقية. ما دام وضع sandbox مفعّلًا. وفي قائمة طرق الدفع تظهر 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 وكلمة مرور API للـ sandbox، وبعد الاعتماد للبيئة الفعلية. توجد وثائق المطورين على desarrolladores.niubiz.com.pe.

Sandbox mode: Use the Niubiz sandbox (QA) environment — no real charges. يبدّل نقاط نهاية API ومجموعة بيانات الاعتماد أدناه معًا. الافتراضي: مفعّل. ألغِ تحديده للمدفوعات الفعلية.

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

Sandbox API user: اسم مستخدم API الخاص بـ sandbox.

Sandbox API password: كلمة مرور API الخاصة بـ sandbox.

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

Production API user: اسم مستخدم API الخاص بالإنتاج.

Production API password: كلمة مرور API الخاصة بالإنتاج.

نموذج الدفع

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

متقدم

Debug log: Log API calls يكتب طلبات Niubiz في WooCommerce > Status > Logs، بالمصدر wcp_niubiz_payment. تُسجَّل الأخطاء دائمًا. لا تُسجَّل بيانات الاعتماد والرموز وبيانات البطاقة أو العميل أبدًا. الافتراضي: معطّل.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. إلغاء التفعيل لا يحذف أي شيء أبدًا. تبقى بيانات الدفع المحفوظة في الطلبات. الافتراضي: معطّل.

تُنقل إعدادات الإصدار 1.0، الذي كانت له مجموعة واحدة من بيانات الاعتماد، تلقائيًا: إلى حقول sandbox إذا كان وضع الاختبار مفعّلًا، وإلا إلى حقول الإنتاج.

صفحة الدفع

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

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

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

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

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

انتهت الجلسة: تستمر جلسة الدفع حتى 20 دقيقة. عند استخدامها أو اقترابها من الانتهاء، أو عند تغيّر مجموع الطلب أو الوضع، تنشئ صفحة الدفع جلسة جديدة.

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

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

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

الطلبات

حالات الطلب

بانتظار الدفع: أُرسل العميل إلى صفحة الدفع ولم يدفع بعد.

قيد المعالجة: وافقت Niubiz على الدفعة وتطابق الرد مع الطلب. تنتقل الطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل إلى حالة «مكتمل»، كالمعتاد في WooCommerce. تعرض ملاحظة الطلب البيئة ومعرّف المعاملة ورمز التفويض ورقم الشراء وعلامة البطاقة مع رقم البطاقة المخفي. معرّف معاملة الطلب هو معرّف معاملة Niubiz.

فشل: رُفضت البطاقة. تعرض ملاحظة الطلب سبب Niubiz ورمز الإجراء ورقم الشراء. يمكن للعميل أن يدفع مرة أخرى.

في الانتظار، موافَق عليه لكنه غير مطابق: وافقت Niubiz على دفعة يختلف رقم شرائها أو مبلغها أو عملتها عن الطلب، أو لا يحتوي ردّها على المبلغ أو العملة. لا يُعلَّم الطلب كمدفوع؛ وتسرد الملاحظة الفروق. تحقّق من المعاملة في لوحة Niubiz. يرى العميل تم استلام دفعتك وتقوم المتجر بمراجعتها.

في الانتظار، بلا نتيجة نهائية: لم ترد Niubiz بوضوح، لذا ربما خُصم مبلغ من البطاقة. تذكر الملاحظة رقم الشراء. ابحث عنه في لوحة Niubiz: إذا كانت المعاملة موافَقًا عليها وصحيحة، فاجعل الطلب قيد المعالجة؛ وإلا فألغِه.

ملغى: نقر العميل على Cancel order في صفحة الدفع، أو ألغيت الطلب بنفسك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce.

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

الاستردادات

الاستردادات والإلغاءات غير متاحة من WooCommerce. نفّذ الاسترداد أو الإلغاء للمعاملة في لوحة Niubiz، ثم حدّث الطلب يدويًا، مثلًا باسترداد يدوي في WooCommerce.

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

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

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

بدون مفتاح فعّال لا يظهر Niubiz للعملاء في صفحة الدفع. إذا بدأ الدفع رغم ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ويظل مديرو المتجر المسجلون الدخول يرون طريقة الدفع، مع علامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. يظهر تذكير في صفحة Plugins وفي صفحات WooCommerce. لا تتأثر الطلبات الحالية: تظل المدفوعات التي بدأت في نموذج Niubiz تُفوَّض.

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

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

لا يظهر Niubiz في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن معرّف التاجر واسم مستخدم API وكلمة مرور API للوضع الحالي مملوءة (حقول sandbox في وضع sandbox، وحقول الإنتاج في غير ذلك)، وأن العملة PEN أو USD. في صفحة Pay for order تُحتسب عملة الطلب. تعرض صفحة الإعدادات تحذيرًا عندما تكون بيانات الاعتماد أو العملة خاطئة.

تمّت الدفعة، لكن الطلب يبقى في حالة بانتظار الدفع: ليس لدى Niubiz webhook لنموذج الدفع هذا، لذا لا يُحدَّث الطلب إلا بالرد على التفويض. إذا كان الطلب في حالة «في الانتظار» مع ملاحظة، فابحث عن رقم الشراء في لوحة Niubiz. إذا بقي في حالة «بانتظار الدفع»، فالعميل لم يُكمل النموذج؛ تحقّق من WooCommerce > Status > Logs، بالمصدر wcp_niubiz_payment.

يرى العميل تعذّر الاتصال بـ Niubiz: تعذّر الحصول على رمز الوصول. تحقّق من اسم مستخدم API وكلمة مرور API للوضع الحالي، ومن أن خادمك يستطيع الوصول إلى واجهة Niubiz. فعّل Debug log للاطلاع على التفاصيل.

يرى العميل تعذّر بدء دفعة Niubiz: لم تنشئ Niubiz جلسة الدفع. تحقّق من معرّف التاجر للوضع الحالي ومن السجل.

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

يرى العميل أن جلسة الدفع انتهت ولم يُخصم مبلغ من بطاقتك: بقيت صفحة الدفع مفتوحة مدة طويلة. يحاول العميل مرة أخرى في الصفحة نفسها.

ملاحظة الطلب: أبلغت Niubiz عن تفويض مكرر: تعرف Niubiz رقم الشراء هذا مسبقًا. تحقّق منه في لوحة Niubiz؛ ويمكن للعميل المحاولة برقم شراء جديد.

الطلب في حالة «في الانتظار» مع ملاحظة من Niubiz: اقرأ الملاحظة. لم تُعطِ Niubiz نتيجة نهائية، أو وافقت على دفعة لا تطابق الطلب. ابحث عن رقم الشراء في لوحة Niubiz، واجعل الطلب قيد المعالجة أو ألغه.

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

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

للمطورين: إذا طلبت Niubiz إرسال حقول مكافحة الاحتيال الخاصة بالتاجر (MDD)، فأضفها عبر الفلتر niubiz_p_merchant_define_data. المفاتيح هي MDD متبوعًا برقم، والقيم حتى 100 حرف. فلاتر أخرى: niubiz_p_cardholder_data (بيانات حامل البطاقة المرسلة مع جلسة الدفع)، وniubiz_p_purchase_number (رقم شراء المحاولة، من 1 إلى 12 حرفًا أو رقمًا، وفريد لكل محاولة)، وniubiz_p_icon (أيقونة طريقة الدفع).

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

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

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