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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

5. فعّل Enable/Disable وانقر على Save. اختبر دفعة في وضع الاختبار، ثم أوقف Sandbox mode لقبول المدفوعات الحقيقية.

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting Wompi payment وWompi payment on hold. يعرض PrestaShop وحدة دفع جديدة للعملات والدول ومجموعات العملاء الموجودة في تلك اللحظة. تحقق من السماح بـ COP في Payment > Preferences. أي دولة تضيفها لاحقًا يجب تحديدها هناك قبل أن يرى عملاؤها Wompi.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Wompi Payment > Configure. لكل قسم يحتوي على حقول زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول يعرض صندوق الحالة الوضع الحالي، أي SANDBOX أو PRODUCTION. عند نقص مفتاح من هذا الوضع يعرض الصندوق المفتاح الناقص، ويوضح أن وسيلة الدفع مخفية في صفحة الدفع حتى تُعدّ جميع مفاتيح هذه البيئة. وعند اكتمال جميع المفاتيح يوضح ما إذا كانت ستُخصم مدفوعات حقيقية. وعند الحفظ تحذرك الوحدة إذا كان مفتاح لا يبدأ ببادئة قسمه، وإذا كانت Wompi مفعّلة لكنها مخفية في صفحة الدفع بسبب نقص المفاتيح.

Wompi

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

Title: اسم وسيلة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا الاسم المحفوظ لوسيلة الدفع في الطلب. الافتراضي: Wompi. إذا تُرك فارغًا فسيُستخدم اسم الوحدة.

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

حساب Wompi

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

Sandbox mode: يستخدم بيئة الاختبار لدى Wompi (مفاتيح الاختبار، ولا توجد أموال حقيقية). ويبدّل كلًا من المفاتيح وواجهة برمجة تطبيقات Wompi (sandbox.wompi.co أو production.wompi.co). تحتفظ محاولات الدفع بالبيئة التي جرت فيها. الافتراضي: on. أوقفه لقبول المدفوعات الحقيقية. وعند تفعيله يرى العملاء أسفل وسيلة الدفع الرسالة وضع الاختبار: لا تُجرى أي دفعة حقيقية.

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

المفاتيح الأربعة لبيئة اختبار 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_...).

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

Clear saved secrets: حدد مفتاحًا خاصًا أو سرًا لأي من البيئتين، ثم انقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

عنوان الأحداث (webhook)

تخبر أحداث Wompi متجرك بأن معاملة قد تغيّرت. في لوحة تحكم التاجر لدى Wompi، في قسم المطورين، اضبط عنوان الأحداث (Events URL) المعروض في هذا القسم، للاختبار وللإنتاج. ومع الروابط المختصرة يبدو هكذا https://your-shop/module/wcp_wompi_payment/webhook، وربما مع رمز لغة مثل /es/. انسخ العنوان تمامًا كما تعرضه الإعدادات.

تستخدم الوحدة هذا الحدث:

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

متقدم

Debug log: يسجّل نشاط الدفع وwebhook في logs/wompi_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عند إيقاف هذا الخيار. لا تُسجَّل المفاتيح والأسرار وبيانات العملاء أبدًا. الافتراضي: off.

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

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

الدفع

في خطوة الدفع يختار العميل وسيلة الدفع (افتراضيًا Wompi) ويؤكد. تُنشئ الوحدة محاولة دفع بمرجعها الخاص (PS- ورقم السلة وطابع زمني)، وتوقّعها بسر التكامل، وترسل العميل إلى Wompi Web Checkout مع إجمالي السلة بالبيزو الكولومبي. يُمرَّر البريد الإلكتروني للعميل واسم عنوان الفوترة إلى Wompi. لا يوجد أي طلب في هذه المرحلة.

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

عند اعتماد المعاملة يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة. في حالة الدفع المعلّق (مثل PSE أو Nequi أو الدفع النقدي) تعرض الصفحة دفعتك عبر Wompi قيد التأكيد (مثل PSE أو Nequi أو الدفع النقدي). سنعالج الطلب فور تأكيد Wompi للدفع. وفي حالة الطلب قيد الانتظار تعرض لقد استلمنا دفعتك عبر Wompi ونحن نراجعها. سنتواصل معك إذا لزم الأمر. وإذا رُفضت الدفعة المعلّقة لاحقًا تعرض الصفحة لم تتم الموافقة على دفعتك عبر Wompi. يرجى التواصل معنا. وإذا أُلغيت تعرض أُلغيت دفعتك عبر Wompi وأُلغي هذا الطلب. يرجى التواصل معنا.

