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

المتطلبات

WordPress: الإصدار 6.0 أو أحدث.

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

PHP: الإصدار 8.0 أو أحدث.

حساب EveryPay: تحتاج إلى اسم مستخدم API وسر API واسم حساب المعالجة لمتجرك الإلكتروني. تجدها في EveryPay Merchant Portal ضمن إعدادات متجرك: البوابة التجريبية (mwt-demo.every-pay.com) لوضع الاختبار، وبوابة الإنتاج (portal.every-pay.eu) للمدفوعات الحقيقية. لبيئتي الاختبار والإنتاج بيانات اعتماد منفصلة. كما تضبط عنوان رد الاتصال (callback URL) لمتجرك في البوابتين (راجع الإعدادات).

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

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

التثبيت

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

2. انقر Activate.

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

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

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

6. انسخ عنوان رد الاتصال المعروض في صفحة الإعدادات إلى Callback notification URL لمتجرك في Merchant Portal.

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

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > EveryPay. وتعرض الصفحة فوق الحقول، ما دام وضع الاختبار مفعّلًا، الرسالة Test mode is on: payments go to the EveryPay demo environment, no real money is charged. وتحذّرك عندما تكون البوابة مفعّلة لكن اسم مستخدم API أو سر API أو حساب المعالجة للوضع الحالي غير مكتمل (وفي هذه الحالة تُخفى طريقة الدفع في صفحة الدفع)، وعندما يخصم حساب المعالجة بعملة مختلفة عن عملة المتجر. وفي قائمة طرق الدفع يُوسم EveryPay بأنه بحاجة إلى إعداد حتى يُهيأ الوضع الحالي. وتُحذف المسافات وفواصل الأسطر الملصوقة مع بيانات الاعتماد عند الحفظ.

عام

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

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

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

حساب EveryPay

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

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

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

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

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

Live API Secret: سر API لبيئة الإنتاج.

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

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

يُخبر رد الاتصال متجرك بأن الدفع قد اكتمل، فتُحدَّث الطلبات حتى لو أغلق العميل المتصفح. انسخ العنوان المعروض في هذا القسم إلى Callback notification URL لمتجرك في EveryPay Merchant Portal، في بيئتي الاختبار والإنتاج. وشكل العنوان هو https://your-site/wc-api/wc_evp_payment/. لا يتضمن طلب الدفع عنوان رد اتصال، لذا يجب ضبطه في البوابة.

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

متقدم

Debug log: Log payment events يكتب أحداث الدفع في WooCommerce > Status > Logs، بالمصدر wcp_everypay_payment. وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل أسرار API ولا بيانات البطاقات أبدًا. الافتراضي: معطّل.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا EveryPay) ويقدّم الطلب. وفي وضع الاختبار تعرض صفحة الدفع TEST MODE: EveryPay demo environment, no real money is charged. وتُنشئ الإضافة دفعة EveryPay لمرة واحدة بمبلغ الطلب الإجمالي، مع البريد الإلكتروني وبيانات الفوترة الخاصة بالعميل، وتوجّه العميل إلى صفحة الدفع الخاصة بـ EveryPay. تتبع لغة الصفحة لغة الموقع (الإنجليزية أو الإستونية أو الروسية أو اللاتفية أو الليتوانية أو الفنلندية أو الألمانية؛ وإلا فالإنجليزية). وهناك يدفع العميل بإحدى الطرق المفعّلة في حساب EveryPay الخاص بك.

بعد الدفع يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد تأكيد EveryPay: تطلب الإضافة من واجهة EveryPay البرمجية حالة الدفع عند عودة العميل وعند رد الاتصال. ويُوجَّه الطلب المدفوع، أو الطلب قيد المراجعة، أو الدفع الذي لا يزال قيد المعالجة، إلى صفحة «تم استلام الطلب».

