VibeFox ePay.bg for WooCommerce — المساعدة

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل.

PHP: 8.0 أو أحدث.

عملة المتجر: الليف البلغاري (BGN) أو اليورو (EUR) أو الدولار الأمريكي (USD). يُخصم مبلغ الطلب بعملته الخاصة بمنزلتين عشريتين. وبالنسبة إلى العملات الأخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب ePay.bg: تحتاج إلى رقم العميل (MIN) والمفتاح السري من ملف التاجر الخاص بك في ePay.bg: بيانات الوضع الفعلي من www.epay.bg، وبيانات الاختبار من demo.epay.bg (يُسجَّل حساب الاختبار بشكل منفصل). وتحتاج أيضًا إلى إدخال عنوان URL للإشعارات الخاص بمتجرك في ملف التاجر.

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

التثبيت

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

2. انقر Activate. يجب أن يكون WooCommerce مفعّلًا.

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

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

5. أدخل MIN والمفتاح السري للاختبار و/أو للوضع الفعلي (راجع قسم الإعداد).

6. انسخ عنوان URL للإشعارات المعروض في القسم Payment notifications (IPN) إلى الحقل URL for receiving notifications في ملف التاجر في ePay.bg، في الملف التجريبي والملف الفعلي معًا. وبدونه تبقى الطلبات بحالة بانتظار الدفع.

7. فعّل Enable/Disable. أجرِ طلب اختبار في وضع الاختبار، ثم ألغِ تحديد Test Mode.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > ePay.bg. تعرض الصفحة فوق الحقول خطأً عندما لا تكون عملة المتجر BGN أو EUR أو USD، وتحذيرًا عندما تكون البوابة مفعّلة لكن MIN أو المفتاح السري للوضع المحدد فارغ (وعندئذ تُخفى في صفحة الدفع، ويظهر الخطأ نفسه عند الحفظ)، كما تعرض Test mode is on: payments go to demo.epay.bg and no real money is charged. ما دام وضع الاختبار مفعّلًا. وفي قائمة طرق الدفع تُعلَّم ePay.bg بأنها تحتاج إلى إعداد إلى أن تُدخَل بيانات اعتماد الوضع المحدد.

عام

Enable/Disable: يقوم Enable ePay.bg Payment Gateway بتشغيل طريقة الدفع أو إيقافها. الافتراضي: متوقفة.

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: ePay.bg.

Description: النص الذي يظهر تحت طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely via ePay.bg with a bank card or your ePay.bg account.

حساب ePay.bg

يظهر رقم العميل (MIN) والمفتاح السري في ملف التاجر الخاص بك على www.epay.bg (الفعلي) وdemo.epay.bg (حساب الاختبار المسجَّل بشكل منفصل). تُحذف المسافات وفواصل الأسطر من المفاتيح السرية الملصقة عند الحفظ.

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). عند التفعيل يُحوَّل العملاء إلى بيئة ePay.bg التجريبية وتُوقَّع الطلبات ببيانات اعتماد الاختبار. الافتراضي: مفعّل.

Test Merchant ID (MIN): رقم العميل (MIN) لحساب التاجر الخاص بك على demo.epay.bg.

Test Secret Key: المفتاح السري لحساب التاجر الخاص بك على demo.epay.bg (64 حرفًا).

Live Merchant ID (MIN): رقم العميل (MIN) لحساب التاجر الخاص بك على www.epay.bg.

Live Secret Key: المفتاح السري لحساب التاجر الخاص بك على www.epay.bg (64 حرفًا)، ويُستخدم لتوقيع HMAC-SHA1.

إذا حدّثت من الإصدار 1.0، تُنقل مجموعة بيانات الاعتماد الوحيدة في ذلك الإصدار إلى حقول الاختبار إذا كان وضع الاختبار مفعّلًا.

إشعارات الدفع (IPN)

يُعلم الإشعار متجرك بأن طلب دفع قد دُفع أو رُفض أو انتهت مدته. يعرض هذا القسم عنوان URL للإشعارات، ويبدو هكذا: https://your-site/wc-api/epaybg_payment_callback/. أدخله بوصفه URL for receiving notifications في ملف التاجر في ePay.bg، للوضع الفعلي والاختبار. لا تُعلَّم الطلبات كمدفوعة إلا بهذه الإشعارات الموقّعة؛ أما عودة العميل إلى المتجر فلا تجعل الطلب مدفوعًا.

