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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

حساب 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). جميع المدفوعات حقيقية.

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

التثبيت

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

2. انقر Activate.

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

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

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

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

7. فعّل Enable/Disable. يُرسل رابط استدعاء الرد إلى Hubtel مع كل عملية دفع، لذا لا يلزم إعداد أي شيء في لوحة تحكم Hubtel.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Hubtel. أعلى الحقول، تحذرك الصفحة عند فقدان API ID أو API Key أو رقم حساب التاجر، وعندما لا تكون عملة المتجر GHS. في كلتا الحالتين تُخفى Hubtel عند الدفع. كما تحذرك عندما يستخدم المتجر أكثر من منزلتين عشريتين. وفي قائمة طرق الدفع، تُعلَّم البوابة بأنها تحتاج إلى إعداد حتى تُملأ بيانات الاعتماد.

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

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

Description: النص الذي يظهر تحت طريقة الدفع في صفحة الدفع. الافتراضي: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

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

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

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

API Key (Client Secret): المفتاح API Key لمفاتيحك القابلة للبرمجة من Hubtel. حافظ على سريته.

Merchant account number (POS Sales ID): تُحصَّل المدفوعات في حساب Hubtel هذا وتُفحص بناءً عليه.

تأكيد الدفع

يُخبر استدعاء الرد متجرك بأن دفعة قد تمت. يُرسل رابط استدعاء الرد المعروض في هذا القسم إلى Hubtel مع كل دفعة، لذا لا يلزم ضبط أي شيء في لوحة تحكم Hubtel. ويكون بالشكل https://your-site/wc-api/hubtel_pay/. ويجب أن يكون متاحًا للوصول عبر الإنترنت: دون وضع صيانة، أو حماية بكلمة مرور، أو جدار ناري يحظر Hubtel.

استدعاءات رد Hubtel ليست موقَّعة. تأخذ الإضافة مرجع الدفع فقط من استدعاء الرد؛ ويجب أن يخص المرجع طلبًا في متجرك. وتأتي الحالة والمبلغ ومعرّف المعاملة دائمًا من واجهة Hubtel Transaction Status API. يُعلَّم الطلب كمدفوع فقط بعد أن تؤكد تلك الواجهة الدفعة ومبلغها. وإذا تعذر الاتصال بـ Hubtel، يُعاد فحص الدفع تلقائيًا في الخلفية، ويمكنك فحصه من شاشة الطلب عبر Order actions > Check Hubtel payment status.

متقدم

Debug log: Log API calls and callbacks إلى WooCommerce > Status > Logs، المصدر wcp_hubtel_pay، دون مفاتيح أو بيانات عملاء. تُسجَّل الأخطاء دائمًا. الافتراضي: إيقاف.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). الافتراضي: إيقاف.

صفحة الدفع

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

بعد الدفع، يعود العميل إلى صفحة استلام الطلب. يُعلَّم الطلب كمدفوع فقط بعد أن تؤكده Hubtel عبر Transaction Status API: سواء عبر استدعاء الرد، أو الفحص الذي يتم عند عودة العميل، أو فحص الخلفية، أو إجراء الطلب. إذا وصل استدعاء الرد وعودة العميل في نفس اللحظة، فتتم معالجتهما واحدًا تلو الآخر، وبذلك لا يكتمل الطلب مرتين أبدًا. إذا لم تكن Hubtel قد أكدت الدفع بعد، تعرض الصفحة 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. وإذا وُضع الطلب في حالة «قيد الانتظار»، فإنها تعرض Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

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

إذا لم تتمكن Hubtel من بدء عملية الدفع، يرى العميل رسالة قصيرة، مثل 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. وتنتقل التفاصيل إلى السجل.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

الطلبات

حالات الطلب

Pending payment: تم توجيه العميل إلى Hubtel ولم يدفع بعد، أو لم تؤكد Hubtel الدفع بعد.

Processing: تم تأكيد الدفع. تنتقل الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى حالة «مكتمل»، وهو الإعداد الافتراضي في WooCommerce. تعرض ملاحظة الطلب المبلغ، ومعاملة Hubtel، وطريقة الدفع، والمرجع. ومعرّف المعاملة هو معرّف معاملة Hubtel.

On hold: أبلغت Hubtel عن مبلغ مدفوع يختلف عن إجمالي الطلب، أو أن الطلب ليس بعملة GHS (الملاحظة Hubtel amount/currency mismatch)؛ أو وصلت دفعة لطلب تم إلغاؤه بالفعل. لم يُعلَّم الطلب كمدفوع. تحقق من الدفعة في لوحة تحكم Hubtel وأكمل الطلب أو استرده يدويًا.

