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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: البيزو الكولومبي (COP). تحصّل Wompi Colombia بالعملة COP فقط، وتُخفى وسيلة الدفع للطلبات بعملات أخرى.

حساب Wompi: حساب تاجر لدى Wompi Colombia. لكل بيئة (بيئة الاختبار وبيئة الإنتاج) أربعة مفاتيح: المفتاح العام، والمفتاح الخاص، وسر الأحداث، وسر التكامل. تجدها في لوحة تحكم التاجر في Wompi (comercios.wompi.co) ضمن قسم المطوّرين. لا تدعم Wompi El Salvador وPanama، لأنهما تستخدمان واجهات برمجة تطبيقات مختلفة.

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

التثبيت

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

2. انقر على Activate.

3. اضبط عملة المتجر على البيزو الكولومبي (COP) في WooCommerce > Settings > General.

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

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

6. الصق مفاتيح بيئة الاختبار وبيئة الإنتاج من لوحة تحكم التاجر في Wompi، واضبط Events URL في Wompi (انظر الإعدادات).

7. فعّل Enable/Disable. جرّب عملية دفع في وضع Sandbox، ثم ألغِ تحديد Sandbox mode لقبول المدفوعات الحقيقية.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Wompi. يعرض مربع الحالة فوق الحقول الوضع الحالي، أي SANDBOX أو PRODUCTION. وعند غياب أحد مفاتيح هذا الوضع، يسرد المربع المفتاح الناقص ويوضح أن وسيلة الدفع مخفية في صفحة الدفع إلى أن تُعدّ جميع مفاتيح هذه البيئة. وعند اكتمال جميع المفاتيح، يوضح المربع ما إذا كانت المدفوعات الحقيقية ستُحصَّل. وعند الحفظ، تحذّرك الإضافة إذا لم يبدأ مفتاح ببادئة قسمه، وإذا كانت Wompi مفعّلة لكنها مخفية في صفحة الدفع لنقص المفاتيح. وفي قائمة وسائل الدفع، تُعلَّم Wompi على أنها تحتاج إلى إعداد إلى أن تكتمل المفاتيح الأربعة للوضع الحالي. وتُنقل مفاتيح الإصدار 1.0 تلقائيًا إلى قسم Sandbox أو Production المناسب عند التحديث.

عام

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

Title: اسم وسيلة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Wompi.

Description: النص الذي يظهر أسفل وسيلة الدفع في صفحة الدفع. الافتراضي: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

حساب Wompi

انسخ المفاتيح من لوحة تحكم التاجر في Wompi (comercios.wompi.co)، ضمن قسم المطوّرين. لكل بيئة مفتاحها العام ومفتاحها الخاص وسر الأحداث وسر التكامل.

Sandbox mode: Use the Wompi sandbox (sandbox keys, no real money). يبدّل هذا الخيار المفاتيح وواجهة برمجة تطبيقات Wompi معًا (sandbox.wompi.co أو production.wompi.co). تحتفظ الطلبات بالبيئة التي دُفعت فيها. الافتراضي: مفعّل. ألغِ التحديد لقبول المدفوعات الحقيقية.

مفاتيح بيئة الاختبار

المفاتيح الأربعة لبيئة اختبار Wompi. وتبدأ بالبادئات pub_test_ وprv_test_ وtest_events_ وtest_integrity_.

Public key: المفتاح العام لبيئة الاختبار (pub_test_...). يحدد حسابك في Wompi Web Checkout.

Private key: المفتاح الخاص لبيئة الاختبار (prv_test_...). يُستخدم لقراءة المعاملات من واجهة برمجة تطبيقات Wompi.

Events secret: سر أحداث بيئة الاختبار (test_events_...). يتحقق من توقيع أحداث Wompi.

Integrity secret: سر تكامل بيئة الاختبار (test_integrity_...). يوقّع طلب الدفع المرسل إلى Web Checkout.

مفاتيح بيئة الإنتاج

المفاتيح الأربعة لبيئة إنتاج Wompi. وتبدأ بالبادئات pub_prod_ وprv_prod_ وprod_events_ وprod_integrity_.

Public key: المفتاح العام لبيئة الإنتاج (pub_prod_...).

Private key: المفتاح الخاص لبيئة الإنتاج (prv_prod_...).

