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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

العملة: يجب أن تكون السلة بعملة KES أو UGX أو TZS أو ZMW أو RWF أو USD. في العملات الأخرى تُخفى طريقة الدفع في خطوة الدفع. تُحصَّل السلة بعملتها الخاصة، ولا تحوّل الوحدة العملات. تُرسل المبالغ بالوحدات الرئيسية، مقربةً وفق دقة العملة (لا توجد منازل عشرية لـ UGX وRWF).

حساب Pesapal: تحتاج إلى مفتاح المستهلك وسرّ المستهلك لحساب تاجر لدى Pesapal. مفاتيح بيئة الاختبار (sandbox) ومفاتيح بيئة الإنتاج مختلفة. تأتي مفاتيح الاختبار من حساب تاجر تجريبي على cybqa.pesapal.com (تنشر Pesapal أيضًا مفاتيح تجريبية في بوابة المطورين لديها). أما مفاتيح الإنتاج فتأتي من لوحة تحكم التاجر لديك في Pesapal. لا يلزم إعداد شيء آخر في لوحة Pesapal: تسجّل الوحدة عنوان URL الخاص بالإشعارات بنفسها. يجب أن يكون متجرك متاحًا من الإنترنت، لأن Pesapal ترسل إليه إشعارات الدفع.

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

التثبيت

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

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

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

4. أدخل مفتاح المستهلك وسرّه لبيئة الاختبار، وفعّل Enable/Disable، وانقر على Save، ثم أجرِ طلب اختبار.

5. أدخل مفتاح المستهلك وسرّه لبيئة الإنتاج، وألغِ تفعيل Sandbox mode، ثم انقر على Save لقبول المدفوعات الحقيقية.

عند التثبيت تُنشئ الوحدة حالة الطلب Pesapal payment on hold. تفعّل PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييد ذلك من Payment > Preferences.

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها. فوق الحقول تعرض شارة الوضع: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. أو LIVE — Real payments on pay.pesapal.com. يظهر تحذير عندما تكون مفاتيح الوضع الحالي مفقودة (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout.، أو الرسالة نفسها لبيئة الإنتاج)، وعندما لا تدعم Pesapal العملة الافتراضية لمتجرك.

Pesapal

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

Title: اسم طريقة الدفع الذي يراه العملاء في الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Pesapal (M-Pesa, Airtel Money, cards). مطلوب: لا يُحفظ العنوان الفارغ، ويبقى العنوان السابق.

Description: النص الذي يظهر تحت طريقة الدفع في خطوة الدفع. الافتراضي: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

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

يشرح هذا القسم أين تحصل على المفاتيح، ويحتوي على روابط إلى cybqa.pesapal.com وpesapal.com. أدخل مفاتيح بيئة الاختبار ومفاتيح بيئة الإنتاج، كل منها في حقله الخاص.

Sandbox mode: Use the Pesapal sandbox (no real money). عند التفعيل تُجرى المدفوعات الجديدة عبر cybqa.pesapal.com بمفاتيح الاختبار. ألغِ التفعيل لقبول مدفوعات حقيقية عبر pay.pesapal.com بمفاتيح الإنتاج. الافتراضي: مفعّل.

Sandbox consumer key: مفتاح المستهلك لحساب التاجر التجريبي (demo) لديك. يُستخدم فقط في وضع الاختبار.

Sandbox consumer secret: سرّ المستهلك لحساب تاجر الاختبار لديك. يُستخدم فقط في وضع الاختبار.

Live consumer key: مفتاح المستهلك من لوحة تحكم التاجر لدى Pesapal. يُستخدم عندما يكون وضع الاختبار معطّلًا.

Live consumer secret: سرّ المستهلك من لوحة تحكم التاجر لدى Pesapal. يُستخدم عندما يكون وضع الاختبار معطّلًا.

لا تُعرض المفاتيح والأسرار المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها.

Clear saved consumer keys and secrets: ضع علامة في المربع وانقر على Save لحذف المفاتيح والأسرار الأربعة المحفوظة جميعها.

