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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

مشروع Paysera: تحتاج إلى معرّف المشروع وكلمة مرور المشروع (مفتاح التوقيع) الخاصين بمشروع Paysera. طرق الدفع التي يراها العميل هي الطرق المفعّلة في هذا المشروع. لا يلزم إعداد أي شيء في Paysera من أجل الـ callback: يُرسَل عنوان URL الخاص به مع كل طلب دفع.

موقع متاح: تُدفع الطلبات عبر callback الخاص بـ Paysera، لذلك يجب أن يكون موقعك متاحاً من الإنترنت، وألا يكون خلف تسجيل دخول أو وضع الصيانة أو جدار حماية.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل Project ID وProject password من حسابك في Paysera (راجع الإعدادات).

6. اختياري: فعّل Allow test payments في مشروع Paysera، وTest payments في الملحق لتجربة العملية دون خصم أي مبلغ. أوقفهما قبل أن تبدأ البيع.

7. فعّل Enable/Disable واحفظ.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Paysera. فوق الحقول، تعرض الصفحة يتم إخفاء Paysera في الدفع إلى أن يتم إدخال معرّف المشروع وكلمة مرور المشروع. طالما أن أحدهما مفقود، كما تعرض إشعاراً بأنه لا يتم تحصيل المبالغ من العملاء طالما أن دفعات الاختبار أو sandbox مفعّلة. في قائمة طرق الدفع، يُعلَّم Paysera على أنه بحاجة إلى إعداد إلى أن يُهيَّأ المشروع، ويظهر شارة وضع الاختبار عند تفعيل دفعات الاختبار أو sandbox.

عام

Enable/Disable: Enable Paysera Payment يفعّل طريقة الدفع أو يوقفها. الافتراضي: إيقاف.

Title: اسم طريقة الدفع الذي يظهر عند الدفع. الافتراضي: Paysera.

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via Paysera.

مشروع Paysera

تجد معرّف المشروع وكلمة مرور المشروع في حسابك لدى Paysera، ضمن Projects and activities، ثم مشروعك، ثم General project settings. يعرض هذا القسم عنوان URL الخاص بالـ callback، ويبدو هكذا: https://your-site/wc-api/wc_psr_payment/. يُرسَل تلقائياً مع كل دفعة، ولا يلزم إعداد أي شيء في Paysera.

Project ID: المعرّف الرقمي لمشروع Paysera الخاص بك.

Project password: كلمة مرور المشروع (مفتاح التوقيع). تُستخدم لتوقيع طلبات الدفع والتحقق من callbacks الخاصة بـ Paysera.

الاختبار

Test payments: Send payments in test mode (no money is charged). يعيد Paysera دفعة اختبار ناجحة دون تحصيل مبلغ من العميل. فعّل أولاً Allow test payments في إعدادات مشروع Paysera. طالما أن هذا الخيار مفعّل، تُعلِّم دفعات الاختبار الطلبات على أنها مدفوعة؛ وعند إيقافه لا تدفع دفعة الاختبار أي طلب أبداً. الافتراضي: إيقاف.

Environment: الوجهة التي يُنقل إليها العميل. أبقِ Production لمشروع Paysera عادي، بما في ذلك دفعات الاختبار. الافتراضي: Production.

متقدم

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

Delete data: Delete the plugin settings and logs when the plugin is deleted. إلغاء تفعيل الملحق لا يحذف أي شيء. بيانات الطلبات تبقى محفوظة دائماً. الافتراضي: إيقاف.

الدفع

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

بعد الدفع يعود العميل إلى صفحة استلام الطلب. لا يُعلَّم الطلب على أنه مدفوع إلا عند وصول callback الموقَّع من Paysera؛ أما عودة العميل فلا تدفع أي طلب أبداً.

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

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

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

الطلبات

حالات الطلب

Pending payment: نُقل العميل إلى Paysera ولم يصل الـ callback بعد.

Processing: أكّد Paysera الدفع (الحالة 1). الطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل تنتقل إلى حالة مكتمل، وهي الافتراضية في WooCommerce. تعرض ملاحظة الطلب طلب Paysera وطريقة الدفع. معرّف المعاملة هو معرّف طلب Paysera.

On hold: قَبِل Paysera أمر الدفع لكنه لم يُنفّذه بعد (الحالة 2)، ويكتمل الطلب عندما يؤكد Paysera الدفع؛ أو أن المبلغ أو العملة المدفوعة تختلف عن الطلب (ملاحظة amount/currency mismatch)؛ أو وصلت دفعة TEST أثناء إيقاف دفعات الاختبار، ولذلك لم يُخصم أي مبلغ. تشرح ملاحظة الطلب السبب.

Cancelled: ألغى العميل في نافذة Paysera، أو ألغيت أنت الطلب، أو ألغاه انتهاء مهلة حجز المخزون. الدفع المؤكد لاحقاً لطلب ملغى لا يغيّر حالته: تطلب منك ملاحظة استعادة الطلب (بتعيينه إلى Processing) أو استرداد الدفعة في Paysera.

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

المبالغ المستردة

لا تُدعم عمليات الاسترداد من WooCommerce: بروتوكول نافذة الدفع الخاصة بـ Paysera لا يحتوي على واجهة برمجية للاسترداد. أجرِ عمليات الاسترداد من حسابك في Paysera. عندما يُبلغ Paysera عن استرداد، تُضاف إلى الطلب ملاحظة بالمبلغ المسترد، ولا تتغير حالة الطلب. سجّل الاسترداد يدوياً في WooCommerce إن لزم الأمر.

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

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

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

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

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

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

لا يظهر Paysera في الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن كلاً من Project ID وProject password مُدخل. تعرض صفحة الإعدادات تحذيراً طالما أن أيّاً منهما مفقود.

تمت عملية الدفع لكن الطلب ما زال في Pending payment: يُدفع الطلب عبر callback من Paysera، وليس عبر عودة العميل. تحقق من أن موقعك متاح من الإنترنت عند عنوان URL الخاص بالـ callback المعروض في الإعدادات (وليس خلف تسجيل دخول أو وضع صيانة أو جدار حماية)، وراجع WooCommerce > Status > Logs، المصدر wcp_paysera_payment.

يرد callback بـ Invalid signature: Project password لا يطابق المشروع، أو أن الـ callback ليس من Paysera. أعد نسخ كلمة مرور المشروع.

يرد callback بـ Project ID mismatch: Project ID في الإعدادات يختلف عن المشروع الذي أجرى الدفع.

يرد callback بـ Gateway not configured أو Busy: معرّف المشروع أو كلمة المرور فارغ، أو أن callback آخر للطلب نفسه ما زال قيد التنفيذ. يعيد Paysera المحاولة.

يرفض Paysera نافذة الدفع أو يقول إن المشروع غير موجود: تحقق من Environment. يعمل مشروع Paysera العادي مع Production فقط؛ أما Sandbox فيحتاج إلى مشروع أُنشئ في بيئة sandbox الخاصة بـ Paysera.

دفعة الاختبار لا تدفع الطلب: تدفع دفعة TEST الطلب فقط طالما أن Test payments مفعّل. وإلا يُوضع الطلب في الانتظار مع ملاحظة تفيد بأنه لم يُخصم أي مبلغ. فعّل أيضاً Allow test payments في مشروع Paysera.

لا توجد أيقونة عند الدفع: لا يعرض الملحق أيقونة افتراضياً. يمكن للمطوّرين تعيين أيقونة باستخدام الفلتر wc_psr_gateway_icon.

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

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

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

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

Paysera هي علامة تجارية تخص مالكها. هذا الملحق غير تابع لـ Paysera ولا تعتمده.