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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث مع امتداد OpenSSL (يُستخدم لفك تشفير webhooks).

حساب HyperPay: تُصدر HyperPay الرمز Access Token والمعرّف Entity ID عند إعداد حساب التاجر لديك. بيانات الاعتماد الخاصة بالاختبار والإنتاج مختلفة. تحتاج أيضًا إلى webhook للدفع في لوحة تحكم HyperPay ومفتاح فك التشفير الخاص به (webhook key)، ويظهر ضمن Administration > Webhooks (انظر الإعداد).

بيانات البطاقة: تُدخل البطاقة في أداة HyperPay فقط، لذلك لا تمر بيانات البطاقة عبر خادمك أبدًا (PCI DSS SAQ A).

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل Access Token وEntity ID ومفتاح webhook الخاصة بالاختبار التي أصدرتها HyperPay، واترك Test Mode مفعّلًا.

5. في لوحة تحكم HyperPay (Administration > Webhooks)، أضف webhook للدفع باستخدام عنوان URL المعروض في قسم Webhook، وانسخ مفتاح فك التشفير الخاص به إلى حقل مفتاح webhook للوضع نفسه.

6. فعّل Enable/Disable، وانقر على Save، ثم أجرِ دفعة تجريبية ببطاقة اختبار من HyperPay. بعد ذلك أدخل بيانات الاعتماد الخاصة بالإنتاج، وأوقف Test Mode.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص وبيانات اعتماد HyperPay وwebhook كما في الخطوات من 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. يختلف عنوان URL الخاص بـ webhook فقط (انظر Webhook).

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox HyperPay Payment Gateway > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات تعرض الصفحة الرسالة Test mode is on: payments go to the HyperPay test system and no real money is charged. ما دام وضع الاختبار مفعّلًا. وتنبهك الصفحة عندما يكون Access Token أو Entity ID للوضع الحالي مفقودًا (وفي هذه الحالة لا تظهر طريقة الدفع في صفحة الدفع)، وعندما لا يحتوي الوضع الحالي على مفتاح webhook صالح (وفي هذه الحالة لا تُؤكَّد المدفوعات إلا عند عودة العميل إلى المتجر). ومن دون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب ألا يكون Title فارغًا وألا يتجاوز 128 حرفًا، ويجب أن يكون Transaction Type صالحًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total رقمًا أكبر من 0 أو يساويه، ويجب أن توجد المنطقة الجغرافية وحالات الطلب؛ وإلا فلن يُحفظ أي شيء. تُزال المسافات من بيانات الاعتماد. تُحفظ الإعدادات مع تحذير إذا لم يكن مفتاح webhook مفتاحًا سداسيًا عشريًا من 64 حرفًا، أو إذا لم تُحدَّد أي علامة دفع.

HyperPay

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

Title: العنوان الذي يراه العميل أثناء الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit/Debit Card (HyperPay). حقل إلزامي.

Description: النص الذي يراه العميل في خطوة Confirm Order، أعلى زر التأكيد وأسفل أيقونة البطاقة. الافتراضي: Pay securely using your credit or debit card.

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

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

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

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

تُصدر HyperPay Access Token وEntity ID ومفتاح webhook عند إعداد حساب التاجر لديك. بيانات الاعتماد الخاصة بالاختبار والإنتاج مختلفة. يظهر مفتاح webhook في لوحة تحكم HyperPay ضمن Administration > Webhooks. يتضمن القسم روابط إلى موقع HyperPay ووثائق المطورين.

Test Mode: يستخدم نظام اختبار HyperPay (eu-test.oppwa.com) وبيانات الاعتماد الخاصة بالاختبار. لا يُخصم أي مبلغ حقيقي. أوقفه لقبول المدفوعات الحقيقية ببيانات الاعتماد الخاصة بالإنتاج (eu-prod.oppwa.com). الافتراضي: مفعّل. وطالما هو مفعّل، يرى العملاء الرسالة Test mode: no real payment will be made. في خطوة Confirm Order.

Test Access Token: الرمز المميز (bearer token) لحساب الاختبار لديك في HyperPay.

Test Entity ID: معرّف Entity ID لقناة الدفع الخاصة بالاختبار.

Test Webhook Key: المفتاح السداسي العشري المكوّن من 64 حرفًا، ويُستخدم لفك تشفير إشعارات webhook من نظام الاختبار.

Live Access Token: الرمز المميز (bearer token) لحساب الإنتاج لديك في HyperPay.

Live Entity ID: معرّف Entity ID لقناة الدفع الخاصة بالإنتاج.

Live Webhook Key: المفتاح السداسي العشري المكوّن من 64 حرفًا، ويُستخدم لفك تشفير إشعارات webhook من نظام الإنتاج.

