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

المتطلبات

WordPress: 6.2 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. ترفض الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل مفتاح المستهلك وسره لبيئة الاختبار، وشغّل Enable/Disable، واحفظ، ثم قدّم طلبًا تجريبيًا.

6. أدخل مفتاح المستهلك وسره لبيئة الإنتاج، وأزل تحديد Sandbox mode، واحفظ لقبول مدفوعات حقيقية.

التهيئة

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Pesapal. تعرض شارة فوق الحقول الوضع: 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 كوضع اختبار ما دامت بيئة الاختبار مشغّلة.

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

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

الدفع

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: مفتاح المستهلك لحساب التاجر في بيئة الاختبار (التجريبي). يُستخدم في وضع الاختبار فقط.

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

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

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

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

إعدادات متقدمة

Debug log: يكتب Log Pesapal requests and notifications التفاصيل في WooCommerce > Status > Logs، بالمصدر wcp_pesapal_pay. تُسجَّل الأخطاء والتحذيرات دائمًا. ولا تُسجَّل المفاتيح أو رموز الوصول أو بيانات العملاء أبدًا. الافتراضي: متوقف.

Delete data: Delete the plugin settings and logs when the plugin is deleted. بيانات Pesapal المحفوظة في الطلبات (معرّفات التتبع والملاحظات) هي سجل المدفوعات وتُحفَظ دائمًا. لا يؤدي تعطيل الإضافة إلى حذف أي شيء. الافتراضي: متوقف.

الدفع

يختار العميل وسيلة الدفع (افتراضيًا Pesapal (M-Pesa, Airtel Money, cards)) ويقدّم الطلب. في وضع الاختبار، تعرض كتلة Checkout الرسالة Sandbox mode: no real money will be charged. تنشئ الإضافة طلب دفع لدى Pesapal بإجمالي الطلب وبعملة الطلب، مع بيانات الفوترة الخاصة به، وتضيف ملاحظة للطلب تحتوي على الوضع والمبلغ ومعرّف تتبع Pesapal. يُنقل العميل إلى صفحة الدفع لدى Pesapal ويدفع بإحدى وسائلها، مثل M-Pesa أو Airtel Money أو MTN أو البطاقة أو البنك.

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

بعد الدفع، يعود العميل إلى صفحة استلام الطلب. قد تستغرق مدفوعات الأموال عبر الهاتف المحمول بعض الوقت. إذا لم يُؤكَّد الدفع بعد، تعرض الصفحة 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. ويُكمل إشعار Pesapal الطلب لاحقًا. وإذا وُضع الطلب قيد الانتظار، تعرض الصفحة Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

إذا ألغى العميل في صفحة Pesapal، يعود إلى صفحة Pay for order مع 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. تُسجَّل التفاصيل التقنية في ملاحظات الطلب والسجل. يجب أن يكون إجمالي الطلب أكبر من الصفر.

تعمل وسيلة الدفع في صفحة الدفع الكلاسيكية، وكتلة Checkout، وصفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce ‏(HPOS).

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

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

حالات الطلبات

Pending payment: نُقل العميل إلى Pesapal ولم يدفع بعد، أو لم تؤكد Pesapal الدفع بعد.

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

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

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

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

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

الاستردادات

لا ترسل الإضافة استردادات إلى Pesapal. نفّذ الاسترداد في لوحة تحكم Pesapal، ثم سجّله يدويًا في WooCommerce.

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

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

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

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

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

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

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

نجح الدفع لكن الطلب لا يزال بانتظار الدفع: لم يصل إشعار Pesapal إلى متجرك ولم يعد العميل. تحقّق من أن عنوان URL المعروض في Payment notifications (IPN) متاح من الإنترنت (دون وضع صيانة أو جدار حماية أو حماية بكلمة مرور أمام /wc-api/pesapal_pay/). راجع WooCommerce > Status > Logs، بالمصدر wcp_pesapal_pay.

كيفية رد المتجر على الإشعارات: يُرد على الإشعار الذي تمت معالجته برمز 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، ثم عالج الطلب أو استرد الدفعة.

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

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

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

Pesapal علامة تجارية لمالكها المعني. هذه الإضافة غير تابعة لـ Pesapal ولا معتمدة منها.