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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

متجر Barion: تحتاج إلى POSKey (المفتاح السري) لمتجرك وإلى البريد الإلكتروني لمحفظة Barion التي تستقبل المدفوعات. يمكنك العثور على الاثنين في بوابة Barion: secure.barion.com للإنتاج، وsecure.test.barion.com للاختبار، ضمن My stores ومتجرك. بيانات الاعتماد للاختبار والإنتاج مختلفة.

العملة: يجب أن تكون عملة السلة HUF أو EUR أو USD أو CZK. وبالنسبة للعملات الأخرى تُخفى طريقة الدفع في صفحة الدفع.

متجر قابل للوصول: تستدعي Barion متجرك بعد كل عملية دفع، لذلك يجب أن يكون الموقع قابلًا للوصول من الإنترنت، دون جدار حماية أو مصادقة أساسية أمامه.

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

التثبيت

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

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

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

4. أدخل POSKey الخاص بالاختبار وبريد محفظة الاختبار، واترك Test Mode مفعّلًا، وفعّل Enable/Disable، ثم انقر على Save. ضع طلب اختبار.

5. عندما يعمل كل شيء، أدخل بيانات الاعتماد الخاصة بالإنتاج وأوقف Test Mode.

يُرسل عنوان الاستدعاء (callback URL) إلى Barion تلقائيًا مع كل عملية دفع. لا يلزم إعداد أي شيء في بوابة Barion.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Barion Gateway > Configure. لكل قسم زر Save الخاص به، ويحفظ الزر الصفحة كاملة. وفوق الحقول تحذّرك الصفحة عندما لا يحتوي الوضع الحالي على POSKey أو على بريد المستلم (فتُخفى طريقة الدفع حينئذٍ في صفحة الدفع)، وعندما لا تدعم Barion العملة الافتراضية لمتجرك، مع قائمة بالعملات المدعومة. وطالما أن وضع الاختبار مفعّل تعرض الصفحة: وضع الاختبار مفعّل: تُرسل المدفوعات إلى بيئة الاختبار الخاصة بـ Barion (api.test.barion.com)، ولا يُخصم أي مبلغ حقيقي.

Barion

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Barion. مطلوب.

Description: النص الظاهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

بيانات اعتماد متجر Barion

احصل على POSKey وبريد المحفظة من بوابة Barion: secure.barion.com (للإنتاج) أو secure.test.barion.com (للاختبار)، ثم My stores، ومتجرك. يستخدم وضع الاختبار بيانات الاعتماد الخاصة بالاختبار فقط، ويستخدم وضع الإنتاج بيانات الإنتاج فقط.

Test Mode: يستخدم بيانات اعتماد الاختبار المدخلة أدناه وبيئة الاختبار الخاصة بـ Barion (api.test.barion.com). لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية. وطالما هو مفعّل يرى العملاء أسفل طريقة الدفع: وضع الاختبار: لا تُحصَّل أي دفعة حقيقية.

Test POSKey: المفتاح السري (POSKey) لمتجرك في نظام الاختبار الخاص بـ Barion (secure.test.barion.com، My stores).

Test Payee Email: عنوان البريد الإلكتروني لمحفظة Barion التجريبية التي تستقبل مدفوعات الاختبار.

Live POSKey: المفتاح السري (POSKey) لمتجرك في نظام الإنتاج الخاص بـ Barion (secure.barion.com، My stores).

Live Payee Email: عنوان البريد الإلكتروني لمحفظة Barion التي تستقبل المدفوعات.

لا تُعرض مفاتيح POSKey المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض: محفوظ — اتركه فارغًا للاحتفاظ به. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved POSKeys: حدّد مفتاحًا وانقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

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

الطلبات

Order Status After Payment: حالة الطلب التي تُعيَّن بعد عملية دفع ناجحة ومُتحقَّق منها.

تبقى المدفوعات التي لا تزال Barion تعالجها في Awaiting Barion payment. وتذهب حالات عدم تطابق المبلغ أو العملة دائمًا إلى Barion payment on hold.

متقدم