إذا لم تؤكد Wompi المعاملة بعد عودة العميل، تظهر صفحة تعرض نحن في انتظار تأكيد Wompi لدفعتك. ستتلقى رسالة بريد إلكتروني فور تأكيدها. مع زر Check again. ينشئ حدث Wompi الطلب بمجرد وصوله.

إذا رُفض الدفع فلا يُنشأ أي طلب وتُحفظ السلة. يعود العميل إلى صفحة الدفع مع الرسالة لم تتم الموافقة على دفعتك عبر Wompi (...). يمكنك المحاولة مرة أخرى أو اختيار وسيلة دفع أخرى. مع السبب الذي تقدمه Wompi. ويعرض الدفع الملغى الرسالة أُلغيت دفعتك عبر Wompi. يمكنك المحاولة مرة أخرى أو اختيار وسيلة دفع أخرى. وإذا غادر العميل Web Checkout دون دفع، فالرسالة هي لم تكتمل دفعتك عبر Wompi. يمكنك المحاولة مرة أخرى أو اختيار وسيلة دفع أخرى. تحصل كل محاولة جديدة على مرجع جديد. وبمجرد أن تحمل السلة طلبًا (مدفوعًا أو معلّقًا أو Payment error أو Canceled) لا يمكن دفعها مرة أخرى، ويُنقل العميل إلى صفحة تأكيد الطلب.

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

يعمل عنوان الأحداث أثناء وضع الصيانة في المتجر، ولا يتأثر بقيد الدول في متجرك.

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

الطلبات

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Wompi ولم يدفع، أو رُفضت الدفعة، أو لم تؤكد Wompi المعاملة بعد. توجد السلة فقط.

Awaiting Wompi payment: تُبلغ Wompi بأن المعاملة قيد الانتظار، مثل مدفوعات PSE أو Nequi أو النقد التي تنتظر التأكيد. ينتظر الطلب حتى توافق عليه Wompi أو ترفضه. عند الموافقة تُسجَّل الدفعة وينتقل الطلب إلى Payment accepted.

Payment accepted: اعتُمدت المعاملة بمبلغ السلة بالبيزو الكولومبي (COP). تُسجَّل الدفعة بمعرّف معاملة Wompi، وتعرض الملاحظة المعاملة ونوع وسيلة الدفع (مثل CARD أو PSE أو NEQUI) والمرجع والمبلغ والبيئة.

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

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

Canceled: أُلغيت في Wompi معاملة معلّقة لآخر محاولة دفع.

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

كتلة دفع Wompi

تعرض صفحة الطلب كتلة Wompi payment تتضمن المرجع ومعرّف المعاملة والحالة (مع حالة Wompi) والمبلغ المطلوب ومبلغ المعاملة ووسيلة الدفع ورسالة Wompi، وشارة SANDBOX لمدفوعات الاختبار، وPayment attempts الخاصة بالسلة عند وجود أكثر من محاولة، وWompi notes الخاصة بالطلب.

الاسترداد

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

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

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

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

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

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

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

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

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

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

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

يرد عنوان الأحداث بـ Retry: كان الطلب يُؤكَّد بطلب آخر في الوقت نفسه، أو تعذر إنشاء الطلب (مثلًا الوحدة معطّلة). ستعيد Wompi إرسال الحدث لاحقًا. راجع حقل Log لمعرفة السبب.

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

يرد عنوان الأحداث بـ Unknown reference: مرجع المعاملة لم يصدره هذا المتجر، مثلًا لأن الحساب نفسه في Wompi يستخدمه متجر آخر. تتلقى مراجع الأنظمة الأخرى الرد Ignored.

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

تحذير عند الحفظ بأن المفتاح لا يبدأ بـ ...: لُصق مفتاح في القسم الخطأ. تبدأ مفاتيح الاختبار بـ pub_test_ وprv_test_ وtest_events_ وtest_integrity_، وتبدأ مفاتيح الإنتاج بـ pub_prod_ وprv_prod_ وprod_events_ وprod_integrity_.

الطلب في حالة Wompi payment on hold: اقرأ الملاحظات في كتلة Wompi payment (انظر حالات الطلب)، ثم أنجز الطلب أو استرد الدفعة من لوحة Wompi.

أخطاء أخرى: راجع حقل Log في صفحة الوحدة وملاحظات Wompi notes الخاصة بالطلب. تُسجَّل الأخطاء دائمًا. فعّل Debug log للحصول على تفاصيل أكثر.

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

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

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