يؤدي حفظ الإعدادات إلى إلغاء رموز الوصول المخزّنة مؤقتًا من Pesapal. لا يعيد تبديل الوضع أو تغيير المفاتيح استخدام رمز وصول أو معرّف إشعار يخص الوضع أو المفاتيح الأخرى أبدًا. يُتحقق من الدفع الذي بدأ في وضع ما دائمًا في ذلك الوضع، حتى بعد التبديل.

إشعارات الدفع (IPN)

IPN URL: يعرض عنوان URL لإشعارات متجرك. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_pesapal_pay/webhook، وقد يتضمن رمز لغة مثل /en/. يُسجَّل هذا العنوان لدى Pesapal تلقائيًا عند أول دفعة، بشكل منفصل لبيئتي الاختبار والإنتاج ولكل زوج من المفاتيح، ولذلك لا يلزم إعداد شيء. بعد أول دفعة يعرض القسم Registered IPN ID: مع المعرّف الذي أعادته Pesapal؛ وقبل ذلك يعرض Not registered yet for the current mode and keys. يجب أن يكون هذا العنوان متاحًا من الإنترنت: لا جدار حماية ولا حماية بكلمة مرور أمامه. يواصل العمل أثناء وضع الصيانة للمتجر، ولا تحجبه قيود الدول الخاصة بمتجرك.

متقدم

Debug log: Log Pesapal requests and notifications. يكتب التفاصيل في logs/pesapal_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون المفتاح معطّلًا. لا تُسجَّل المفاتيح والرموز وبيانات العملاء أبدًا. الافتراضي: معطّل.

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

Delete data: Delete the module settings and logs when the module is uninstalled. بيانات Pesapal المحفوظة في الطلبات (معرّفات التتبع والملاحظات) جزء من سجل المدفوعات، ولذلك تُحفظ دائمًا. تعطيل الوحدة لا يحذف شيئًا. الافتراضي: معطّل.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Pesapal (M-Pesa, Airtel Money, cards)) ويرى وصفها. بعد التأكيد تنشئ الوحدة طلب دفع لدى Pesapal بإجمالي السلة وبعملة السلة، مع بيانات الفوترة من عنوان الفاتورة، ثم تنقل العميل إلى صفحة الدفع الخاصة بـ Pesapal. وصف الدفع المرسل إلى Pesapal هو Cart ورقم السلة واسم المتجر. هناك يدفع العميل بإحدى الطرق التي تقدمها Pesapal، مثل M-Pesa أو Airtel Money أو MTN أو البطاقة أو التحويل البنكي. لا يوجد طلب في هذه المرحلة.

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

قد تستغرق المدفوعات عبر المال المتنقل بعض الوقت. إذا لم تؤكد Pesapal الدفع عند عودة العميل، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. مع الزرين Check again وBack to checkout. يُنشئ إشعار Pesapal الطلب فور تأكيد الدفع. إذا وُضع الطلب قيد الانتظار، تعرض صفحة التأكيد الرسالة Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

إذا ألغى العميل في صفحة Pesapal، يعود إلى الدفع مع الرسالة The Pesapal payment was cancelled. You can try again or choose another payment method. وإذا فشل الدفع فالرسالة هي The Pesapal payment was not successful. Please try again or choose another payment method. تبقى السلة محفوظة ويمكن للعميل الدفع مرة أخرى. تُسجَّل كل محاولة دفع للسلة، لذلك يُقبل الدفع الذي يتم لاحقًا في صفحة Pesapal أقدم لنفس السلة.

إذا تعذّر على Pesapal بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، على سبيل المثال Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method.، أو Pesapal is not available at the moment. Please choose another payment method. (مفاتيح خاطئة)، أو Pesapal could not start the payment: متبوعةً بالسبب الذي أعادته Pesapal. يُكتب السبب التقني في السجل. يجب أن يكون إجمالي الطلب أكبر من صفر.

لا تحتوي الوحدة على نموذج دفع في موقعك الخاص (يدفع العميل دائمًا في صفحة Pesapal)، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا تحويل للعملات.

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

حالات الطلب

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

