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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

4. أدخل Project ID وProject password من حساب Paysera الخاص بك (انظر الإعدادات).

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

6. فعّل Enable/Disable وانقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Paysera Payment > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول تعرض الصفحة الرسالة Paysera is hidden at checkout until the project ID and the project password are entered. طالما أن أحدهما مفقود، والرسالة Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. طالما أن دفعات الاختبار أو sandbox مفعّلة.

Paysera

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

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

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

مشروع Paysera

تجد معرّف المشروع وكلمة مروره في حساب Paysera الخاص بك ضمن Projects and activities، ثم مشروعك، ثم General project settings.

Callback URL: العنوان الذي تستخدمه Paysera لتأكيد كل دفعة. عند استخدام الروابط الودية يبدو هكذا: https://your-shop/module/wcp_paysera_payment/callback، وقد يتضمن رمز اللغة. يُرسَل تلقائياً مع كل دفعة، لذلك لا يلزم إعداد شيء في Paysera، لكن يجب أن يكون متاحاً من الإنترنت. تُنشأ الطلبات بواسطة هذه الـ callbacks الموقَّعة فقط.

Project ID: المعرّف الرقمي لمشروع Paysera الخاص بك. تُقبل الأرقام فقط: أي قيمة أخرى تعرض الخطأ Project ID must be a number: the numeric ID of your Paysera project. ولا يُحفظ أي شيء.

Project password: كلمة مرور المشروع (sign key). تُوقّع طلبات الدفع وتتحقق من callbacks الخاصة بـ Paysera. لا تُعرض كلمة المرور المحفوظة مرة أخرى. يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved password: ضع علامة على Project password وانقر على Save لحذف كلمة المرور المحفوظة. الحقل الفارغ يُبقي القيمة المحفوظة.

الاختبار

Test payments: يرسل الدفعات في وضع الاختبار، فلا يُخصم أي مبلغ. تعيد Paysera دفعة اختبار ناجحة دون تحصيل أي مبلغ من العميل. فعّل أولاً Allow test payments في إعدادات مشروع Paysera. طالما أن هذا الخيار مفعّل، تُعلِّم دفعات الاختبار الطلبات على أنها مدفوعة؛ وعندما يكون متوقفاً، تضع دفعة الاختبار الطلب في حالة الانتظار. الافتراضي: off. طالما أنه مفعّل، يرى العملاء TEST MODE — no money will be charged. أسفل طريقة الدفع.

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

متقدم

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

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

Delete data: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها والسجل. بيانات الطلبات (الطلبات، وسجلات دفع Paysera، وحالات الطلب) تُحفظ دائماً. الافتراضي: off.

الدفع

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

تؤكد Paysera الدفعة بواسطة callback من الخادم إلى الخادم. لا يُعلَّم الطلب على أنه مدفوع إلا بعد أن تؤكده Paysera بـ callback موقَّع؛ وعودة العميل إلى المتجر لا تنشئ طلباً ولا تدفعه أبداً. عندما يعود العميل بعد الـ callback، تُعرض صفحة تأكيد الطلب القياسية. إذا قبل البنك أمر الدفع لكنه لم يُنفّذه بعد، يُنشأ الطلب في Awaiting Paysera payment وتعرض الصفحة Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. أما الطلب المعلّق فتعرض الصفحة له Your payment is being reviewed. We will contact you if anything else is needed.

إذا عاد العميل قبل وصول الـ callback، تشرح صفحة Payment confirmation أن الطلب سيُنشأ فور تأكيد Paysera للدفع، وتعرض Check again وBack to checkout.

إذا ألغى العميل في نافذة Paysera، يعود إلى صفحة الدفع مع الرسالة The Paysera payment was cancelled. You can try again or choose another payment method. وإذا أفادت Paysera بأن الدفعة لم تُنفَّذ، فالرسالة هي The payment was not completed. You can try again or choose another payment method. تبقى السلة محفوظة في الحالتين. وإذا كان للسلة طلب بالفعل، فإن المحاولة الجديدة تذهب مباشرة إلى تأكيد الطلب بدلاً من دفعة ثانية.

إذا تعذّر بدء الدفع، يبقى العميل في صفحة الدفع مع الرسالة Paysera payments are temporarily unavailable. Please choose another payment method. أو، في حال كان إجمالي الطلب غير صالح، مع الرسالة This order cannot be paid via Paysera. ويُكتب السبب في السجل.

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

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

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى Paysera ولم يصل الـ callback بعد، أو ألغى العميل. لا توجد إلا السلة.

Payment accepted: أكدت Paysera الدفعة بالمبلغ والعملة المطابقين. تُسجَّل الدفعة بمعرّف طلب Paysera كمعرّف للمعاملة، وتعرض ملاحظة الطلب والطريقة، ومعلَّمة بـ (TEST — no money charged) في دفعات الاختبار.

Awaiting Paysera payment: قبلت Paysera أمر الدفع، لكن البنك لم يُنفّذه بعد. ينتقل الطلب إلى Payment accepted عندما تؤكد Paysera الدفعة.

Paysera payment on hold: تحتاج الدفعة إلى مراجعة يدوية. المبلغ المدفوع أو العملة يختلفان عن السلة أو إجمالي الطلب، أو وصلت دفعة TEST بينما Test payments متوقف (لم يُخصم أي مبلغ)، أو أُكدت الدفعة بعد أن ألغاها العميل. لا تُسجَّل الدفعة. تشرح الملاحظة السبب، وكتلة Paysera تطلب منك التحقق من الدفعة في حسابك لدى Paysera، ثم ضبط الطلب على Payment accepted أو إلغاء الطلب واسترداد الدفعة في Paysera.

Cancelled: الدفعة التي تُؤكَّد لاحقاً لطلب ملغى لا تغيّر حالته. تطلب الملاحظة استعادة الطلب (ضبطه على Payment accepted) أو استرداد الدفعة في Paysera. ودفعة TEST لاحقة أو اختلاف في المبلغ لطلب ملغى تضيف ملاحظة فقط.

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

كتلة دفع Paysera

تعرض صفحة الطلب كتلة Paysera payment تتضمن معرّف طلب Paysera (رقم السلة والمحاولة)، ومعرّف طلب Paysera، والبيئة وعلامة TEST payment، وحالة الدفع، والمبالغ المطلوبة والمدفوعة، وطريقة الدفع، وملاحظات الوحدة.

الاسترداد

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

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

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

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

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

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

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

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

يرد callback بـ Invalid signature: Project password لا يطابق المشروع، أو أن الـ callback ليس من Paysera. انسخ كلمة مرور المشروع مرة أخرى. إذا غيّرت المشروع أو كلمة المرور، فلا يمكن التحقق من الدفعات التي بدأت قبل التغيير.

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

يرد callback بـ Order not found: السلة في الـ callback ليس لها دفعة Paysera في هذا المتجر، مثل أن تكون الدفعة قد بدأت في متجر آخر بالمشروع نفسه.

يرد callback بـ Gateway not configured أو Busy أو Temporary error: معرّف المشروع أو كلمة مروره فارغان، أو أن callback آخر للسلة نفسها ما يزال قيد التشغيل، أو تعذّر إنشاء الطلب (مثلاً الوحدة معطّلة). تعيد Paysera محاولة الـ callback. فعّل Debug log لمعرفة السبب.

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

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

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

يرى العميل الرسالة Paysera payments are temporarily unavailable: راجع حقل Log. قد يكون معرّف المشروع أو كلمة مروره فارغين، أو قد يتجاوز أحد عناوين المتجر المرسلة إلى Paysera 255 حرفاً.

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

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

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