تُبلغ ePay.bg بهذه النتائج لكل فاتورة:

يُتحقق من كل إشعار بالمفتاح السري للوضع المحدد. تُرفض الإشعارات التي لا تحمل مجموع تحقق صالحًا، وتواصل ePay.bg إرسالها. وبدون عنوان URL للإشعارات في ملف التاجر لا يُعلَّم أي طلب كمدفوع.

طلب الدفع

Invoice Prefix: أرقام فقط (حتى 10)، توضع قبل معرّف الطلب لتكوّن رقم فاتورة ePay.bg، مثل 00001 + 123 = 00001123. استخدم بادئات مختلفة للمتاجر المختلفة على حساب ePay.bg واحد. تُحذف الأحرف الأخرى عند الحفظ. تغيير البادئة لاحقًا آمن: تُوجد الطلبات المعلّقة من خلال الفاتورة المحفوظة في الطلب. الافتراضي: 00001.

Expiration Time: المدة التي ينتهي بعدها طلب الدفع غير المدفوع؛ عندئذ تبلغ ePay.bg بانتهائه ويُلغى الطلب المعلّق. اختر 1 أو 3 أو 6 أو 12 أو 24 أو 48 أو 72 ساعة. يُرسل الوقت بتوقيت بلغاريا مهما كانت المنطقة الزمنية لموقعك. الافتراضي: 24 ساعة.

Language: لغة صفحة الدفع في ePay.bg، الإنجليزية أو البلغارية. الافتراضي: الإنجليزية.

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفع ناجح. تُعيَّن الحالة فورًا، دون تغيير ثانٍ للحالة.

متقدم

Logging: يكتب Enable logging طلبات الدفع والإشعارات في WooCommerce > Status > Logs، المصدر wcp_epaybg_gateway، دون المفاتيح السرية أو بيانات البطاقة. الافتراضي: متوقف.

Delete Data on Uninstall: Remove all plugin data when uninstalled. إذا كان محددًا، تُحذف إعدادات البوابة وبيانات ePay.bg المحفوظة في الطلبات وسجلات الإضافة عند إلغاء تثبيت الإضافة. الافتراضي: متوقف.

صفحة الدفع

يختار العميل طريقة الدفع (ePay.bg افتراضيًا) ويُتم الطلب. يرى العميل Redirecting to ePay.bg for payment... ويُحوَّل إلى ePay.bg مع طلب دفع موقّع بإجمالي الطلب بعملة الطلب، ومعه رقم الفاتورة ووقت الانتهاء. وفي الصفحة أيضًا زر Pay via ePay.bg في حال لم يبدأ التحويل، وزر Cancel order. وفي ePay.bg يدفع العميل ببطاقة مصرفية أو بحساب ePay.bg.

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا عند وصول إشعار ePay.bg الموقّع. ولا تُفرَّغ السلة إلا في صفحة استلام الطلب.

إذا ألغى العميل في ePay.bg، يُلغى الطلب بالطريقة القياسية في WooCommerce وتبقى السلة محفوظة، فيستطيع العميل اختيار طريقة دفع أخرى.

إذا تعذّر دفع الطلب عبر ePay.bg، يرى العميل رسالة قصيرة، مثل ePay.bg payments are temporarily unavailable. Please choose another payment method. أو رسالة بأن ePay.bg لا تقبل المدفوعات بعملة الطلب.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

تقبل الإضافة المدفوعات لمرة واحدة فقط في ePay.bg. لا تتضمن الاستردادات من WooCommerce، ولا البطاقات المحفوظة أو الترميز (tokenization)، ولا الاشتراكات أو المدفوعات المتكررة، ولا رموز الدفع النقدي EasyPay أو B-Pay.

الطلبات

حالات الطلب

Pending payment: حُوِّل العميل إلى ePay.bg ولم يدفع بعد، أو لم يصل الإشعار بعد. تقول ملاحظة الطلب Awaiting ePay.bg payment.

Processing, Completed or On Hold: تأكد الدفع. تتبع الحالة الخيار Order Status After Payment. تعرض ملاحظة الطلب رقم الفاتورة وتاريخ الدفع وSTAN ورمز BORICA. معرّف المعاملة هو STAN (أو رقم الفاتورة إذا لم يوجد STAN).

