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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر Activate.

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

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

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

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

7. فعّل Enable/Disable وأجرِ دفعة تجريبية ببطاقة اختبار من HyperPay. ثم أدخل بيانات الإنتاج وأوقف Test Mode.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > HyperPay. وتعرض الصفحة فوق الحقول، ما دام وضع الاختبار مفعّلًا، الرسالة وضع الاختبار مفعّل: تُرسَل المدفوعات إلى نظام اختبار HyperPay ولا يُخصم أي مبلغ حقيقي. وتحذّرك عندما يغيب Access Token أو Entity ID للوضع الحالي (فلا تظهر طريقة الدفع في صفحة الدفع حينئذٍ)، وعندما لا يملك الوضع الحالي مفتاح webhook صالحًا (فلا تُعتمد المدفوعات إلا عند عودة العميل إلى المتجر). وفي قائمة طرق الدفع، تظهر البوابة بوصف «تحتاج إلى إعداد» إلى أن يحصل الوضع الحالي على Access Token وEntity ID. وعند الحفظ تُحذف المسافات من بيانات الاعتماد، وتعرض الصفحة خطأ إذا لم يكن مفتاح webhook مفتاحًا سداسي عشريًا من 64 خانة.

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: Enable Test Mode يستخدم نظام اختبار HyperPay (eu-test.oppwa.com) وبيانات الاعتماد التجريبية. لا يُخصم أي مبلغ حقيقي. أوقفه لقبول المدفوعات الحقيقية ببيانات الإنتاج (eu-prod.oppwa.com). الافتراضي: مفعّل.

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 لنظام الإنتاج.

Webhook

يُخبر الـ webhook متجرك بالمدفوعات حتى عندما يُغلق العميل المتصفح قبل العودة إلى المتجر. في لوحة تحكم HyperPay (Administration > Webhooks)، أضف webhook للمدفوعات بالعنوان المعروض في هذا القسم من الإعدادات. ويبدو العنوان هكذا: https://your-site/wp-json/hyperpay-p/v1/webhook. ثم انسخ مفتاح فك تشفير الـ webhook إلى Test Webhook Key أو Live Webhook Key للوضع نفسه.

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

الدفع

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

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

متقدم

Enable Logging: Log API requests and responses. تُكتب معلومات التصحيح في WooCommerce > Status > Logs، بالمصدر wcp_hyperpay_payment_gateway. تُسجَّل الأخطاء دائمًا. لا تحتوي السجلات على بيانات البطاقة أو المفاتيح أو بيانات العميل. الافتراضي: معطّل.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. يزيل الإعدادات وملفات السجل عند حذف الإضافة. تبقى بيانات HyperPay المحفوظة في الطلبات. الافتراضي: معطّل.

عملية الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (HyperPay)) وينقر Continue to payment. يُنشأ الطلب وينتقل العميل إلى صفحة Pay for order. هناك تُعِدّ الإضافة جلسة دفع في HyperPay بقيمة إجمالي الطلب وبعملة الطلب، وتعرض أداة HyperPay مع الرسالة يرجى إتمام الدفع أدناه:. وتستخدم الأداة لغة موقعك عندما تدعمها HyperPay. وفي وضع الاختبار تعرض الصفحة وضع الاختبار: استخدم بطاقة اختبار من HyperPay؛ لن تتم أي عملية دفع حقيقية. ويُدخل العميل بيانات البطاقة في الأداة.

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

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

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

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

لا تدعم الإضافة الاستردادات أو الإلغاءات من WooCommerce، ولا البطاقات المحفوظة أو الترميز (tokenization)، ولا الاشتراكات، ولا التحقق من نطاق Apple Pay، ولا Entity ID منفصلًا لكل علامة تجارية، ولا Tabby أو Tamara أو أي طرق أخرى للدفع الآجل (buy now, pay later).

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

حالات الطلب

Pending payment: لم يدفع العميل بعد، أو لم يُكمل الأداة، أو لم تؤكد HyperPay الدفع بعد.

Processing: تم تأكيد دفعة خصم، أو تم تحصيل تفويض مسبق. تنتقل الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى حالة «مكتمل»، وهي الحالة الافتراضية في WooCommerce. وتعرض ملاحظة الطلب رمز نتيجة HyperPay ووصفها ومعرّف الدفع. ومعرّف المعاملة هو معرّف الدفع في HyperPay. وإذا وضعت HyperPay علامة مراجعة يدوية على الدفعة، فستذكر الملاحظة ذلك؛ تحقق منها في لوحة تحكم HyperPay قبل الشحن.

