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

المتطلبات

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

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

حساب EveryPay: تحتاج إلى اسم مستخدم API وسر API واسم حساب المعالجة الخاص بمتجرك. تجدها في EveryPay Merchant Portal، في إعدادات متجرك: بوابة التجربة (demo) لوضع الاختبار، والبوابة الحية لمدفوعات الإنتاج الفعلية. بيانات اعتماد الاختبار والإنتاج منفصلة. كما تضبط عنوان رد الاتصال (callback) الخاص بمتجرك في البوابتين (انظر الإعدادات).

عملة المتجر: يحدد حساب المعالجة العملة المخصومة، فمثلًا يخصم EUR3D1 بعملة EUR. وتُعرض طريقة الدفع فقط للسلال التي تستخدم هذه العملة.

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

التثبيت

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

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

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

4. أدخل اسم مستخدم API الخاص بالاختبار وسر API الخاص بالاختبار واسم حساب المعالجة من بوابة Merchant Portal التجريبية. أبقِ Test Mode مفعّلًا.

5. انسخ عنوان رد الاتصال (callback) المعروض في صفحة الإعدادات والصقه في Callback notification URL لمتجرك في Merchant Portal.

6. فعّل Enable/Disable، وانقر على Save، ونفّذ طلب اختبار. عند عمل كل شيء، أدخل بيانات اعتماد الإنتاج، واضبط عنوان رد الاتصال في البوابة الحية أيضًا، وأوقف Test Mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox EveryPay Payment > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. فوق الحقول، تعرض الصفحة وضع الاختبار مفعّل: تُرسل المدفوعات إلى بيئة EveryPay التجريبية، ولا يُخصم أي مبلغ حقيقي. ما دام وضع الاختبار مفعّلًا. وتحذّرك عندما تكون طريقة الدفع مفعّلة لكن اسم مستخدم API أو سر API أو حساب المعالجة للوضع الحالي غير موجود (عندها تُخفى طريقة الدفع عند الدفع)، وعندما يخصم حساب المعالجة عملة غير العملة الافتراضية للمتجر. تُحذف المسافات وفواصل الأسطر الملصوقة مع بيانات الاعتماد عند الحفظ.

EveryPay

Enable/Disable: Enable EveryPay payment gateway يُفعّل طريقة الدفع أو يُوقفها. الافتراضي: off.

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

Description: النص المعروض أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely by card or bank link on the EveryPay payment page.

حساب EveryPay

يظهر اسم مستخدم API وسر API واسم حساب المعالجة في EveryPay Merchant Portal (إعدادات المتجر): بوابة التجربة (demo) لوضع الاختبار، والبوابة الحية لمدفوعات الإنتاج. يحتوي القسم على روابط لكلتا البوابتين.

Test Mode: عند التفعيل، تُرسل المدفوعات إلى بيئة EveryPay التجريبية ببيانات اعتماد الاختبار. ولا يُخصم أي مبلغ حقيقي. الافتراضي: on. وما دام مفعّلًا، يرى العملاء أسفل طريقة الدفع العبارة وضع الاختبار: بيئة EveryPay التجريبية، ولا يُخصم أي مبلغ حقيقي.

Test API Username: اسم مستخدم API لبيئة التجربة.

Test API Secret: سر API لبيئة التجربة.

Live API Username: اسم مستخدم API للبيئة الحية.

Live API Secret: سر API للبيئة الحية.

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

Clear saved API secrets: حدّد سرًّا ثم انقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

Processing Account Name: حساب المعالجة في EveryPay، مثل EUR3D1. يحدد الحساب العملة المخصومة: تُعرض طريقة الدفع فقط للسلال بتلك العملة. ويُستخدم اسم الحساب نفسه في الوضعين.

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

يُخبر رد الاتصال متجرك بأن الدفع قد اكتمل، لتُنشأ الطلبات حتى لو أغلق العميل المتصفح. انسخ العنوان المعروض في Callback notification URL إلى حقل Callback notification URL لمتجرك في EveryPay Merchant Portal، سواء للتجربة أو الإنتاج. وباستخدام عناوين URL الودية يبدو هكذا: https://your-shop/module/wcp_everypay_payment/callback. انسخ العنوان تمامًا كما يظهر في الإعدادات. طلب الدفع لا يحمل عنوان رد اتصال، لذلك يجب ضبطه في البوابة.