Events secret: سر أحداث بيئة الإنتاج (prod_events_...).

Integrity secret: سر تكامل بيئة الإنتاج (prod_integrity_...).

Events URL (webhook)

تُخبر أحداث Wompi متجرك بأن معاملة قد تغيّرت. في لوحة تحكم التاجر في Wompi، ضمن قسم المطوّرين، اضبط Events URL الظاهر في هذا القسم من الإعدادات، لكل من بيئة الاختبار وبيئة الإنتاج. يبدو على هذا النحو: https://your-site/wc-api/wompi_p/. انسخ الرابط تمامًا كما تعرضه الإعدادات.

تستخدم الإضافة هذا الحدث:

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

متقدم

Debug log: يكتب Log payment and webhook activity نشاط المدفوعات والأحداث في WooCommerce > Status > Logs، بالمصدر wcp_wompi_payment. تُسجَّل الأخطاء دائمًا حتى عندما يكون هذا الخيار معطّلًا. ولا تُسجَّل المفاتيح والأسرار وبيانات العملاء أبدًا. الافتراضي: معطّل.

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

الدفع

يختار العميل وسيلة الدفع (وهي افتراضيًا Wompi) ويُتم الطلب. وفي وضع Sandbox، تعرض صفحة الدفع الرسالة Sandbox mode: no real payment is made. أسفل الوصف. تُنشئ الإضافة محاولة دفع برقم مرجعي خاص بها (WC- ورقم الطلب وطابع زمني)، وتوقّعها بسر التكامل، وترسل العميل إلى Wompi Web Checkout مع إجمالي الطلب بالعملة COP. يُمرَّر البريد الإلكتروني للفوترة واسم العميل إلى Wompi. وتسجّل ملاحظة الطلب البيئة والرقم المرجعي والمبلغ.

في صفحة Wompi، يدفع العميل بأي وسيلة دفع مفعّلة في حسابك لدى Wompi. ثم تعيد Wompi العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Wompi: إما بحدث موقَّع، أو بطلب من جهة الخادم إلى واجهة برمجة تطبيقات Wompi عندما يصل العميل إلى تلك الصفحة. ولا يُعتمد رقم المعاملة الموجود في عنوان الرجوع نفسه. وعند إعادة تحميل الصفحة، تُعاد مراجعة المعاملة مرة واحدة كحد أقصى كل 20 ثانية.

لا يمكن أن تدفع هذا الطلب إلا المعاملات التي أُنشئت له، وفي بيئة المحاولة نفسها فقط. ويمكن للعميل أن يدفع طلبًا غير مدفوع مرة أخرى، مثلًا من صفحة Pay for order. وتحصل كل محاولة على رقم مرجعي جديد.

تظهر وسيلة الدفع فقط عندما تكون الرخصة فعّالة، وتكون المفاتيح الأربعة للوضع الحالي مُعدّة، وتكون عملة الطلب COP، ويكون الإجمالي 1,500 COP على الأقل. وإذا تعذّر بدء الدفع، يرى العميل رسالة قصيرة ويمكنه اختيار وسيلة دفع أخرى:

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

لا تُجري الإضافة استردادات من WooCommerce. ولا يتضمن موقعك بطاقات محفوظة ولا اشتراكات ولا حقول بطاقات: تُدخل جميع بيانات الدفع في Wompi.

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى Wompi ولم يدفع بعد، أو لم تؤكد Wompi المعاملة بعد.

On hold (pending payment): تُبلغ Wompi عن المعاملة بأنها قيد الانتظار، مثل مدفوعات PSE أو Nequi أو النقد التي تنتظر التأكيد. ويبقى الطلب في حالة الانتظار إلى أن توافق عليه Wompi أو ترفضه.

Processing or Completed: تمت الموافقة على المعاملة. ويُطبَّق معيار WooCommerce: قيد المعالجة، أو مكتمل للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. تعرض ملاحظة الطلب معاملة Wompi ونوع وسيلة الدفع (مثل البطاقة أو PSE أو Nequi) والرقم المرجعي. ومعرّف معاملة الطلب هو معرّف معاملة Wompi.

