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

المتطلبات

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

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. ويعمل مفتاح واحد على نطاق واحد.

التثبيت

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

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

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

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

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

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

عند التثبيت، تُنشئ الوحدة ثلاث حالات للطلب: Awaiting HyperPay payment وHyperPay payment authorized وHyperPay payment on hold. يربط PrestaShop وحدة الدفع الجديدة بالعملات والدول ومجموعات العملاء النشطة في تلك اللحظة. ويجب السماح بالدول التي تفعّلها لاحقًا في Payment > Preferences.

الإعدادات

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

HyperPay

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

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

Description: الوصف الذي يراه العميل في الدفع. الافتراضي: Pay securely using your credit or debit card.

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

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

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

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 tokens ومفاتيح webhook المحفوظة مرة أخرى. ويبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

مسح الأسرار المحفوظة: ضع علامة على token أو مفتاح ثم انقر على Save لإزالته. ويُبقي الحقل الفارغ القيمة المحفوظة.

Webhook

يُخبر الـ webhook متجرك بالمدفوعات حتى عندما يغلق العميل المتصفح قبل العودة إلى المتجر. في لوحة تحكم HyperPay (Administration > Webhooks)، أضف webhook للمدفوعات باستخدام العنوان المعروض في Webhook URL في هذا القسم. ومع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_hyperpay_payment_gateway/webhook، وربما مع رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات. ثم انسخ مفتاح فك تشفير الـ webhook إلى Test Webhook Key أو Live Webhook Key للوضع نفسه.

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

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 غالبًا كيانًا خاصًا بها، وهذه الوحدة لا تدعمه.

Advanced

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

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (HyperPay)) ويؤكد الطلب. تُجهّز الوحدة جلسة دفع في 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 دقيقة ما دامت السلة لم تتغير.

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

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

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

تعمل الـ webhooks أثناء وضع الصيانة في المتجر، ولا يعيقها تقييد الدول في متجرك.

لا تدعم الوحدة استردادات أو إلغاءات من PrestaShop، ولا بطاقات محفوظة أو ترميزًا، ولا اشتراكات، ولا التحقق من نطاق Apple Pay، ولا Entity ID منفصلًا لكل علامة تجارية، ولا Tabby أو Tamara أو أي طرق أخرى للدفع الآجل.

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

حالات الطلب

No order yet: أُرسل العميل إلى صفحة الدفع ولم يدفع، أو رُفض الدفع، أو لم تؤكد HyperPay الدفع بعد. لا توجد سوى السلة.

Payment accepted: تأكد دفع بالخصم المباشر، أو حُصِّل تفويض مسبق. ويُسجَّل الدفع بمعرّف دفع HyperPay كمعرّف للمعاملة، وتعرض ملاحظة خاصة رمز نتيجة HyperPay ووصفها ومعرّف الدفع. وإذا وضعت HyperPay الدفع للمراجعة اليدوية، تذكر الملاحظة ذلك؛ تحقق منه في لوحة تحكم HyperPay قبل الشحن.

HyperPay payment authorized: حُجز المبلغ بتفويض مسبق. حصّله من كتلة HyperPay الخاصة بالطلب أو من لوحة تحكم HyperPay؛ عندها ينقل webhook التحصيل الطلب إلى Payment accepted.

Awaiting HyperPay payment: أبلغت HyperPay أن الدفع معلّق. وينتقل الطلب إلى Payment accepted عندما تؤكد HyperPay الدفع.

HyperPay payment on hold: أبلغت HyperPay عن مبلغ أو عملة مختلفة عن السلة أو الطلب (مثلًا تغيّرت السلة بعد فتح صفحة الدفع)، أو وصل الدفع بعد إلغاء الطلب. وتشرح الملاحظة السبب. تحقق من الدفع في لوحة تحكم HyperPay، ثم أتمم الطلب أو استرد الدفع.

Canceled: عُكس التفويض المسبق في لوحة تحكم HyperPay، ويلغي webhook العكس الطلب المعتمد.

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

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

تعرض صفحة الطلب كتلة HyperPay payment تتضمن معرّف الدفع (ومعرّف التحصيل بعد التحصيل)، ونوع المعاملة، ومعرّف جلسة الدفع، ومعرّف معاملة التاجر، والمبلغ المرسل إلى HyperPay، والنتيجة، وشارة Test mode لمدفوعات الاختبار. وتوجد ملاحظات الوحدة في الرسائل الخاصة للطلب.

التحصيل

بالنسبة إلى طلب في حالة HyperPay payment authorized، تعرض الكتلة Capture payment مع المبلغ. انقر عليه وأكد Capture the pre-authorized amount through HyperPay?. يُحصَّل إجمالي الطلب الحالي في الوضع الذي أُجري فيه التفويض المسبق، لذلك يجب أن يكون Access Token وEntity ID لذلك الوضع مضبوطين. وتحتاج إلى صلاحية تعديل الطلبات؛ ولا يلزمك الوصول إلى صفحات الوحدة. وبعد التحصيل الناجح يصبح الطلب Payment accepted، ويُضاف معرّف التحصيل إلى الدفع وإلى الملاحظات. وإذا رفضت HyperPay التحصيل، يُعرض رمز النتيجة ووصفها ويُضافان إلى الملاحظات، ويبقى الطلب معتمدًا. ولا يُحصَّل المبلغ مرتين بالنقر المزدوج. ويتم إلغاء التفويض المسبق (void) في لوحة تحكم HyperPay.

الاستردادات

الاستردادات من PrestaShop غير مدعومة، وأزرار الاسترداد القياسية في PrestaShop لا ترسل الأموال عبر HyperPay. استرد الدفعة في لوحة تحكم HyperPay وسجّلها في PrestaShop باسترداد جزئي أو إشعار دائن إذا لزم الأمر. وتُضاف الاستردادات وعمليات chargeback التي تُنفَّذ في HyperPay إلى الطلب كملاحظة عبر الـ webhook؛ ولا تتغير حالة الطلب.

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

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

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

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

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

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

تم الدفع لكن لم يُنشأ أي طلب: لا يعمل الـ webhook ولم يعد العميل إلى المتجر. في لوحة تحكم HyperPay تحقق من وجود webhook الدفع للوضع الذي تستخدمه، ومن أن عنوانه مطابق تمامًا للعنوان المعروض في 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: الدفع لا ينتمي إلى سلة في هذا المتجر، أو تم في الوضع الآخر. ويُفصل الدفع التجريبي عن الدفع الحقيقي.

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

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

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

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

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

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

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