لا تُعرض رموز Access Token ومفاتيح webhook المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف قيمة محفوظة، حدّد Clear the saved value on save أسفل الحقل، ثم انقر على Save.

Webhook

يُخبر webhook متجرك بالمدفوعات حتى عندما يغلق العميل المتصفح قبل العودة إلى المتجر. في لوحة تحكم HyperPay (Administration > Webhooks)، أضف webhook للمدفوعات باستخدام عنوان URL المعروض في Webhook URL في هذا القسم. يبدو العنوان في OpenCart 3 هكذا: https://your-store/index.php?route=extension/payment/wcp_hyperpay_payment_gateway/webhook، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_hyperpay_payment_gateway/payment/wcp_hyperpay_payment_gateway.webhook، ويُنشأ من عنوان الواجهة الأمامية لتثبيت OpenCart لديك. انسخ العنوان تمامًا كما تعرضه الإعدادات. ثم انسخ مفتاح فك تشفير webhook إلى Test Webhook Key أو Live Webhook Key، بحسب الوضع نفسه.

إشعارات webhook من HyperPay مشفّرة (AES-256-GCM). يُرفض أي webhook لا يمكن فك تشفيره بمفاتيحك. تُعالج إشعارات الدفع فقط، ويجب أن ينتمي الدفع إلى صفحة دفع لأحد طلباتك، وأن يكون قد أُنشئ في الوضع نفسه للمفتاح الذي فك تشفيره. وتُقبل إشعارات الاختبار من HyperPay. كما يُبلغ webhook عن عمليات التحصيل والإلغاء والاسترداد والمطالبات المسترجعة (chargebacks) التي تُجرى في لوحة تحكم HyperPay (انظر الطلبات والاستردادات). ومن دون webhook، لا يُؤكَّد الدفع إلا عندما يعود العميل إلى المتجر بعد الدفع. ويعمل webhook أيضًا والمتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وفي OpenCart 4 تضيف الإضافة إجراء بدء تشغيل يسمح بمرور webhook وعودة العميل من HyperPay.

Payment

Transaction Type: طريقة خصم مبلغ البطاقة.

Payment Brands: العلامات التجارية التي تظهر في أداة الدفع: VISA وMastercard وmada وAmerican Express وSTC Pay وApple Pay. الافتراضي: VISA وMastercard. إذا لم تُحدَّد أي علامة، تُنبهك الصفحة وتعرض الأداة VISA وMastercard. حدّد فقط العلامات التي فعّلتها HyperPay لمعرّف Entity ID الخاص بك؛ فغالبًا ما تستخدم mada وSTC Pay وApple Pay كيانًا خاصًا بها، وهو ما لا تدعمه هذه الإضافة.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تؤكد HyperPay الدفع. ويبقى الطلب بلا حالة عند رفض الدفع أو التخلي عنه، ويُحفظ السلة. تسرد كل حقول أدناه حالات طلبات OpenCart لديك. لا تتوفر حالة On hold في OpenCart، لذلك يكون الافتراضي لثلاث منها هو Pending؛ ويمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Order Status After Payment: تُعيَّن عندما تؤكد HyperPay عملية خصم بالمبلغ والعملة الصحيحين، أو عندما يُحصَّل تفويض مسبق. الافتراضي: Processing.

Authorized (Capture Required) Status: حجز التفويض المسبق المبلغ؛ حصّله من تبويب الطلب. يؤدي الإلغاء في لوحة تحكم HyperPay إلى إلغاء الطلب ما دام بهذه الحالة. الافتراضي: Pending.

Awaiting Payment Status: أبلغت HyperPay عن دفعة تنتظر التأكيد؛ وسيؤكدها webhook لاحقًا. الافتراضي: Pending.

On Hold (Review) Status: المبلغ المدفوع أو العملة يختلفان عن الطلب، أو وصلت دفعة بعد إلغاء الطلب. توضح ملاحظة السبب. الافتراضي: Pending.

Canceled Status: تُعيَّن عند إلغاء التفويض المسبق في HyperPay. تؤدي الدفعة المتعلقة بطلب بهذه الحالة إلى وضعه قيد الانتظار بدلًا من إعادة فتحه. الافتراضي: Canceled.

Refunded Status: تُسجَّل الدفعة المستلمة لطلب بهذه الحالة كملاحظة فقط؛ ولا يتغير الطلب. الافتراضي: Refunded.

متقدم

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

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف الإعدادات وملفات السجل. تُحفظ الطلبات ومحاولات الدفع في HyperPay دائمًا، لأن إشعارات webhook المتأخرة وعمليات التحصيل للطلبات الموجودة تحتاجها. الافتراضي: معطّل.

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

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر رموز Access Token ومفاتيح webhook.

Import: الصق ملف JSON المُصدَّر سابقًا، وانقر على Import لاستعادة الإعدادات. تُحفظ رموز Access Token ومفاتيح webhook المحفوظة.