On hold after payment: وافقت Wompi على مبلغ أو عملة يختلفان عن إجمالي الطلب (مثلًا، عُدِّل الطلب بعد بدء الدفع)، أو وافقت على الدفع بعد إلغاء الطلب. لا يُعلَّم الطلب كمدفوع. وتوضح ملاحظة الطلب ذلك. تحقق من الدفع في لوحة تحكم Wompi، ثم أكمل الطلب أو استرد المبلغ.

Failed: رُفضت معاملة آخر محاولة دفع أو انتهت بخطأ. وتُضاف رسالة Wompi إلى الملاحظة. ولا تغيّر نتائج المحاولات الأقدم الطلب.

Cancelled: أُلغيت معاملة آخر محاولة دفع في Wompi قبل أن يُدفع الطلب.

إذا وصلت دفعة ثانية معتمدة لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد النسخة المكررة في لوحة تحكم Wompi. وإذا أُلغيت معاملة الدفع في Wompi، تطلب منك ملاحظة مراجعة الطلب. ولا تضيف الدفعة المتأخرة لطلب مُسترَد إلا ملاحظة. ولا تكرر الأحداث المتكررة وعودة العملاء الملاحظات أو رسائل البريد الإلكتروني أو تغييرات المخزون أبدًا.

الاستردادات

لا تُرسل الاستردادات من WooCommerce. استرد المبلغ أو ألغِ الدفعة في لوحة تحكم التاجر في Wompi، ثم سجّل استردادًا يدويًا في WooCommerce. ويُضاف الإلغاء الذي يُجرى في Wompi إلى الطلب كملاحظة.

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

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

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

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

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

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

لا تظهر Wompi في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن المفاتيح الأربعة للوضع الحالي مُعدّة (يسرد مربع الحالة في صفحة الإعدادات المفاتيح الناقصة). وتحقق أيضًا من أن عملة الطلب COP وأن إجمالي الطلب 1,500 COP على الأقل.

تمت عملية الدفع لكن الطلب ما زال في Pending payment: لا يعمل Events URL. في لوحة تحكم Wompi، تحقق من أن Events URL مضبوط للبيئة التي تستخدمها (بيئة الاختبار أو الإنتاج) وأنه مطابق تمامًا للرابط الظاهر في الإعدادات. وتحقق من أن سر أحداث تلك البيئة موجود في القسم المناسب. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

يرد Events URL بـ Not configured: سر أحداث بيئة الحدث فارغ. ألصقه في الإعدادات.

يرد Events URL بـ Invalid signature: سر الأحداث يعود إلى بيئة أخرى أو حساب آخر. انسخه من جديد من لوحة تحكم Wompi.

يرد Events URL بـ Transaction lookup failed: لم تُرجع واجهة برمجة تطبيقات Wompi المعاملة، مثلًا بسبب مفتاح خاص غير صحيح أو مشكلة في الشبكة. سترسل Wompi الحدث مرة أخرى لاحقًا.

يرد Events URL بـ Busy, retry: كان طلب آخر يحدّث الطلب في اللحظة نفسها. سترسل Wompi الحدث مرة أخرى لاحقًا.

يرد Events URL بـ Environment mismatch: وصلت معاملة من بيئة الاختبار لمحاولة دفع في بيئة الإنتاج، أو العكس. لا تؤكد مدفوعات بيئة الاختبار طلبات بيئة الإنتاج أبدًا.

تحذير عند الحفظ «The key does not start with ...»: لُصق مفتاح في القسم الخطأ. تبدأ مفاتيح بيئة الاختبار بـ pub_test_ وprv_test_ وtest_events_ وtest_integrity_، وتبدأ مفاتيح الإنتاج بـ pub_prod_ وprv_prod_ وprod_events_ وprod_integrity_.

الطلب في حالة On hold مع ملاحظة عن المبلغ: المبلغ أو العملة المعتمدة يختلفان عن إجمالي الطلب. تحقق من الدفع في لوحة تحكم Wompi، ثم أكمل الطلب أو استرد المبلغ يدويًا.

أخطاء أخرى: افتح ملاحظات الطلب أو WooCommerce > Status > Logs، بالمصدر wcp_wompi_payment. تُسجَّل الأخطاء دائمًا. فعّل Debug log للحصول على تفاصيل أكثر. ويمكن للمطوّرين السماح بعملة أخرى عبر الفلتر wompi_p_supported_currencies إذا كان حساب Wompi يقبلها.

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

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

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

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