Logging: يكتب طلبات Barion واستدعاءاتها في logs/barion_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. ولا تُسجَّل المفاتيح السرية وبريد المحافظ. الافتراضي: موقوف. وطالما هو موقوف لا يُكتب أي شيء، بما في ذلك الأخطاء.

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Barion) ويرى الملاحظة ستُنقل إلى صفحة دفع Barion الآمنة. وبعد التأكيد تبدأ الوحدة عملية دفع Barion بإجمالي السلة وبعملة السلة، وتنقل العميل إلى صفحة دفع Barion. تُدرج المنتجات والشحن وتغليف الهدايا والضريبة في الدفعة، وتظهر الدفعة بالاسم Cart مع رقم السلة، ويُمرَّر بريد العميل كتلميح، ويتبع لغة الصفحة لغة السلة حيثما تدعمها Barion. ولا يوجد أي طلب في هذه المرحلة.

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

إذا نجحت عملية الدفع يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة تم استلام دفعتك عبر Barion. وإذا كانت عملية الدفع لا تزال قيد المعالجة لدى Barion يُنشأ الطلب في Awaiting Barion payment، وتعرض الصفحة: يجري تأكيد دفعتك من قبل Barion. ستتلقى رسالة بريد إلكتروني فور تأكيدها. وإذا أُلغيت عملية الدفع هذه لاحقًا أو انتهت صلاحيتها أو فشلت لدى Barion، تعرض الصفحة: لم تكتمل دفعتك عبر Barion. يرجى التواصل معنا بشأن هذا الطلب. وإذا تعذر الوصول إلى Barion عند عودة العميل، تظهر صفحة تأكيد الدفع بالنص نفسه «يجري التأكيد» وزر Check again؛ وينشئ الاستدعاء الطلب فور تأكيد Barion للدفعة.

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

إذا تعذر بدء عملية الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة: تعذّر بدء الدفع عبر Barion. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.، أو لا تدعم Barion الدفع بالعملة الخاصة بالسلة، أو لا يمكن لـ Barion معالجة طلب إجماليه صفر. وتُكتب التفاصيل في السجل عند تفعيل Logging.

يعمل الاستدعاء أثناء وضع الصيانة للمتجر، ولا يُحظر بقيد الدول الخاص بمتجرك.

تعالج الوحدة المدفوعات الفورية فقط. لا توجد مدفوعات حجز أو تحصيل مؤجل، ولا اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة، ولا Barion Pixel، ولا بيانات 3-D Secure إضافية؛ إذ تتولى Barion التحقق بـ 3-D Secure في صفحة الدفع الخاصة بها.

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

حالات الطلب

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

Awaiting Barion payment: تُفيد Barion بأن عملية الدفع ما زالت قيد المعالجة. تعرض الملاحظة معرّف PaymentId الخاص بـ Barion والمبلغ، وفي وضع الاختبار (test mode). ينتقل الطلب إلى «تم قبول الدفع» عندما تؤكد Barion الدفعة.

Payment accepted or Delivered: أكدت Barion الدفعة. وتتبع الحالة الإعداد Order Status After Payment. تُسجَّل الدفعة بمعرّف معاملة Barion، وتعرض الملاحظة المبلغ ومعرّف PaymentId والمعاملة.

Barion payment on hold: أبلغت Barion بمبلغ أو عملة تختلف عن إجمالي الطلب، مثلًا لأن السلة عُدّلت بعد بدء الدفع. تعرض الملاحظة المبلغين. تحقّق من الدفعة في بوابة Barion، ثم أكمل الطلب أو استرد الدفعة في بوابة Barion.

Canceled: أُلغيت آخر محاولة دفع لطلب في الانتظار أو انتهت صلاحيتها لدى Barion.

Payment error: فشلت آخر محاولة دفع لطلب في الانتظار.

Refunded: استُرد الدفع بالكامل عبر الوحدة.

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

كتلة دفع Barion

تعرض صفحة الطلب كتلة Barion payment تتضمن معرّف PaymentId ومعاملة Barion وحالة الدفع والمبلغ المدفوع والمسترد وشارة Test mode لمدفوعات الاختبار وسجل الاسترداد.

