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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث مع إضافة cURL.

العملة: سيدي غاني (GHS) فقط. تُخفى طريقة الدفع في صفحة الدفع عندما لا تكون عملة الطلب GHS. أبقِ عدد المنازل العشرية لعملة GHS عند 2، لأن Hubtel تخصم بوحدات بيسيوا كاملة.

حساب Hubtel: حساب أعمال لدى Hubtel يحتوي على مفاتيح API (API ID وAPI Key) ورقم حساب التاجر (POS Sales ID). توجد المفاتيح في لوحة أعمال Hubtel على bo.hubtel.com ضمن Programmable keys.

القائمة البيضاء لعناوين IP: لا تستجيب Hubtel لواجهة Transaction Status API إلا من عناوين IP لخوادم مدرجة في القائمة البيضاء. اطلب من Hubtel (مدير حسابك أو support@hubtel.com) إضافة عنوان IP العام لخادم الويب لديك إلى القائمة البيضاء. وحتى ذلك الحين لا يمكن تأكيد المدفوعات، وتبقى الطلبات بدون حالة.

لا توجد بيئة اختبار: ليس لدى Hubtel بيئة اختبار عامة (sandbox). جميع المدفوعات حقيقية.

Cron: يُوصى بوجود مهمة cron على خادمك تستدعي عنوان cron الخاص بالإضافة كل 5 دقائق لفحوصات المدفوعات في الخلفية (انظر Configuration).

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل API ID وAPI Key ورقم حساب التاجر (POS Sales ID).

5. اطلب من دعم Hubtel إضافة IP خادمك إلى القائمة البيضاء لواجهة Transaction Status API.

6. أضف عنوان cron المعروض في قسم Payment confirmation إلى cron خادمك.

7. فعّل Enable/Disable وانقر على Save. يُرسل عنوان callback إلى Hubtel مع كل دفعة، لذلك لا حاجة إلى إعداد أي شيء في لوحة Hubtel.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص وبيانات اعتماد Hubtel وcron كما في الخطوات من 3 إلى 7 الخاصة بـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين، ويختلف فقط عنوانا callback وcron (انظر Payment confirmation).

تبدأ عملية التثبيت الجديدة مع إيقاف طريقة الدفع.

الإعدادات

تقع جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit. تُدرج الأقسام على اليسار؛ ويحفظ الزر Save أسفل القائمة الصفحة بأكملها. وفوق الإعدادات، تحذّرك الصفحة إذا كان الحقل API ID أو API Key أو رقم حساب التاجر فارغًا، وإذا لم تكن العملة الافتراضية للمتجر هي GHS. وفي الحالتين يُخفى Hubtel في صفحة الدفع. كما تحذّرك الصفحة إذا كانت عملة GHS تستخدم أكثر من منزلتين عشريتين (اضبطها في System > Localisation > Currencies). وإذا لم تكن لديك صلاحية تعديل الإضافة، فستعرض الصفحة الإعدادات لكنها لن تستطيع حفظها.