يحمل رد الاتصال مراجع الدفع فقط. عند وصوله، تطلب الوحدة من واجهة EveryPay البرمجية حالة الدفع باستخدام بيانات اعتماد البيئة التي أُنشئ فيها الدفع، وتتحقق من أن الرد يخص هذه السلة. تُرفض ردود الاتصال الخاصة بدفع لم ينشئه متجرك دون طلب إلى EveryPay. وبدون رد الاتصال، يُنشأ الطلب عندما يعود العميل إلى المتجر بعد الدفع، أو عندما تعيد EveryPay إرسال رد الاتصال.

متقدم

Debug log: يسجّل أحداث الدفع في logs/wc_evp_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون هذا الخيار متوقفًا. ولا تُسجَّل أسرار API أو بيانات البطاقات أو بريد العملاء الإلكتروني أبدًا. الافتراضي: off.

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

Uninstall: يحذف إعدادات البوابة والسجلات عند إلغاء تثبيت الوحدة. وتُحفظ بيانات الدفع من EveryPay للطلبات دائمًا. الافتراضي: off.

الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا EveryPay) ويؤكد. تُنشئ الوحدة دفعة EveryPay لمرة واحدة بمبلغ السلة الإجمالي بعملة السلة، مع بريد العميل وعنوان الفوترة، وتُرسل العميل إلى صفحة الدفع الخاصة بـ EveryPay. تتبع لغة هذه الصفحة لغة المتجر (الإنجليزية أو الإستونية أو الروسية أو اللاتفية أو الليتوانية أو الفنلندية أو الألمانية؛ وفي غير ذلك الإنجليزية). وهناك يدفع العميل بإحدى طرق الدفع المفعّلة لحساب EveryPay الخاص بك. لا يوجد طلب في هذه المرحلة.

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد EveryPay ذلك: تطلب الوحدة من واجهة EveryPay البرمجية حالة الدفع عند العودة وعند رد الاتصال. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة. وإذا كانت EveryPay ما زالت تعالج الدفع، أو تعذّر الوصول إلى واجهتها البرمجية في تلك اللحظة، تظهر صفحة Payment confirmation برسالة تقوم EveryPay بتأكيد دفعتك. ستتلقى رسالة بريد إلكتروني فور تأكيد الطلب. وزر Check again؛ وينشئ رد الاتصال الطلب فور تأكيد EveryPay للدفع.

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

إذا تعذّر على EveryPay بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل EveryPay غير متاحة مؤقتًا. يرجى المحاولة مرة أخرى بعد قليل أو اختيار طريقة دفع أخرى. وتفاصيل ذلك موجودة في السجل.

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

تقبل الوحدة المدفوعات لمرة واحدة فقط. لا تتوفر الاستردادات أو التحصيلات من PrestaShop، ولا البطاقات المحفوظة أو المدفوعات بنقرة واحدة، ولا الاشتراكات أو المدفوعات المتكررة، ولا حقول البطاقة المدمجة، ولا تعدد العملات.

الطلبات

حالات الطلب

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

Payment accepted: أبلغت EveryPay بأن الدفع قد تمت تسويته أو تفويضه. يُسجَّل الدفع بمرجع الدفع الخاص بـ EveryPay كمعرّف للمعاملة، وتعرض ملاحظة المبلغ والعملة والمرجع. وبالنسبة للدفع المفوَّض، تنص الملاحظة على أن المبلغ محجوز: إذا لم يكن حسابك يحصّل تلقائيًا، فحصّل الدفع في EveryPay Merchant Portal. وعند تسوية الدفع لاحقًا، تنبّه ملاحظة واحدة إلى ذلك.

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

إذا اكتمل دفع ثانٍ لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد الدفعة المكررة في EveryPay Merchant Portal.

كتلة الدفع في EveryPay

تعرض صفحة الطلب كتلة EveryPay payment تضم كل محاولات الدفع من EveryPay لهذا الطلب: التاريخ، ومرجع الدفع (مع شارة Test mode لمدفوعات الاختبار)، ومرجع الطلب، والمبلغ، وحالة EveryPay، والنتيجة. وأسفلها EveryPay notes الخاصة بالطلب، الأحدث أولًا.

