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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على الإصدار 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على حزم الإصدارين من OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt وحزمة OpenCart 3 wcp_pesapal_pay-oc3-(version).ocmod.zip وحزمة OpenCart 4 wcp_pesapal_pay.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_pesapal_pay-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذا لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت، يمكنك نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Pesapal Pay Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

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

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_pesapal_pay.ocmod.zip. لا تُغيّر اسم الملف: يستمد OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي يُعاد تسميتها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (الزر الأخضر +) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Pesapal Pay Gateway، وانقر على Install (الزر الأخضر +)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح Pesapal كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو عنوان IPN (راجع Payment notifications).

تبدأ عملية التثبيت الجديدة بطريقة الدفع معطّلة ووضع بيئة الاختبار مفعّلًا.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit. تُدرج الأقسام على اليسار، وزر Save أسفل القائمة يحفظ الصفحة كاملةً. وفوق الإعدادات تظهر شارة توضح الوضع: SANDBOX — دفعات تجريبية على cybqa.pesapal.com — لا يُخصم أي مبلغ حقيقي. أو LIVE — دفعات حقيقية على pay.pesapal.com. يظهر تحذير عند غياب مفاتيح الوضع الحالي (أدخل مفتاح المستهلك والسر الخاص ببيئة الاختبار — حتى ذلك الحين لن يظهر Pesapal في صفحة الدفع.، أو الرسالة نفسها للإنتاج)، وعندما لا يدعم Pesapal العملة الافتراضية لمتجرك. ومن دون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا يُقبل حقل Title فارغًا: يُحتفظ بالعنوان السابق مع رسالة خطأ، وتُحفظ الحقول الأخرى. يجب أن يكون Sort Order عددًا صحيحًا (القيم السالبة مسموحة)، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن يكون Geo Zone وحالات الطلب موجودة؛ وإلا فإن الحقل يحتفظ بقيمته السابقة مع رسالة خطأ. يؤدي الحفظ إلى حذف رموز الوصول المخزنة مؤقتًا لـ Pesapal.

Pesapal

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

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

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

Sort Order: موقع Pesapal بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Pesapal فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي سلة الشراء، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب حتى يُعرض Pesapal. اتركه فارغًا لعرض Pesapal مهما كان المبلغ.

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

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

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

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

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

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

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

حالات الطلب

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تُبلغ Pesapal بأن الدفع «Completed». يعرض كل حقل أدناه حالات طلبات OpenCart لديك.

Order Status After Payment: الحالة التي تُعيَّن عندما تؤكد Pesapal الدفع. الافتراضي: Processing.

Pesapal Payment On Hold Status: الدفعات التي لا يتطابق مبلغها أو عملتها مع الطلب، والدفعات الواردة بعد إلغاء الطلب. توضح ملاحظة السبب. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Cancelled Order Status: الدفعة الواردة من Pesapal لطلب في هذه الحالة (أو في حالة الاسترداد) تضع الطلب في حالة انتظار بدلًا من إعادة فتحه بصمت. الافتراضي: Canceled.

Refunded Status: تُعيَّن عندما تُبلغ Pesapal بأن دفعة الطلب قد أُلغيت. الافتراضي: Refunded.

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

IPN URL: يعرض عنوان URL لإشعارات متجرك. يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_pesapal_pay/ipn في OpenCart 3، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_pesapal_pay/payment/wcp_pesapal_pay.ipn. ويُنشأ من عنوان الواجهة الأمامية لتثبيت OpenCart لديك. يُسجَّل هذا العنوان لدى Pesapal تلقائيًا عند أول دفعة، بشكل منفصل لبيئة الاختبار والإنتاج ولكل مفتاح مستهلك، لذلك لا يوجد ما يتطلب الإعداد. وبعد الدفعة الأولى يعرض القسم Registered IPN ID: مع المعرّف الذي أعادته Pesapal؛ وقبل ذلك يقول لم يُسجَّل بعد للوضع والمفاتيح الحالية. يجب أن يكون عنوان URL متاحًا من الإنترنت: لا جدار حماية ولا حماية بكلمة مرور أمامه. ويستمر عمله أثناء وضع الصيانة للمتجر، لأن OpenCart يسمح بمرور طلبات إضافات الدفع (في OpenCart 4 تضيف الإضافة إجراء بدء التشغيل الخاص بها لهذا الغرض، وهو يسمح أيضًا بعودة العميل من Pesapal).