Failed: أبلغت Hubtel بفشل آخر محاولة دفع لطلب في حالة «في انتظار الدفع»، وتؤكد واجهة Transaction Status API أنه غير مدفوع. يمكن للعميل المحاولة مرة أخرى من الطلب. الفشل الذي يبلّغ عنه استدعاء الرد فقط لا يغيّر حالة الطلب أبدًا إلى فاشل.

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

فحوصات الدفع

بعد نحو 20 دقيقة من توجيه العميل إلى Hubtel، يستعلم فحص في الخلفية (WooCommerce Action Scheduler) من Hubtel عن الدفعة، في حال فُقد استدعاء الرد ولم يعد العميل. وتُفحص المحاولة غير المدفوعة مرة أخرى بعد ساعة. وعندما يتعذر الوصول إلى Hubtel API، يُعاد الفحص حتى 5 مرات بفواصل زمنية متزايدة.

يفحص إجراء الطلب Check Hubtel payment status أحدث محاولات للطلب (حتى 5، الأحدث أولًا)، ويطبق النتيجة ويضيف ملاحظة بحالة كل محاولة.

الاستردادات

الاستردادات من WooCommerce غير مدعومة. استرد الدفعة في لوحة تحكم Hubtel، ثم أنشئ استردادًا يدويًا في WooCommerce.

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

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

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

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

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

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

Hubtel لا تظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن API ID وAPI Key ورقم حساب التاجر قد تم ملؤها، وأن العملة هي GHS. في صفحة Pay for order تُعتمد عملة الطلب. تعرض صفحة الإعدادات تحذيرًا عند وجود خطأ في بيانات الاعتماد أو العملة.

تم الدفع ولكن الطلب ما زال في حالة «في انتظار الدفع»: تعذر تأكيد الدفع. افتح WooCommerce > Status > Logs، المصدر wcp_hubtel_pay. وجود HTTP 401 أو 403 في فحص الحالة يعني أن مفاتيح API غير صحيحة أو أن عنوان IP للخادم غير مدرج في القائمة البيضاء لدى Hubtel. تحقق أيضًا من إمكانية الوصول إلى رابط استدعاء الرد عبر الإنترنت. بعد إصلاح المشكلة، افتح الطلب وشغّل Order actions > Check Hubtel payment status. وتؤكد فحوصات الخلفية أيضًا الطلب بمجرد استجابة Hubtel.

استدعاء الرد يجيب بـ Unknown reference: لا يخص مرجع الدفع أي طلب في هذا المتجر.

استدعاء الرد يجيب بـ Payment status unavailable: تعذر الوصول إلى واجهة Transaction Status API أو أنها رفضت الطلب. يُعاد فحص الدفع في الخلفية.

الطلب في حالة «قيد الانتظار» مع ملاحظة عدم تطابق المبلغ/العملة: أبلغت Hubtel عن مبلغ مدفوع يختلف عن إجمالي الطلب، أو أن الطلب ليس بعملة GHS. تحقق من الدفعة في لوحة تحكم Hubtel وأكمل الطلب أو استرده يدويًا.

يرى العميل خطأ عند إرسال الطلب: فعّل Debug log وراجع السجل. تؤدي مفاتيح API الخاطئة إلى Hubtel payments are not available at the moment. وتؤدي مشاكل الاتصال إلى Could not connect to Hubtel.

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

للمطورين: يغيّر الفلتر hubtel_p_icon أيقونة طريقة الدفع، ويغيّر hubtel_p_payment_description وصف الدفع في صفحة Hubtel (حتى 100 حرف).

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

عند إلغاء تفعيل الإضافة تُحفظ جميع البيانات؛ وتُلغى فقط فحوصات الدفع المعلقة في الخلفية. للإزالة، ألغِ التفعيل ثم احذفها من صفحة Plugins. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالة ترخيصها. أما إعدادات البوابة، وخيارات الإضافة الخاصة، وفحوصات الخلفية المعلقة، والسجلات فتُحذف فقط إذا كان Delete data on uninstall مفعّلًا. وإلا فإنها تبقى لإعادة التثبيت لاحقًا. وتُحفظ بيانات Hubtel المخزّنة في الطلبات دائمًا باعتبارها سجل مدفوعات. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات معاملاتها.

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