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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبت ومفعّل. بدونه تعرض الإضافة تنبيهًا في لوحة الإدارة ولا تُحمَّل طريقة الدفع.

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل POSKey الخاص بالاختبار وبريد محفظة الاختبار، واترك Test Mode مفعّلًا، وفعّل Enable/Disable. ونفّذ طلبًا تجريبيًا.

6. عندما تعمل كل الأمور بشكل صحيح، أدخل بيانات الاعتماد الخاصة بالإنتاج، وألغِ تحديد Test Mode.

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

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Barion. وإذا لم تكن عملة المتجر مدعومة، تُخبرك الصفحة بذلك بالأحمر في قسم Barion shop credentials وتسرد العملات المدعومة؛ وتُخفى طريقة الدفع في صفحة الدفع حينها.

عام

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، ثم متجرك. ويعرض هذا القسم أيضًا عنوان callback، مثل https://your-site/wc-api/barion_payment_callback/. ويُرسل إلى Barion مع كل دفعة، ويكفي أن يكون متاحًا من الإنترنت.

Test Mode: Enable Barion test/sandbox 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 التي تستقبل المدفوعات.

الطلبات

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

متقدم

Logging: Enable debug logging. تُحفظ السجلات في WooCommerce > Status > Logs، والمصدر wcp_barion_gateway. لا تُسجَّل المفاتيح السرية أبدًا. الافتراضي: إيقاف.

Delete Data on Uninstall: Remove the plugin settings when the plugin is deleted. تبقى الطلبات وبيانات دفع Barion الخاصة بها محفوظة دائمًا. الافتراضي: إيقاف.

صفحة الدفع

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

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

إذا نجح الدفع أو ما زال قيد المعالجة لدى Barion، يصل العميل إلى صفحة استلام الطلب. وإلا يعود إلى صفحة الدفع ويرى الرسالة Payment was not completed. Please try again. ويمكن للعميل المحاولة مجددًا؛ وتُحفظ كل محاولة، فيُكمل الدفع المتأخر لمحاولة سابقة الطلب.

إذا تعذّر بدء الدفع يرى العميل الرسالة The Barion payment could not be started. Please try again or choose another payment method. ويرى مديرو المتجر المسجلون السبب التقني أيضًا، وتذهب التفاصيل إلى السجل.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية وفي كتلة Checkout. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

Order statuses

Pending payment: بدأت عملية الدفع في Barion ولم تؤكدها Barion بعد. تعرض ملاحظة الطلب PaymentId الخاص بـ Barion والمبلغ، وفي وضع الاختبار تُضاف (test mode).

Processing or Completed: أكدت Barion الدفع. تتبع الحالة الإعداد Order Status After Payment. وتعرض ملاحظة الطلب المبلغ وPaymentId والمعاملة. ومعرّف المعاملة هو معرّف معاملة Barion.

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

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

Failed: فشلت آخر محاولة دفع.

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

الاستردادات

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

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

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

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

بدون مفتاح فعّال لا تظهر Barion للعملاء في صفحة الدفع. وإذا بدأ أحدهم دفعًا رغم ذلك، يرى الرسالة This payment method is not available. Please choose another one. ويظل مديرو المتجر المسجلون يرون طريقة الدفع، مع علامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. ويظهر تذكير في صفحة Plugins وفي صفحات WooCommerce. ولا تتأثر الطلبات الحالية: تبقى المدفوعات التي بدأت مؤكدة، وتعمل الاستردادات.

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

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

Barion لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على POSKey وبريد المستلم، وأن عملة المتجر HUF أو EUR أو USD أو CZK.

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

يرد callback بـ Busy, retry: كان الطلب يُعالَج في اللحظة نفسها بعودة العميل. وستعيد Barion الاستدعاء.

يرد callback بـ API error: تعذّر على المتجر قراءة حالة الدفع من Barion. تحقق من POSKey للوضع الذي تمت به الدفعة.

الطلب في حالة On hold مع ملاحظة عدم تطابق: المبلغ أو العملة اللذان تُبلغ بهما Barion يختلفان عن إجمالي الطلب. تحقق من الدفعة في بوابة Barion، وأكملها أو استردها يدويًا.

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

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

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

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

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

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