متقدم

Debug log: يسجّل طلبات Pesapal وإشعاراتها في الملف pesapal_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى pesapal_p_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون المفتاح معطّلًا. لا تُسجَّل المفاتيح ولا الرموز ولا بيانات العملاء أبدًا. الافتراضي: معطّل.

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

Delete data: يحذف إعدادات الإضافة والسجلات عند إلغاء تثبيتها. أما بيانات Pesapal المحفوظة في الطلبات (معرّفات التتبع والملاحظات) فهي جزء من سجل المدفوعات وتُحتفظ بها دائمًا. لا يحذف تعطيل الإضافة أي شيء. الافتراضي: معطّل.

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر مفاتيح المستهلك وأسراره.

Import: ألصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى مفاتيح المستهلك وأسراره المحفوظة كما هي.

صفحة الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Pesapal (M-Pesa, Airtel Money, cards)). وفي خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة طلب دفع في Pesapal بإجمالي الطلب وبعملة الطلب، مع بيانات الفوترة من عنوان الدفع (وفي OpenCart 4، عندما لا يطلب الدفع عنوان دفع، من عنوان الشحن)، وتُوجّه العميل إلى صفحة دفع Pesapal. ووصف الدفعة المُرسل إلى Pesapal هو Order ورقم الطلب واسم المتجر. وهناك يدفع العميل بإحدى الطرق التي تقدمها Pesapal، مثل M-Pesa أو Airtel Money أو MTN أو البطاقة أو التحويل المصرفي. وتسجّل ملاحظة على الطلب طلب الدفع.

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

قد تستغرق مدفوعات الهاتف المحمول بعض الوقت. إذا لم تؤكد Pesapal الدفعة بعد عند عودة العميل، تظهر صفحة Payment confirmation تعرض تُؤكَّد دفعتك من Pesapal. ستصلك رسالة بريد إلكتروني فور تأكيدها — لا حاجة إلى الدفع مرة أخرى. مع الزرين Check again وBack to checkout. يعيّن إشعار Pesapal حالة الطلب بمجرد تأكيد الدفعة. وإذا وُضع الطلب في حالة الانتظار، تعرض صفحة النجاح: تم استلام دفعتك وتقوم المتجر بمراجعتها. ستصلك رسالة بريد إلكتروني بعد تأكيد الطلب. وعندما تنقل دفعة لاحقة الطلب من حالة الانتظار إلى حالة الدفع، يُبلَّغ العميل عبر البريد الإلكتروني.

إذا ألغى العميل الدفع في صفحة Pesapal، يعود إلى صفحة الدفع مع الرسالة تم إلغاء الدفع عبر Pesapal. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وإذا فشلت الدفعة، تكون الرسالة لم تنجح دفعة Pesapal. يُرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وتذكر ملاحظة على الطلب السبب. يبقى السلة محفوظة ويمكن للعميل الدفع مجددًا. وفي OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع. في OpenCart 3 ينشئ OpenCart طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، وفي OpenCart 4 يُحدَّث طلب الدفع، لذلك تتحقق الإضافة قبل أي دفعة جديدة من المحاولات السابقة للسلة لدى Pesapal: فإذا دُفعت إحداها في الأثناء، يحصل ذلك الطلب على حالته ويذهب العميل إلى صفحة النجاح دون أن يدفع مرتين. أما الدفعة التي تُجرى لاحقًا من صفحة Pesapal أقدم للسلة فتظل مقبولة. ويُعدّ أي تغيير في السلة، بما في ذلك الكمية الجديدة، سلةً جديدة تحتاج إلى دفعة خاصة بها.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تُعرض صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا عند إلغائه)، أو كان قد دُفع لسلة سابقة وتغيّرت السلة منذ ذلك الحين، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. وتدفع خطوة Confirm Order التالية طلبًا جديدًا. ولا يُعرض طلب مغلق أبدًا على أنه مدفوع.

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

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

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى Pesapal ولم يدفع، أو فشلت الدفعة، أو لم تؤكد Pesapal الدفع بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Order Status After Payment (الافتراضي Processing): تُبلغ Pesapal بأن الدفع «Completed»، ويطابق المبلغ والعملة الطلب. تعرض ملاحظة المبلغ وطريقة الدفع ورمز التأكيد من Pesapal ومعرّف التتبع. تُطبَّق كل دفعة مرة واحدة فقط.

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

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

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