صفحة الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (HyperPay)). وفي خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. عندما ينقر العميل على Confirm Order، تُجهّز الإضافة جلسة دفع في HyperPay بقيمة الطلب وبعملة الطلب، وتفتح صفحة HyperPay payment في متجرك مع أداة HyperPay والعبارة Please complete your payment below:. تستخدم الأداة لغة العميل عندما تدعمها HyperPay. وفي وضع الاختبار، تعرض الصفحة Test mode: use a HyperPay test card, no real payment will be made. يُدخل العميل بيانات البطاقة في الأداة، أو يتبع Choose another payment method للعودة إلى صفحة الدفع. وعند إعادة تحميل الصفحة، تُعاد استخدام جلسة الدفع نفسها لمدة تصل إلى 25 دقيقة ما دام إجمالي الطلب لم يتغير؛ وبعد ذلك تُجهَّز جلسة جديدة.

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

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

إذا لم تكتمل الدفعة، يعود العميل إلى صفحة الدفع مع رسالة: Payment failed: والسبب الذي تُرجعه HyperPay، أو Payment was not completed. Please try again.، أو We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. تُحفظ السلة، ويستطيع العميل الدفع مرة أخرى. وإذا تعذّر تجهيز نموذج الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة، مثل أن مزوّد الدفع لم يقبل بعض بيانات الفوترة، أو أن نموذج الدفع غير متاح بسبب خطأ في إعدادات الدفع. يُكتب السبب التقني في السجل.

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

يُبقي OpenCart 4 الطلب في صفحة الدفع حتى تظهر صفحة النجاح. وإذا أُغلق ذلك الطلب في الأثناء دون دفع (مثلًا ألغيته أنت)، يُعاد العميل إلى صفحة الدفع مع الرسالة Payment failed. Please try again or use another card. وإذا دُفع الطلب ثم أُلغي أو استُرد، تكون الرسالة Your previous order was closed by the store. Please confirm the order again to pay with a new order. وإذا كان مدفوعًا بالفعل وتحتوي السلة الآن على شراء جديد، تكون الرسالة Your previous order #(الرقم) has already been placed. Your cart has changed: please confirm the new order to pay for it. وفي كل حالة، يدفع Confirm Order التالي طلبًا جديدًا للسلة. ولا يظهر الطلب المدفوع أبدًا كمدفوع لسلة مختلفة.

تُرسل المبالغ برقمين عشريين، كما تشترط واجهة HyperPay API. وفي العملات ذات الثلاث منازل عشرية (KWD وBHD وJOD وOMR) يُقرَّب إجمالي الطلب إلى منزلتين عشريتين.

لا تتضمن الإضافة استردادات أو إلغاءات من OpenCart، ولا بطاقات محفوظة أو ترميزًا (tokenization)، ولا اشتراكات، ولا التحقق من نطاق Apple Pay، ولا كيانًا منفصلًا لكل علامة، ولا Tabby أو Tamara أو غيرهما من طرق الشراء الآن والدفع لاحقًا.

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

حالات الطلب

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

Order Status After Payment (default Processing): تأكد خصم مدفوع، أو حُصّل تفويض مسبق. تعرض ملاحظة رمز نتيجة HyperPay ووصفها ومعرّف الدفعة. وإذا وضعت HyperPay علامة على الدفعة للمراجعة اليدوية، توضح الملاحظة ذلك؛ تحقق منها في لوحة تحكم HyperPay قبل الشحن.

Authorized (Capture Required) Status (default Pending): حجز التفويض المسبق المبلغ. حصّله من تبويب الطلب أو من لوحة تحكم HyperPay؛ ثم ينقل webhook التحصيل الطلب إلى Order Status After Payment.

Awaiting Payment Status (default Pending): أبلغت HyperPay أن الدفعة معلّقة. ينتقل الطلب إلى Order Status After Payment عندما تؤكدها HyperPay.

On Hold (Review) Status (default Pending): أبلغت HyperPay عن مبلغ أو عملة تختلف عن الطلب (مثلًا، تغيّرت السلة بعد فتح صفحة الدفع)، أو وصلت الدفعة بعد إلغاء الطلب. توضح الملاحظة ذلك. تحقق من الدفعة في لوحة تحكم HyperPay، ثم أكمل الطلب أو استرد الدفعة.

Canceled Status (default Canceled): أُلغي تفويض مسبق في لوحة تحكم HyperPay، ويؤدي webhook الإلغاء إلى إلغاء الطلب المعتمد.

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

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

تبويب VibeFox HyperPay Payment Gateway

في Sales > Orders افتح طلبًا دُفع عبر HyperPay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox HyperPay Payment Gateway معرّف الدفعة (ومعرّف التحصيل بعد التحصيل) مع الوسم Test mode للدفعات التجريبية، ونوع المعاملة، ومعرّف الدفع، ومعرّف معاملة التاجر، والمبلغ المرسل إلى HyperPay، والنتيجة، وHyperPay notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