Payment accepted: تُبلغ Pesapal بأن الدفع مكتمل، ويتطابق المبلغ والعملة. يُسجَّل الدفع بمعرّف تتبع Pesapal بوصفه معرّف المعاملة، وتعرض ملاحظة المبلغ وطريقة الدفع ورمز تأكيد Pesapal ومعرّف التتبع. يُطبَّق كل دفع مرة واحدة فقط.

Pesapal payment on hold: المبلغ أو العملة المدفوعة يختلفان عن السلة (ملاحظة Pesapal amount/currency mismatch — held for review)، أو وصلت أموال لطلب سبق إلغاؤه. يُسجَّل المبلغ المدفوع فعليًا على الطلب عندما يكون بعملة الطلب. تحقق من الدفع في لوحة Pesapal، ثم أكمل الطلب أو استرد الدفع.

Refunded: تُبلغ Pesapal بأن الدفع الذي سدّد الطلب قد عُكس. عكس محاولة أخرى يُسجَّل في الطلب فقط.

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

كتلة الدفع عبر Pesapal

تعرض صفحة الطلب كتلة Pesapal payment مع شارة Sandbox أو Live، ومعرّف التتبع، ومرجع التاجر، وحالة Pesapal، وطريقة الدفع، ورمز التأكيد، والمبلغ المطلوب والمبلغ المدفوع، وسبب المراجعة، وكل Payment attempts للسلة، وPayment notes للطلب. الكتلة للقراءة فقط.

المرتجعات والاسترداد

لا ترسل الوحدة عمليات استرداد إلى Pesapal. استرد الدفع من لوحة Pesapal، ثم سجّل الاسترداد يدويًا في PrestaShop.

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

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

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

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

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

لا تظهر Pesapal في الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاح المستهلك وسرّه للوضع الحالي مُدخلان (Sandbox consumer key وSandbox consumer secret في وضع الاختبار، وLive consumer key وLive consumer secret في وضع الإنتاج)، وأن عملة السلة هي KES أو UGX أو TZS أو ZMW أو RWF أو USD. تحدد التحذيرات أعلى الإعدادات المشكلة. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل. يمكن للمطورين تغيير قائمة العملات عبر الخطاف actionPesapalSupportedCurrencies.

تمت عملية الدفع لكن لم يُنشأ أي طلب: لم يصل إشعار Pesapal إلى متجرك ولم يعد العميل. تحقق من أن عنوان URL المعروض في IPN URL متاح من الإنترنت (لا جدار حماية ولا حماية بكلمة مرور أمامه). فعّل Debug log وراجع حقل Log في صفحة الوحدة.

كيف يرد المتجر على الإشعارات: يُرد على الإشعار المعالج بالرمز HTTP 200. وإذا لم تستطع الوحدة معالجته ترد بخطأ، فتعيد Pesapal إرسال الإشعار لاحقًا: 400 (معرّف التتبع مفقود أو غير صالح)، 404 (لا توجد سلة في هذا المتجر تحمل معرّف التتبع هذا)، 409 (المعاملة تخص مرجع تاجر آخر؛ لا يتغير شيء)، 502 (تعذّر الوصول إلى واجهة Pesapal API في تلك اللحظة، أو مفاتيح الوضع الذي بدأ فيه الدفع مفقودة)، و503 (كانت السلة تُحدَّث بعودة العميل في اللحظة نفسها، أو تعذّر إنشاء الطلب، مثلًا لأن الوحدة معطّلة).

يرى العميل الرسالة Pesapal is not available at the moment: رفضت Pesapal مفتاح المستهلك أو سرّه للوضع الحالي. تحقق من أن المفاتيح تطابق الوضع: مفاتيح الاختبار تعمل في وضع الاختبار فقط، ومفاتيح الإنتاج في وضع الإنتاج فقط. يعرض السجل خطأ Pesapal.

يرى العميل الرسالة Pesapal is temporarily unavailable: تعذّر الوصول إلى Pesapal، أو تعذّر تسجيل عنوان URL للإشعارات. اقرأ السجل وأعد المحاولة.

لا تُؤكَّد مدفوعات الوضع السابق بعد التبديل: يُتحقق من الدفع بمفاتيح الوضع الذي بدأ فيه. أبقِ مفاتيح ذلك الوضع مُدخلة حتى تُؤكَّد مدفوعاته.

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

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

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

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