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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

6. فعّل Enable/Disable وانقر Save. ضع طلبًا تجريبيًا في وضع الاختبار، ثم أوقف Test Mode.

عند التثبيت تنشئ الوحدة حالة الطلب ePay.bg payment on hold. تعرض PrestaShop وحدة الدفع الجديدة لكل العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعداد

جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. يحفظ كل زر Save الصفحة كاملة. وتعرض الصفحة فوق الحقول خطأ إذا لم تكن العملة الافتراضية للمتجر 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: يفعّل وضع الاختبار. يُحوَّل العملاء إلى بيئة 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.

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. تُحذف المسافات وفواصل الأسطر في المفاتيح الملصوقة عند الحفظ.

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

Payment notifications (IPN)

يُخبر الإشعار متجرك بأن طلب الدفع قد دُفع أو رُفض أو انتهت مدته. يُظهر الحقل Notification URL العنوان الذي يجب إدخاله باسم URL for receiving notifications في ملف التاجر على ePay.bg، للفعلي والتجريبي. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_epaybg_gateway/notify، وقد يتضمن رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات. لا تُنشأ الطلبات إلا بهذه الإشعارات الموقّعة؛ وعودة العميل إلى المتجر لا تنشئ طلبًا ولا تدفعه.

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

تُرفض الإشعارات التي لا تحمل مجموع تحقق صالحًا، وتستمر ePay.bg في إرسالها. يُتحقق من مجموع التحقق بالمفتاح السري لكل وضع يملك مفتاحًا، لذلك تبقى المدفوعات التي بدأت قبل التبديل بين الاختبار والفعلي مؤكدة. يجب أن تصل الدفعة في الوضع نفسه الذي أُرسل فيه طلبها؛ وإلا يُنقل الطلب إلى ePay.bg payment on hold. ومن دون عنوان الإشعارات في ملف التاجر لا يُنشأ أي طلب.

Payment request

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: حالة الطلب التي تُعيَّن بعد الدفع الناجح.

Advanced

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

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والسجل. تبقى سجلات مدفوعات ePay.bg وحالة الطلب ePay.bg payment on hold والطلبات محفوظة دائمًا. الافتراضي: إيقاف.

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُنشأ الطلب إلا عند وصول إشعار ePay.bg الموقّع. إذا كان قد وصل، يرى العميل صفحة تأكيد الطلب القياسية. وإذا لم يصل، تعرض صفحة Payment confirmation النص Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. مع الزرين Check again وBack to checkout.

إذا ألغى العميل في ePay.bg يعود إلى صفحة الدفع مع الرسالة The ePay.bg payment was cancelled. You can try again or choose another payment method. وإذا أبلغت ePay.bg بأن الطلب رُفض أو انتهى، فالرسالة هي The payment was not completed. You can try again or choose another payment method. تبقى السلة محفوظة. وأي محاولة جديدة للسلة نفسها تستخدم رقم الفاتورة نفسه.

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

يعمل الإشعار حتى عندما يكون المتجر في وضع الصيانة، ولا يتأثر بقيود الدول في متجرك.

تقبل الوحدة المدفوعات لمرة واحدة عبر ePay.bg فقط. لا توجد استردادات من PrestaShop، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا رموز الدفع النقدي EasyPay أو B-Pay.

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى ePay.bg ولم يدفع، أو لم يصل الإشعار بعد، أو أبلغت ePay.bg بأن الطلب رُفض أو انتهى. لا توجد سوى السلة.

Payment accepted, Delivered or ePay.bg payment on hold: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. يُسجَّل الدفع مع STAN كمعرّف للمعاملة (أو برقم الفاتورة إذا لم يوجد STAN)، وتعرض ملاحظة رقم الفاتورة وتاريخ الدفع وSTAN ورمز BORICA.

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

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

كتلة الدفع في ePay.bg

تعرض صفحة الطلب كتلة ePay.bg payment تتضمن الفاتورة والمبلغ المطلوب والعملة ونتيجة الإشعار وتاريخ الدفع وSTAN ورمز BORICA، وشارة Test mode للمدفوعات التجريبية، وملاحظات ePay.bg notes الخاصة بالطلب.

الاستردادات

الاستردادات من PrestaShop غير متاحة، لأن WEB API الخاصة بـ ePay.bg لا يحتوي على استدعاء للاسترداد. استرد الدفعة في لوحة تاجر ePay.bg وحدّث الطلب في PrestaShop يدويًا.

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

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

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

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

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

لا تظهر ePay.bg في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن MIN والمفتاح السري للوضع المختار مُدخلان، وأن عملة السلة BGN أو EUR أو USD. تعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: يُنشأ الطلب فقط عبر إشعار ePay.bg. تحقق من إدخال عنوان الإشعارات في ملف التاجر على ePay.bg للوضع الذي تستخدمه (التجريبي أو الفعلي)، تمامًا كما يظهر في Notification URL، ومن صحة المفتاح السري لذلك الوضع. انظر حقل Log في صفحة الوحدة؛ وفعّل Logging لرؤية كل إشعار.

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

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

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

يجيب الإشعار بـ STATUS=ERR: خطأ مؤقت، مثلًا إشعاران للسلة نفسها في اللحظة نفسها، أو تعذر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). تُرسل ePay.bg الإشعار مرة أخرى. السبب موجود في السجل.

يعرض عنوان الإشعارات ERR=Method not allowed in the browser في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الصادرة من ePay.bg فقط.

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

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

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

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

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

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