التحصيل

بالنسبة إلى طلب تم التفويض المسبق له ولم يُحصَّل بعد، يعرض التبويب Capture payment مع المبلغ. انقر عليه وأكّد Capture the pre-authorized amount through HyperPay?. يُحصَّل إجمالي الطلب الحالي في الوضع الذي أُجري فيه التفويض المسبق، لذلك يجب تعيين Access Token وEntity ID لذلك الوضع. وتحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). بعد التحصيل الناجح، يحصل الطلب على Order Status After Payment، ويُضاف معرّف التحصيل إلى التبويب والملاحظات. تُكتب الحالة مباشرة، دون رسائل بريد إلكتروني للطلب ولا تحديث للمخزون. وإذا رفضت HyperPay التحصيل، يُعرض رمز النتيجة والوصف ويُضافان إلى الملاحظات، ويبقى الطلب معتمدًا. ولا يحصّل النقر المزدوج المبلغ مرتين. أما إلغاء التفويض المسبق (void) فيُجرى في لوحة تحكم HyperPay.

الاستردادات

الاستردادات من OpenCart غير مدعومة. ولا ترسل مرتجعات المنتجات في Sales > Returns الأموال عبر HyperPay. استرد الدفعة في لوحة تحكم HyperPay. وتُضاف الاستردادات والمطالبات المسترجعة التي تتم في HyperPay إلى الطلب كملاحظة عبر webhook؛ ولا تتغير حالة الطلب. حدّثها يدويًا عند الحاجة.

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

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

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

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

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

لا يظهر HyperPay في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على Access Token وEntity ID الخاصين به: الخاصة بالاختبار في وضع الاختبار، والخاصة بالإنتاج في وضع الإنتاج. تعرض صفحة الإعدادات تحذيرًا عند غيابهما. وتحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يصل إلى Total المضبوط في الإعدادات.

تمت الدفعة، لكن الطلب بقي بلا حالة: لا يعمل webhook، ولم يعد العميل إلى المتجر. في لوحة تحكم HyperPay، تحقق من وجود webhook الدفع للوضع الذي تستخدمه، ومن أن عنوان URL الخاص به مطابق تمامًا للعنوان المعروض في Webhook URL، ومن أن مفتاح فك التشفير موجود في حقل مفتاح webhook للوضع نفسه. فعّل Enable Logging وانظر إلى الحقل Log في صفحة الإضافة.

يرد webhook بالرسالة Decryption failed: مفتاح webhook يعود إلى webhook آخر أو وضع آخر. انسخ المفتاح من جديد من لوحة تحكم HyperPay.

يرد webhook بالرسالة Webhook key not configured: لم يُضبط مفتاح webhook صالح. الصق المفتاح المكوّن من 64 حرفًا في الإعدادات. ستعيد HyperPay محاولة webhook.

يرد webhook بالرسالة Busy, retry later: كان الطلب يُعالَج بطلب آخر في اللحظة نفسها، أو تعذّر تعيين حالة الطلب. ستعيد HyperPay محاولة webhook. السبب موجود في السجل.

يعرض السجل الرسالة Webhook ignored: الدفعة لا تنتمي إلى طلب من هذا المتجر، أو أُجريت في الوضع الآخر. تُفصل دفعات الاختبار ودفعات الإنتاج.

يعرض عنوان URL الخاص بـ webhook الرسالة Method not allowed في المتصفح: هذا طبيعي. لا يقبل العنوان إلا طلبات POST الصادرة من HyperPay.

لا يُحمَّل نموذج الدفع: راجع السجل. يشير خطأ الإعداد عادة إلى Access Token أو Entity ID غير صحيح للوضع الحالي. وتعني رسالة بيانات الفوترة أن HyperPay لم تقبل بعض بيانات العميل. تأكد من تفعيل Payment Brands المحددة لمعرّف Entity ID الخاص بك.

يرى العميل الرسالة The payment session was not found. Please confirm the order again.: رابط صفحة الدفع لم يعد صالحًا لهذا الطلب. يعيد العميل تأكيد الطلب في صفحة الدفع.

Order is in the on hold status: اقرأ الملاحظات في تبويب الطلب (انظر حالات الطلب)، وتحقق من الدفعة في لوحة تحكم HyperPay، ثم أكمل الطلب أو استرد الدفعة.

يفشل التحصيل: اقرأ رمز النتيجة والوصف في التبويب والملاحظات. يُرسل التحصيل في وضع التفويض المسبق، لذلك يجب تعيين بيانات اعتماد ذلك الوضع؛ وإلا فسيوضح التبويب أن Access Token / Entity ID لذلك الوضع فارغان.

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

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

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

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