On hold after payment: وصل الدفع، لكن ليس لما يقوله الطلب الآن: تغيّر الإجمالي أو العملة بعد طلب الدفع، أو أُجري الطلب في الوضع الآخر أو بُدّلت البوابة لاحقًا بين الاختبار والفعلي، أو تغيّرت طريقة الدفع للطلب، أو كان الطلب قد أُلغي من قبل. تشرح ملاحظة الطلب السبب. تحقق من الدفعة في لوحة تاجر ePay.bg وأكمل الطلب أو استرد مبلغه يدويًا.

Cancelled: أبلغت ePay.bg بأن طلب الدفع رُفض أو انتهت مدته، أو ألغى العميل في ePay.bg. يستعيد WooCommerce المخزون. لا يمكن دفع طلب ملغى مرة أخرى، لأن رقم فاتورة ePay.bg هو البادئة مضافًا إليها معرّف الطلب. يُجري العميل طلبًا جديدًا.

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

الاستردادات

الاستردادات من WooCommerce غير متاحة، لأن واجهة ePay.bg WEB API لا تحتوي على استدعاء للاسترداد. استرد الدفعة في لوحة تاجر ePay.bg وسجّل الاسترداد يدويًا في WooCommerce.

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

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

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

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

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

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

ePay.bg لا تظهر في صفحة الدفع: تأكد من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن MIN والمفتاح السري للوضع المحدد مدخلان، وأن عملة المتجر BGN أو EUR أو USD. تعرض صفحة الإعدادات تحذيرًا في كل حالة من هذه الحالات.

تمت عملية الدفع، لكن الطلب يبقى بانتظار الدفع: لا يُعلَّم الطلب كمدفوع إلا بإشعار ePay.bg. تأكد من إدخال عنوان URL للإشعارات في ملف التاجر في ePay.bg للوضع الذي تستخدمه (تجريبي أو فعلي) ومن صحة المفتاح السري للوضع النشط. فعّل Logging وراجع WooCommerce > Status > Logs، المصدر wcp_epaybg_gateway.

يردّ الإشعار بـ ERR=Not valid CHECKSUM: المفتاح السري في الإعدادات لا يطابق ملف التاجر الذي أرسل الإشعار. تُفحص الإشعارات بمفتاح الوضع المحدد حاليًا ثم بمفتاح الوضع الآخر، ولذلك تظل طلبات الدفع التي أُجريت قبل تبديل الوضع مقبولة. وتواصل ePay.bg إعادة المحاولة، فيتحدّث الطلب بمجرد أن يصبح المفتاح صحيحًا.

يردّ الإشعار بـ ERR=Not configured: المفتاح السري للوضع المحدد فارغ. أدخله.

يردّ الإشعار بـ STATUS=NO لفاتورة: الفاتورة لا تخص طلب ePay.bg من هذا المتجر، فمثلًا قد يكون متجر آخر على حساب ePay.bg نفسه هو من أصدرها. امنح كل متجر Invoice Prefix خاصًا به.

يردّ الإشعار بـ STATUS=ERR: خطأ مؤقت، مثل وصول إشعارين للطلب نفسه في اللحظة نفسها. تعيد ePay.bg إرسال الإشعار.

الطلب بحالة قيد الانتظار بعد الدفع: اقرأ ملاحظة الطلب. تغيّر الإجمالي أو العملة بعد طلب الدفع، أو أُجري الطلب في الوضع الآخر أو بُدّل الوضع لاحقًا، أو تغيّرت طريقة الدفع، أو كان الطلب قد أُلغي. تحقق من الدفعة في لوحة تاجر ePay.bg.

تغيّرت بادئة الفاتورة عند الحفظ: يجوز أن تحتوي البادئة على أرقام فقط، حتى 10. تُحذف الأحرف الأخرى.

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

للمطورين: يذكر ملف readme المرشّح epay_bp_form_fields، مثلًا لاستخدام صفحة البطاقة المباشرة (PAGE=credit_paydirect).

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

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

ePay.bg علامة تجارية لمالكها. هذه الإضافة غير تابعة لـ ePay.bg ولا معتمدة منها.