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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد cURL. ترفض الوحدة التثبيت بدونهما.

العملة: السيدي الغاني (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 دقائق لفحوصات الدفع في الخلفية (انظر الإعدادات).

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

التثبيت

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

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

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

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

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

6. أضف رابط cron المعروض في صفحة Configure إلى cron الخاص بخادمك.

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول تحذرك الصفحة عندما يكون API ID أو API Key أو رقم حساب التاجر مفقودًا، وعندما لا تكون العملة الافتراضية للمتجر GHS. وفي الحالتين تُخفى Hubtel في صفحة الدفع. كما تحذر عندما تستخدم عملة GHS أكثر من منزلتين عشريتين.

Hubtel

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Mobile Money or card (Hubtel). مطلوب: العنوان الفارغ يعطي الخطأ Enter a title for the payment method.

Description: النص الظاهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. ستُوجَّه إلى 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. أدخل قيمة جديدة فقط إذا أردت تغييره.

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

Clear saved API Key: ضع علامة في المربع وانقر على Save لإزالة API Key المحفوظ. الحقل الفارغ يُبقي القيمة المحفوظة.

تأكيد الدفع

Callback URL: يُخبر الرد (callback) متجرك بأن دفعة قد تمت. يُرسل هذا الرابط إلى Hubtel مع كل عملية دفع، لذلك لا حاجة لإعداد أي شيء في لوحة Hubtel. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_hubtel_pay/callback، وربما مع رمز اللغة. يجب أن يكون الرابط متاحًا من الإنترنت: لا حماية بكلمة مرور ولا جدار حماية يحجب Hubtel. يعمل الرد أيضًا أثناء وجود المتجر في وضع الصيانة، ولا يُحجب بقيد الدول الخاص بمتجرك.

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

فحوصات الدفع في الخلفية (cron): رابط cron مع رمز سري. استدعِه كل 5 دقائق من cron الخاص بخادمك، مثلاً باستخدام curl. تُعاد بعدها تلقائيًا مراجعة المدفوعات غير المؤكدة مع Hubtel: بعد 20 دقيقة من إرسال العميل إلى Hubtel، ومرة أخرى بعد ساعة إذا بقيت الدفعة غير مدفوعة، وحتى 5 مرات بفواصل متزايدة عندما يتعذر الوصول إلى Hubtel. احتفظ بالرابط سرًا.

متقدم

Debug log: يسجل استدعاءات API والردود في logs/hubtel_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح وبيانات العملاء. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون هذا الخيار معطّلًا. الافتراضي: معطّل.

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

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

صفحة الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Hubtel الدفع عبر Transaction Status API: عن طريق الرد، أو عبر الفحص الذي يُجرى عند عودة العميل، أو عبر فحص في الخلفية، أو عبر الزر في صفحة الطلب. يُعالج الرد وعودة العميل إذا وصلا في الوقت نفسه واحدًا تلو الآخر، لذلك لا يُنشأ الطلب مرتين أبدًا. ثم يرى العميل صفحة تأكيد الطلب المعتادة. إذا وُضع الطلب في الانتظار، تعرض الصفحة 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 الملغاة مقبولة.

إذا تعذّر على 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. تذهب التفاصيل إلى السجل.

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

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى Hubtel ولم يدفع، أو لم تؤكد Hubtel الدفع بعد. توجد السلة فقط.

Payment accepted: تم تأكيد الدفع لكامل إجمالي السلة بالضبط بعملة GHS. يُسجَّل الدفع مع معرّف معاملة Hubtel، وتعرض ملاحظة المبلغ ومعاملة Hubtel وطريقة الدفع والمرجع.

Hubtel payment on hold: أفادت Hubtel بمبلغ مدفوع يختلف عن إجمالي السلة، أو أن السلة ليست بعملة GHS. لم يُعلَّم الطلب كمدفوع؛ يُسجَّل المبلغ الذي حصّلته Hubtel فعليًا كدفعة، وتشرح ملاحظة سبب الاختلاف. تحقق من الدفعة في لوحة Hubtel ثم نفّذ الطلب أو استرده يدويًا. إذا دُفعت محاولة أخرى للسلة نفسها لاحقًا بالمبلغ الصحيح، ينتقل الطلب إلى Payment accepted.

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

كتلة الدفع في Hubtel

تعرض صفحة الطلب كتلة Hubtel payment تضم جميع محاولات الدفع لسلة الطلب: التاريخ والمرجع وصفحة Hubtel والمبلغ وحالة Hubtel والمعاملة والنتيجة. وتحت المحاولات تُدرج Hubtel notes الخاصة بالطلب، والأحدث أولًا.

يفحص الزر Check Hubtel payment status أحدث محاولات الطلب (حتى 5، الأحدث أولًا، ويتوقف بمجرد دفع الطلب)، ويطبّق النتيجة، ويضيف ملاحظة بحالة كل محاولة. تظهر النتيجة في الكتلة. تحتاج إلى صلاحية تعديل الطلبات؛ ولا تحتاج إلى الوصول إلى صفحات الوحدات. الزر متاح عندما يكون الطلب موجودًا. تُؤكَّد السلة المدفوعة دون طلب عبر الرد أو عودة العميل أو cron.

الاسترداد

الاسترداد من PrestaShop غير مدعوم. استرد الدفعة في لوحة Hubtel، ثم سجّل الاسترداد في PrestaShop. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترسل المال عبر Hubtel.

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

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

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

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

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

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

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

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

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

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

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

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

يرد رابط cron بـ Forbidden: الرمز في الرابط خاطئ. انسخ رابط cron تمامًا كما تعرضه الإعدادات.

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

يرى العميل خطأ عند اختيار Hubtel: فعّل 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.

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

الإزالة

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

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