Check EveryPay payment status: يتحقق الزر في الكتلة من كل دفع من EveryPay للطلب عبر الواجهة البرمجية، من الأحدث إلى الأقدم، ويطبّق النتيجة كما ذُكر أعلاه، ويضيف ملاحظة واحدة بحالة كل دفع. وتظهر النتيجة في الكتلة. تحتاج إلى صلاحية تعديل الطلبات؛ ولا تحتاج إلى الوصول إلى صفحات الوحدات. استخدمه عندما لا يصل رد الاتصال أبدًا، مثلًا لرؤية تحصيل أو استرداد لاحق.

الاسترداد

الاسترداد من PrestaShop غير مدعوم. استرد المبلغ في EveryPay Merchant Portal، ثم حدّث حالة الطلب في PrestaShop. وعندما تُبلغ EveryPay بأن الدفع قد استُرد أو أُعيد بالخصم، تضيف الوحدة ملاحظة إلى الطلب فقط؛ ولا تتغير حالة الطلب. أما أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب فلا تعيد الأموال عبر EveryPay.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox EveryPay Payment هي أول كتلة في Modules > Module Manager > VibeFox EveryPay Payment > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها السطر Product: presta-payment-everypay والرابط Manage licenses and domains in your account، الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة back office (تشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on متبوعة بتاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

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

بدون مفتاح نشط، لا تُعرض EveryPay للعملاء عند الدفع. وإذا بُدئ الدفع رغم ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يُرجى اختيار طريقة أخرى. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى back office، لذا تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager على علامة التبويب Alerts. الطلبات الحالية لا تتأثر: تبقى الدفعات التي بدأت مؤكدة، وتعمل فحوصات الحالة.

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

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

لا تظهر EveryPay عند الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن اسم مستخدم API وسر API وProcessing Account Name للوضع الحالي مُدخلة، وأن عملة السلة هي عملة حساب المعالجة. وتعرض صفحة الإعدادات تحذيرًا في هذه الحالات. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

تم الدفع لكن لم يُنشأ أي طلب: رد الاتصال لا يعمل. تحقّق من أن عنوان رد الاتصال من الإعدادات مضبوط كـ Callback notification URL في Merchant Portal للوضع الذي تستخدمه (التجربة أو الإنتاج). كما يُنشأ الطلب عندما يعود العميل إلى المتجر بعد الدفع. انظر حقل Log في صفحة الوحدة: تُسجَّل الأخطاء دائمًا.

يرد رد الاتصال بـ Unknown payment أو Unknown payment reference أو Payment does not belong to this order: لم يُنشئ هذا الدفع هذا المتجر أو هذه السلة، أو أن رد EveryPay لا يطابقه. لا يتغير شيء.

يرد رد الاتصال بـ Not configured: بيانات اعتماد البيئة التي أُنشئ فيها الدفع مفقودة، مثل دفعة اختبار بعد إزالة بيانات اعتماد الاختبار. أدخلها من جديد؛ فتعيد EveryPay محاولة رد الاتصال.

يرد رد الاتصال بـ Payment status unavailable أو Busy, please retry أو Order could not be created: تعذّر الوصول إلى واجهة EveryPay البرمجية، أو كان طلب آخر ينشئ الطلب في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). تعيد EveryPay محاولة رد الاتصال. والسبب موجود في السجل.

يرى العميل «EveryPay غير متاحة مؤقتًا»: رفضت EveryPay بيانات الاعتماد أو تعذّر الوصول إليها. تحقّق من اسم مستخدم API وسر API للوضع الحالي.

يرى العميل «طريقة الدفع هذه لا تدعم عملة الطلب»: عملة السلة تختلف عن عملة حساب المعالجة.

يبقى العميل في صفحة Payment confirmation: لم تُكمل EveryPay الدفع بعد. يُنشأ الطلب عبر رد الاتصال، أو عندما ينقر العميل على Check again بعد أن تؤكد EveryPay الدفع.

الطلب في حالة EveryPay payment on hold: اقرأ EveryPay notes في كتلة الطلب. كان المبلغ أو العملة مختلفًا، أو كان الطلب قد أُلغي قبل وصول الدفع. تحقّق من الدفع في Merchant Portal، ثم نفّذ الطلب أو استرد المبلغ يدويًا.

للمطوّرين: يسرد ملف README الخاص بالوحدة الخطافين actionWcpEverypayOneoffRequest (تعديل طلب الدفع) وactionWcpEverypayLocale (تغيير لغة صفحة الدفع).

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

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

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