الملاحظات هي إدخالات في History الخاص بالطلب، ولا يراها العميل.

VibeFox Pesapal Pay Gateway tab

في Sales > Orders افتح طلبًا دُفع عبر Pesapal. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Pesapal Pay Gateway معرّف التتبع مع الوسم Sandbox أو Live، ومرجع التاجر، وحالة Pesapal، وطريقة الدفع، ورمز التأكيد، والمبلغ المطلوب والمبلغ المدفوع، وسبب المراجعة، وجميع Payment attempts الخاصة بالطلب (عند وجود أكثر من محاولة)، وPayment notes. علامة التبويب للقراءة فقط، وتظهر للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

لا ترسل الإضافة استردادات إلى Pesapal. استرد الدفعة في لوحة Pesapal، ثم سجّل الاسترداد يدويًا في OpenCart. ولا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر Pesapal.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Pesapal Pay Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit، فوق الإعدادات. ألصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموَّهًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-payment-pesapal والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify على الإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (تشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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

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

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

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

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

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

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

يرى العميل الرسالة «This payment method is not available. Please reload the checkout page.»: لم تعد جلسة الدفع تطابق الطلب، أو أُوقفت طريقة الدفع في الأثناء. يعيد العميل تحميل صفحة الدفع.

يرى العميل الرسالة «We could not verify the Pesapal payment»: رابط العودة من Pesapal لم يطابق أي طلب في المتجر. وإذا خُصم مبلغ، فابحث عن الدفعة في لوحة Pesapal وراجع الطلب قبل أن يدفع العميل مرة أخرى.

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

الطلب في حالة الانتظار بعد الدفع: اقرأ الملاحظات في علامة التبويب VibeFox Pesapal Pay Gateway. فالمبلغ أو العملة المدفوعان اختلفا عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. تحقّق من الدفعة في لوحة Pesapal، ثم عالج الطلب أو استرد الدفعة.

للمطورين: تُطلق الإضافة أحداث OpenCart التالية: pesapal_p_supported_currencies (قائمة العملات) وpesapal_p_submit_order_payload (طلب الدفع قبل إرساله إلى Pesapal).

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، وانقر على Uninstall (الزر الأحمر −) بجوار VibeFox Pesapal Pay Gateway. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. ويحذف OpenCart إعدادات الإضافة الخاصة به دائمًا: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلب في قسم حالات الطلب، وتعود إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف دائمًا حدث OpenCart الخاص بالإضافة، ورموز الوصول المخزنة مؤقتًا لـ Pesapal، ومعرّفات الإشعارات المسجلة (وفي OpenCart 4 تُحذف أيضًا أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور الإشعارات وعودة العميل في وضع الصيانة). وإذا كان Delete data مفعّلًا، تُحذف الإعدادات الأخرى (العنوان والوصف ووضع بيئة الاختبار والمفاتيح ومفتاح سجل التصحيح) والسجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. تُحفظ محاولات الدفع في Pesapal دائمًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات التتبع الخاصة بـ Pesapal.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Pesapal Pay Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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