On hold (pre-authorization): تم حجز المبلغ. حصّله بإجراء الطلب Capture HyperPay payment أو من لوحة تحكم HyperPay؛ وعندها يُكمل webhook التحصيل الطلب.

On hold after payment: أبلغت HyperPay عن مبلغ أو عملة تختلف عن الطلب (مثلًا عُدّل الطلب بعد فتح صفحة الدفع)، أو ما زالت الدفعة معلّقة لدى HyperPay، أو وصلت الدفعة بعد إلغاء الطلب. وتشرح ملاحظة الطلب ذلك. تحقّق من الدفعة في لوحة تحكم HyperPay ثم أكمِلها أو استرجعها.

Failed: رفضت HyperPay الدفعة. السبب مذكور في ملاحظة الطلب ويظهر للعميل. ولا تغيّر المحاولة المرفوضة أبدًا طلبًا مدفوعًا أو محجوزًا أو في الانتظار أو ملغيًا.

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

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

التحصيل

يظهر إجراء الطلب Capture HyperPay payment في الطلبات المعلّقة التي تحتوي على تفويض مسبق لم يُحصَّل بعد. ويُحصّل إجمالي الطلب الحالي مطروحًا منه الاستردادات المسجلة بالفعل في WooCommerce، وذلك في الوضع الذي تم فيه التفويض المسبق. وبعد التحصيل الناجح يصبح الطلب Processing. وإذا رفضت HyperPay التحصيل، يُعرض رمز النتيجة ووصفها، ويُضافان إلى ملاحظات الطلب. ويتم عكس التفويض المسبق (إلغاؤه) في لوحة تحكم HyperPay.

الاستردادات

لا يُدعم الاسترداد من WooCommerce. استرجع الدفعة في لوحة تحكم HyperPay وسجّلها في WooCommerce باستخدام Refund manually. وتُضاف الاستردادات والـ chargebacks التي تتم في HyperPay إلى الطلب كملاحظة عبر الـ webhook؛ ولا تتغير حالة الطلب.

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

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

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

من دون مفتاح فعّال، لا تظهر HyperPay للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل لا تتوفر طريقة الدفع هذه. يرجى اختيار طريقة أخرى.. ويظل مديرو المتجر الذين سجّلوا الدخول يرون طريقة الدفع مع الوسم (unlicensed — visible to admins only)، ليتمكنوا من إعداد الإضافة واختبارها قبل شراء مفتاح. وتظهر تذكرة في صفحة Plugins وفي صفحات WooCommerce. ولا تتأثر الطلبات الحالية: فالدفعات التي بدأت تبقى مؤكَّدة، والتحصيلات تعمل.

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

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

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

تمت عملية الدفع لكن الطلب يبقى Pending payment: الـ webhook لا يعمل والعميل لم يعد إلى المتجر. في لوحة تحكم HyperPay تحقّق من وجود webhook الدفع للوضع الذي تستخدمه، ومن أن عنوانه مطابق تمامًا للعنوان المعروض في الإعدادات، ومن أن مفتاح فك التشفير موجود في حقل مفتاح webhook للوضع نفسه. وراجع WooCommerce > Status > Logs، بالمصدر wcp_hyperpay_payment_gateway.

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

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

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

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

الطلب في حالة On hold مع ملاحظة عدم تطابق المبلغ أو العملة: أبلغت HyperPay عن دفعة لا تطابق إجمالي الطلب أو عملته، مثلًا لأن الطلب عُدّل بعد فتح صفحة الدفع. تحقّق من الدفعة في لوحة تحكم HyperPay ثم أكمِلها أو استرجعها.

يفشل التحصيل: اقرأ رمز النتيجة والوصف في ملاحظة الطلب. يُرسَل التحصيل في وضع التفويض المسبق، لذلك يجب أن تكون بيانات اعتماد ذلك الوضع مضبوطة.

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

للمطورين: يغيّر الفلتر hyperpay_p_icon أيقونة طريقة الدفع.

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

تعطيل الإضافة يُبقي على كل البيانات. ولإزالتها، عطّلها ثم احذفها من صفحة Plugins. وتُزال دائمًا مفاتيح الترخيص وحالة الترخيص لهذه الإضافة. ولا تُزال إعدادات البوابة والبيانات المؤقتة للإضافة وملفات السجل إلا إذا كان Delete Data on Uninstall مفعّلًا؛ وإلا تبقى لإعادة التثبيت لاحقًا. وتبقى بيانات HyperPay المحفوظة في الطلبات دائمًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات الخاصة بها.

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