الاسترداد

في كتلة Barion payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واكتب سببًا اختياريًا، ثم انقر على Refund via Barion. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Barion؟ لا يمكن التراجع عن هذا الإجراء. يُدعم الاسترداد الكامل والجزئي. ويلزمك صلاحية تعديل الطلبات. يُرسل السبب إلى Barion كتعليق. ويجب أن تكون مبالغ الاسترداد بعملة HUF أعدادًا صحيحة. يُرسل الاسترداد في الوضع (الاختبار أو الإنتاج) الذي تمت به عملية الدفع، لذلك يجب تعيين POSKey الخاص بذلك الوضع. وإذا لم تقبل Barion الاسترداد أو لم تؤكده، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع معاملة Barion وحالتها. ويؤدي الاسترداد الكامل إلى وضع الطلب على Refunded. ولا يغيّر الاسترداد الجزئي الحالة.

تتوفر عمليات الاسترداد بعد أن تؤكد Barion الدفعة ويصبح الطلب مدفوعًا بها. ولا يمكن استرداد دفعة تختلف مبلغها أو عملتها من PrestaShop؛ استردها في بوابة Barion. ولا تُنشئ الوحدة إشعارات دائنة، ولا تعيد أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب أي أموال عبر Barion.

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

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

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

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

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

لا تظهر Barion في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على POSKey وبريد المستلم (تعرض صفحة الإعدادات تحذيرًا عند غياب أيٍّ منهما)، وأن عملة السلة هي HUF أو EUR أو USD أو CZK. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

تمت عملية الدفع لكن لم يُنشأ أي طلب: يُنشأ الطلب عندما تستدعي Barion عنوان الاستدعاء أو عندما يعود العميل إلى متجرك. تأكد من أن الموقع قابل للوصول من الإنترنت (دون جدار حماية أو مصادقة أساسية أمام عنوان الاستدعاء). وتحقّق من أن POSKey الخاص بالوضع الذي تمت فيه عملية الدفع صحيح، لأن الوحدة تسأل Barion عن حالة الدفع به. وفعّل Logging لرؤية الاستدعاء.

يرد الاستدعاء بالرسالة Busy, retry: كان الطلب يُعالَج في اللحظة نفسها بعودة العميل، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد Barion الاستدعاء. وفعّل Logging لرؤية السبب.

يرد الاستدعاء بالرسالة API error: تعذّر على المتجر قراءة حالة الدفع من Barion، أو أن POSKey الخاص بالوضع الذي تمت فيه عملية الدفع غير مُعيَّن. تحقّق من POSKey هذا.

يرد الاستدعاء بالرسالة Order not found: لم يبدأ هذا المتجر معرّف PaymentId. تُتجاهل استدعاءات Barion الخاصة بمتاجر أخرى أو بأنظمة الاختبار.

يرى العميل الرسالة «فشل التحقق من الدفع»: رابط العودة لا يطابق السلة، مثلًا لأنه فُتح في جلسة متصفح أخرى أو عُدّل. ومع ذلك يؤكد الاستدعاء حالة الدفع.

يرى العميل خطأً عند اختيار Barion: فعّل Logging وراجع حقل Log في صفحة الوحدة. فـ POSKey أو بريد المستلم غير الصحيح يؤدي إلى تعذّر بدء الدفع عبر Barion.

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

لماذا لا أستطيع استرداد 10,50 HUF؟: تعالج Barion عملة HUF بدون كسور عشرية. أدخل مبلغًا صحيحًا.

يقول الاسترداد إن POSKey الخاص بـ Barion لوضع هذا الطلب غير مُعدّ: تمت عملية الدفع في وضع الاختبار أو الإنتاج، وPOSKey الخاص بذلك الوضع فارغ. أدخله وأعد المحاولة.

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

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

Barion علامة تجارية مسجّلة لمالكها. وهذه الوحدة غير تابعة لـ Barion ولا معتمدة من قِبلها.