إذا فشل الدفع، يعود العميل إلى صفحة الدفع (أو صفحة Pay for order) ويرى الرسالة Your EveryPay payment was not successful. Please try again or choose another payment method. وإذا غادر العميل صفحة الدفع دون أن يدفع، فالرسالة هي The EveryPay payment was not completed. You can try again or choose another payment method. وتُنشئ كل محاولة جديدة دفعة EveryPay جديدة؛ وتُحفظ المحاولات السابقة، فيبقى الدفع الذي تم برابط أقدم معترفًا به.

وإذا تعذّر على EveryPay بدء الدفع، يرى العميل رسالة قصيرة، مثل EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. وتفاصيل ذلك موجودة في السجل.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS). والنصوص الظاهرة للعملاء مترجمة إلى الإستونية.

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

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى EveryPay ولم يدفع بعد، أو أن الدفع لا يزال قيد المعالجة.

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

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

Failed: فشلت آخر محاولة دفع لطلب غير مدفوع، أو أُهملت، أو أُلغيت (void). وتعرض الملاحظة السبب الذي ذكرته EveryPay. ويمكن للعميل المحاولة مرة أخرى.

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

Check EveryPay payment status

في شاشة الطلب اختر إجراء الطلب Check EveryPay payment status. تتحقق الإضافة من كل دفعة EveryPay للطلب عبر الواجهة البرمجية، وتطبّق النتيجة كما هو موضح أعلاه، وتضيف ملاحظة بحالة كل دفعة. استخدمه للطلبات التي لم يصل رد الاتصال الخاص بها أبدًا.

الاستردادات

لا تُدعم الاستردادات من WooCommerce. استرد في EveryPay Merchant Portal، ثم اضبط حالة الطلب في WooCommerce. وعندما تبلغ EveryPay بأن الدفع مُسترد أو تم الاعتراض عليه (chargeback)، تضيف الإضافة ملاحظة للطلب فقط؛ ولا تتغير حالة الطلب.

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

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

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

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

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

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

لا يظهر EveryPay في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن اسم مستخدم API وسر API وProcessing Account Name للوضع الحالي مضبوطة، وأن عملة المتجر (في صفحة Pay for order، عملة الطلب) هي عملة حساب المعالجة. وتعرض صفحة الإعدادات تحذيرًا في هذه الحالات.

تم الدفع لكن الطلب يبقى في Pending payment: رد الاتصال لا يعمل. تحقّق من أن عنوان رد الاتصال في الإعدادات مضبوط كـ Callback notification URL في Merchant Portal للوضع الذي تستخدمه (التجريبي أو الإنتاج). ويمكنك أيضًا فتح الطلب وتشغيل Check EveryPay payment status. فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_everypay_payment.

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

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

يرد الاتصال بـ Payment status unavailable أو Busy, please retry: تعذّر الوصول إلى واجهة EveryPay البرمجية، أو كان الطلب يُحدَّث بطلب آخر في الوقت نفسه. وستعيد EveryPay محاولة رد الاتصال.

يرى العميل EveryPay is temporarily unavailable: رفضت EveryPay بيانات الاعتماد أو تعذّر الوصول إليها. تحقّق من اسم مستخدم API وسر API للوضع الحالي.

يرى العميل This payment method does not support the order currency: عملة الطلب تختلف عن عملة حساب المعالجة.

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

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

للمطوّرين، تسرد وثائق الإضافة المرشحات wc_evp_icon وwc_evp_locale وwc_evp_currency_decimals وwc_evp_oneoff_request.

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

إلغاء تفعيل الإضافة يُبقي جميع البيانات. ولحذفها، ألغِ تفعيلها ثم احذفها من صفحة Plugins. ويُحذف دائمًا مفتاح الترخيص وحالته لهذه الإضافة. أما إعدادات البوابة والسجلات فتُحذف فقط إذا كان Uninstall (Delete the gateway settings and logs when the plugin is deleted) مفعّلًا؛ وإلا تبقى لإعادة التثبيت لاحقًا. وتبقى مراجع دفعات EveryPay المخزنة في الطلبات محفوظة دائمًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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