عند الحفظ، يجب ألّا يكون الحقل Title فارغًا ولا يتجاوز 128 حرفًا (Enter a title for the payment method (1 to 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total رقمًا أكبر من 0 أو يساويه، ويجب أن توجد المنطقة الجغرافية وحالات الطلبات؛ وإلا فلن يُحفظ شيء. وإذا فُعّلت طريقة الدفع دون بيانات الاعتماد، فستُحفظ الإعدادات مع تحذير.

Hubtel

Enable/Disable: يقوم Enable Hubtel payments بتفعيل طريقة الدفع أو إيقافها. الافتراضي: إيقاف.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Mobile Money or card (Hubtel). مطلوب.

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد، بجوار أيقونة Mobile Money والبطاقة. الافتراضي: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

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

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

Total: إجمالي الدفع في صفحة الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Hubtel. اتركه فارغًا إذا لم ترد حدًّا أدنى.

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

انسخ API ID وAPI Key من لوحة أعمال Hubtel: bo.hubtel.com > Programmable keys (يحتوي القسم على رابط مباشر إليها). رقم حساب التاجر هو POS Sales ID لحسابك في Hubtel. ويكرر القسم أيضًا تنبيه القائمة البيضاء لعناوين IP.

API ID (Client ID): معرّف API للمفاتيح القابلة للبرمجة في Hubtel.

API Key (Client Secret): مفتاح API للمفاتيح القابلة للبرمجة في Hubtel. احتفظ به سرًّا. لا يُعرض المفتاح المحفوظ مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف المفتاح المحفوظ، فعّل خيار Clear saved API Key أسفل الحقل، ثم انقر على Save.

رقم حساب التاجر (POS Sales ID): تُحصَّل المدفوعات في حساب Hubtel هذا وتُتحقق بالمقارنة معه.

تأكيد الدفع

Callback URL: يُخبر callback متجرك بأنه تم دفع مبلغ ما. يُرسل هذا العنوان إلى Hubtel مع كل دفعة، لذلك لا حاجة إلى إعداد أي شيء في لوحة Hubtel. وهو على الشكل https://your-store/index.php?route=extension/payment/wcp_hubtel_pay/callback في OpenCart 3، وعلى الشكل https://your-store/index.php?route=extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.callback في OpenCart 4. ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك. يجب أن يكون متاحًا من الإنترنت: لا حماية بكلمة مرور ولا جدار حماية يمنع Hubtel. ويعمل callback أيضًا والمتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة على OpenCart 4 حدث بدء تشغيل (startup action) يسمح بمرور callback وعنوان cron وعودة العميل من Hubtel.

لا تكون callbacks الخاصة بـ Hubtel موقّعة. تأخذ الإضافة من callback مرجع الدفع فقط؛ ويجب أن ينتمي هذا المرجع إلى دفعة في متجرك. وتأتي الحالة والمبلغ ومعرّف المعاملة دائمًا من واجهة Transaction Status API الخاصة بـ Hubtel. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد هذه الواجهة الدفعة ومبلغها.

فحوصات الدفع في الخلفية (cron): عنوان cron مع رمز سري يُنشأ عند تثبيت الإضافة. استدعِه كل 5 دقائق من cron خادمك، مثلًا باستخدام curl. ثم تُعاد تلقائيًا مراجعة المدفوعات غير المؤكدة مع Hubtel: بعد 20 دقيقة من إرسال العميل إلى Hubtel، ومرة أخرى بعد ساعة إذا كانت الدفعة لا تزال غير مدفوعة، وحتى 5 مرات بفواصل زمنية متزايدة إذا تعذّر الوصول إلى Hubtel. وفي OpenCart 4 يكون مسار عنوان cron هو extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.cron بدلًا من extension/payment/wcp_hubtel_pay/cron؛ انسخه تمامًا كما تعرضه الإعدادات. أبقِ العنوان سريًّا. يستجيب العنوان بسطر قصير مثل OK checked=0.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود)، ولا يحصل الطلب على حالة إلا بعد أن تؤكد Hubtel الدفع. يسرد كل حقل أدناه حالات الطلبات الخاصة بـ OpenCart.

Order status after payment: الحالة التي تُضبط بعد أن تؤكد Hubtel دفع المبلغ الدقيق للطلب بعملة GHS. الافتراضي: Processing.

Hubtel payment on hold status: الحالة التي تُضبط عندما تُبلّغ Hubtel عن مبلغ مدفوع يختلف عن إجمالي الطلب، أو عندما لا يكون الطلب بعملة GHS. وتوضح ملاحظة في سجل الطلب ذلك. الافتراضي: Pending، لأن OpenCart لا يحتوي على حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

متقدم

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

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

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

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

Export: يحفظ Download JSON الإعدادات في ملف JSON. لا يُصدَّر مفتاح API.

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

صفحة الدفع

في خطوة Payment Method، يختار العميل طريقة الدفع (افتراضيًا Mobile Money or card (Hubtel)). وفي خطوة Confirm Order، يرى العميل الأيقونة ووصفك. وينشئ OpenCart الطلب في هذه الخطوة، ولكن بدون حالة بعد. عندما ينقر العميل على Confirm Order، تنشئ الإضافة جلسة دفع في Hubtel بإجمالي الطلب بعملة GHS وترسل العميل إلى صفحة الدفع الخاصة بـ Hubtel. وهناك يظهر الدفع بالعبارة Order # ورقم الطلب واسم متجرك. وفي صفحة Hubtel يدفع العميل عبر MTN MoMo أو Telecel Cash أو AirtelTigo Money أو بطاقة Visa أو Mastercard أو GhQR. ويُنشئ كل نقرة على Confirm Order محاولة دفع جديدة برقم مرجعي خاص بها، وتبقى صفحات Hubtel القديمة قابلة للدفع.

في OpenCart 4 يختار العميل طريقة الدفع بالزر Choose في كتلة طريقة الدفع، وذلك في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

بعد الدفع، يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Hubtel عبر واجهة Transaction Status API: من خلال callback، أو من خلال الفحص الذي يجري عند عودة العميل، أو من خلال فحص في الخلفية، أو من خلال زر في صفحة الطلب. ويُعالَج callback وعودة العميل إذا وصلا في اللحظة نفسها واحدًا تلو الآخر، لذلك لا يُطبَّق الدفع مرتين أبدًا. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وإذا وُضع الطلب قيد الانتظار، تعرض الصفحة Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

إذا لم تكن Hubtel قد أكدت الدفع عند عودة العميل، تعرض صفحة Payment confirmation النص We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. مع الزرين Check again وBack to checkout. ويحصل الطلب على حالته بمجرد أن تؤكد Hubtel الدفع. وإذا كانت Hubtel قد أبلغت بالفعل أن محاولة الدفع هذه فشلت، يعود العميل إلى صفحة الدفع مع الرسالة The Hubtel payment was not completed. You can try again or choose another payment method. وتُحفظ السلة، ويبقى الطلب بدون حالة.

إذا ضغط العميل على Cancel في صفحة Hubtel، تتحقق الإضافة أولًا مما إذا كان الدفع قد تم رغم ذلك. وإذا لم يتم، يعود العميل إلى صفحة الدفع مع الرسالة The Hubtel payment was cancelled. You can try again or choose another payment method. وتُحفظ السلة. ولا يزال الدفع اللاحق عبر صفحة Hubtel الملغاة مقبولًا.

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

يبقى OpenCart 4 الطلب في صفحة الدفع حتى تُعرض صفحة النجاح. وإذا أُغلق ذلك الطلب دون دفع في الأثناء (مثلًا لأنك ألغيته)، يعود العميل إلى صفحة الدفع مع الرسالة The Hubtel payment was not completed. You can try again or choose another payment method.، ويدفع النقر التالي على Confirm Order طلبًا جديدًا. وإذا كان الطلب مدفوعًا بالفعل وصارت السلة تحتوي على شراء جديد، فإن Confirm Order يعيد تحميل صفحة الدفع، ويدفع النقر التالي على Confirm Order طلبًا جديدًا. ولا يُعرض الطلب المدفوع أبدًا كمدفوع لسلة أخرى.

إذا تعذّر على Hubtel بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل Could not connect to Hubtel. Please try again in a moment.، أو Hubtel could not start the payment. Please try again or choose another payment method.، أو عند خطأ في بيانات الاعتماد، Hubtel payments are not available at the moment. Please choose another payment method. وتُرسل التفاصيل إلى السجل.

لا تتضمن الإضافة استردادات من OpenCart، ولا اشتراكات، ولا بطاقات محفوظة، ولا اختيارًا لقناة الدفع داخل المتجر.

الطلبات

حالات الطلب

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

Order status after payment (الافتراضي Processing): تم تأكيد الدفع للمبلغ الدقيق للطلب بعملة GHS. تعرض ملاحظة المبلغ ومعاملة Hubtel وطريقة الدفع والمرجع.

Hubtel payment on hold status (الافتراضي Pending): أبلغت Hubtel عن مبلغ مدفوع يختلف عن إجمالي الطلب، أو لا يكون الطلب بعملة GHS. لم يُعلَّم الطلب كمدفوع، وتوضح ملاحظة سبب عدم التطابق. تحقق من الدفع في لوحة Hubtel ثم نفّذ الطلب أو استرده يدويًا. وإذا دُفعت لاحقًا محاولة أخرى للطلب نفسه بالمبلغ الصحيح، ينتقل الطلب إلى Order status after payment.

وإذا دُفعت أيضًا محاولة أخرى لطلب مدفوع بالفعل، أو دُفع طلب آخر من سلة مدفوعة بالفعل، فلن يتغير الطلب المدفوع. وتطلب منك ملاحظة استرداد النسخة المكررة من لوحة Hubtel. ويُضيف الدفع لطلب نقلته إلى حالة أخرى (مثل ملغى) ملاحظة، ولا يُعاد فتح الطلب تلقائيًا أبدًا. وعندما تُبلّغ Hubtel بأن دفعة قد استُردت، تُضاف ملاحظة إلى الطلب.

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

تبويب VibeFox Hubtel Pay Gateway

في Sales > Orders افتح طلبًا دُفع عبر Hubtel. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Hubtel Pay Gateway قائمة Hubtel payment attempts للطلب: التاريخ والمرجع وجلسة Hubtel للدفع والمبلغ والحالة في Hubtel والمعاملة والنتيجة. وأسفل المحاولات تُدرج Hubtel notes الخاصة بالطلب، الأحدث أولًا. ويظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

يتحقق الزر Check Hubtel payment status من أحدث محاولات الطلب (حتى 5، الأحدث أولًا، ويتوقف بمجرد دفع الطلب)، ويطبّق النتيجة، ويضيف ملاحظة بحالة كل محاولة. وتظهر النتيجة في التبويب. وتحتاج إلى صلاحية تعديل الطلبات (Sales > Orders، وتُضبط في System > Users > User Groups). ويعمل الزر أيضًا للطلب بدون حالة. والحالة التي يضبطها هذا الزر تُكتب مباشرة دون رسائل البريد الإلكتروني للطلب أو تحديث المخزون؛ أما callback وعودة العميل وcron فتضبطها بالطريقة المعتادة.

الاستردادات

لا تُدعم الاستردادات من OpenCart. استرد الدفعة في لوحة Hubtel، ثم سجّل الاسترداد في OpenCart. ولا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Hubtel.

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

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

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

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

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

لا يظهر Hubtel في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن حقول API ID وAPI Key ورقم حساب التاجر مملوءة، وأن عملة الطلب هي GHS. وتحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المحدد في الإعدادات. وتعرض صفحة الإعدادات تحذيرًا عندما تكون بيانات الاعتماد أو العملة خاطئة.

تم الدفع، لكن الطلب يبقى بدون حالة: تعذّر تأكيد الدفع. فعّل Debug log وانظر إلى الحقل Log في صفحة الإضافة. ويعني HTTP 401 أو 403 في فحص الحالة أن مفاتيح API خاطئة أو أن IP الخادم غير مُدرج في القائمة البيضاء من قِبل Hubtel. وتحقق أيضًا من أن عنوان callback متاح من الإنترنت وأن عنوان cron يُستدعى. وبمجرد أن ترد Hubtel، يضبط callback التالي أو الفحص في الخلفية أو عودة العميل أو Check Hubtel payment status حالة الطلب.

يُجيب callback بـ Unknown reference: مرجع الدفع لا ينتمي إلى دفعة لهذا المتجر.

يُجيب callback بـ Payment status unavailable: تعذّر الوصول إلى Transaction Status API أو رفضت الطلب، أو كانت السلة تُؤكَّد بطلب آخر في اللحظة نفسها. تُعاد مراجعة الدفعة في الخلفية بعد 5 دقائق.

يُجيب callback بـ Gateway not configured: أحد الحقول API ID أو API Key أو رقم حساب التاجر مفقود. أكمله؛ وستُراجع الدفعة في الخلفية.

يُجيب callback بـ Invalid request أو Invalid ClientReference: الطلب لم يحتوِ على callback صالح من Hubtel.

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

يُجيب عنوان cron بـ Forbidden: الرمز في العنوان خاطئ. انسخ عنوان cron تمامًا كما تعرضه الإعدادات. وبعد إعادة التثبيت مع تفعيل Delete data on uninstall يكون الرمز جديدًا.

الطلب في حالة الانتظار: اقرأ الملاحظات في تبويب VibeFox Hubtel Pay Gateway (انظر حالات الطلب)، وتحقق من الدفع في لوحة Hubtel، ثم نفّذ الطلب أو استرده يدويًا.

يرى العميل خطأً بعد Confirm Order: فعّل Debug log وراجع السجل. وتعني مفاتيح API الخاطئة الرسالة Hubtel payments are not available at the moment. وتعني مشكلة الاتصال الرسالة Could not connect to Hubtel. ويعني طلب بعملة أخرى الرسالة Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method. أما This payment method is not available. Please reload the checkout page. فتعني أن صفحة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع قد أُوقفت في الأثناء.

للمطورين: حدث OpenCart الخاص wcp_hubtel_pay_icon يغيّر أيقونة طريقة الدفع، وwcp_hubtel_pay_payment_description يغيّر وصف الدفع في صفحة Hubtel.

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

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

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

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