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

المتطلبات

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

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

العملة: يجب أن تكون السلة بعملة PLN أو EUR أو GBP أو CZK. وبالعملات الأخرى تُخفى طريقة الدفع في صفحة إتمام الشراء. تُحصَّل قيمة السلة بعملتها الخاصة؛ ولا تُحوِّل الوحدة العملات.

حساب Przelewy24: تحتاج إلى حساب تاجر لدى Przelewy24 وبيانات API الخاصة به: Merchant ID، ومفتاح API (ويُسمّى report key في لوحة Przelewy24)، ومفتاح CRC، وإذا كان لمتجرك معرّف خاص به، فـ POS ID (Shop ID). تجدها في لوحة التاجر لدى Przelewy24 على panel.przelewy24.pl، ضمن My data > API data and configuration. تأتي مفاتيح sandbox من حساب sandbox منفصل على sandbox.przelewy24.pl/panel. لا يلزم إعداد أي شيء آخر في لوحة Przelewy24: تُرسل الوحدة عنوان الإشعار الخاص بها مع كل دفعة. ويجب أن يكون متجرك متاحًا من الإنترنت، لأن Przelewy24 يرسل إليه إشعارات الدفع.

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

التثبيت

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

2. عند اكتمال الرفع، اضغط على Configure، أو اعثر لاحقًا على VibeFox Przelewy24 Payment في قائمة الوحدات واضغط على Configure.

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

4. أدخل مفاتيح sandbox (Merchant ID ومفتاح API ومفتاح CRC؛ وPOS ID فقط إذا كان يختلف عن Merchant ID)، وفعّل Enable/Disable، واضغط على Save، ونفّذ دفعة تجريبية في وضع sandbox.

5. أدخل مفاتيح Live، وألغِ تفعيل Test Mode، ثم اضغط على Save لقبول المدفوعات الحقيقية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Przelewy24 Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. تعرض الصفحة فوق الحقول تحذيرات عند نقص شيء ما. أثناء تفعيل sandbox: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. وعندما تكون مفاتيح الوضع الحالي غير مكتملة: Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout. (أو الرسالة نفسها لمفاتيح Live). وإذا لم يقبل Przelewy24 العملة الافتراضية لمتجرك، يذكر التحذير هذه العملة والعملات المدعومة. وبعد الحفظ تتبع التحذيرات الوضع والمفاتيح الجديدة فورًا. وتُزال المسافات وفواصل الأسطر المنسوخة مع المفاتيح من لوحة Przelewy24 عند الحفظ.

Przelewy24

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة إتمام الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Przelewy24. مطلوب: الحفظ بعنوان فارغ يعرض Enter a title for the payment method.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة إتمام الشراء. الافتراضي: Pay with BLIK, online bank transfer or card via Przelewy24.

بيانات اعتماد API

يشرح هذا القسم مكان العثور على المفاتيح (My data > API data and configuration في لوحة التاجر لدى Przelewy24)، ويحتوي على روابط إلى panel.przelewy24.pl وsandbox.przelewy24.pl/panel.

Test Mode: يستخدم sandbox الخاص بـ Przelewy24 (sandbox.przelewy24.pl) ومفاتيح Sandbox. لا يُخصم أي مبلغ حقيقي. ألغِ تفعيله لقبول المدفوعات الحقيقية على secure.przelewy24.pl بمفاتيح Live. الافتراضي: مفعّل. وأثناء تفعيله يرى العملاء Sandbox mode - no real money is charged أسفل طريقة الدفع.

مفاتيح Live

Live Merchant ID: معرّف التاجر لدى Przelewy24، أرقام فقط.

Live POS ID (optional): Shop ID (posId). اتركه فارغًا إذا كان مطابقًا لـ Merchant ID.

Live API key (report key): مفتاح API من لوحة Przelewy24. يُستخدم للمصادقة على واجهة API.

Live CRC key: يُستخدم لتوقيع الطلبات المرسلة إلى Przelewy24 والتحقق من توقيع إشعارات Przelewy24.

مفاتيح Sandbox

Sandbox Merchant ID: Merchant ID لحساب sandbox الخاص بك لدى Przelewy24.

Sandbox POS ID (optional): Shop ID (posId) لحساب sandbox. اتركه فارغًا إذا كان مطابقًا لـ Merchant ID.

Sandbox API key (report key): مفتاح API لحساب sandbox.

Sandbox CRC key: مفتاح CRC لحساب sandbox، ويُستخدم لتوقيع الطلبات والتحقق من إشعارات sandbox.

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

Clear saved secrets: ضع علامة على مفتاح واضغط على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

مفاتيح Live ومفاتيح sandbox مختلفة. يجب أن يحتوي Merchant ID وPOS ID على أرقام فقط؛ وإلى أن يُدخل Merchant ID ومفتاح API ومفتاح CRC للوضع الحالي، لا تظهر طريقة الدفع في صفحة إتمام الشراء. تُتحقق الدفعة التي بدأت في وضع ما وتُسترد دائمًا بمفاتيح ذلك الوضع، حتى بعد التبديل، لذلك احتفظ بمفاتيح الوضع القديم طالما كانت دفعاته مفتوحة أو قد تحتاج إلى استرداد.

إشعارات الدفع

Notification URL: العنوان الذي يستقبل إشعارات الدفع من Przelewy24. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_przelewy24_payment/notify، وقد يتضمن رمز لغة مثل /en/. تُرسل الوحدة هذا العنوان إلى Przelewy24 مع كل دفعة وكل استرداد، لذلك لا يلزم ضبط أي شيء في لوحة Przelewy24. ويجب أن يكون العنوان متاحًا من الإنترنت: لا يجوز وضع جدار حماية أو مصادقة HTTP أمامه. يواصل العمل أثناء وضع الصيانة للمتجر، ولا يُحجب بقيد الدول الخاص بمتجرك. وبدون إشعارات تُؤكَّد الدفعة عندما يعود العميل إلى المتجر (انظر إتمام الشراء)؛ وإذا لم يعد العميل، فلن يُنشأ أي طلب.

متقدم

Debug Log: يكتب الأحداث التقنية (أرقام السلال، ومعرّفات معاملات P24، والأخطاء) في logs/wc_p24_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. وتُسجَّل الأخطاء والتحذيرات، مثل الإشعارات المرفوضة أو فشل التحقق أو الاسترداد، دائمًا؛ فعّل المفتاح لتسجيل كل خطوة أيضًا. لا تُسجَّل المفاتيح ولا أجسام الطلبات ولا البيانات الشخصية أبدًا. الافتراضي: معطّل.

Log: يعرض حجم السجل وآخر مدخلاته. اضغط على Clear log لتفريغه.

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها والسجل. ولا تُحذف الطلبات وبيانات دفعها لدى Przelewy24 أبدًا. الافتراضي: معطّل.

إتمام الشراء

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Przelewy24 مع شعار P24) ويؤكد الطلب. تسجّل الوحدة معاملة Przelewy24 بإجمالي السلة بعملة السلة، مع بريد العميل واسمه ودولة الفوترة، والوصف Cart # مع رقم السلة واسم متجرك. ولكل محاولة دفع معرّف جلسة خاص بها. يُنقل العميل إلى صفحة دفع Przelewy24 فيدفع عبر BLIK أو التحويل المصرفي الإلكتروني أو البطاقة أو أي طريقة أخرى مفعّلة لحسابك لدى Przelewy24. وتظهر صفحة الدفع بلغة سلة العميل إذا كانت Przelewy24 تدعمها، وإلا فبالإنجليزية. ولا يوجد طلب في هذه المرحلة.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Przelewy24. ترسل Przelewy24 إلى متجرك إشعارًا موقّعًا. وتتحقق الوحدة من التوقيع باستخدام مفتاح CRC وMerchant ID وPOS ID؛ ومن أن الجلسة سُجّلت لهذه السلة وفي الوضع نفسه؛ ومن أن المبلغ والعملة يطابقان محاولة الدفع وإجمالي السلة الحالي. عندها فقط تتحقق من المعاملة لدى Przelewy24 (لا تُضيف Przelewy24 إلى الرصيد إلا المدفوعات المتحقق منها) وتُنشئ الطلب بحالة Payment accepted. وتُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا.

بعد الدفع يعود العميل إلى متجرك. وإذا لم يكن الإشعار قد وصل بعد، تطلب الوحدة من Przelewy24 حالة المعاملة عبر طلب موثَّق من الخادم إلى الخادم (مرة واحدة كحد أقصى كل 10 ثوانٍ لكل سلة)، وتطبّق الفحوص نفسها. ولا تُعلِّم صفحة العودة وحدها الطلب كمدفوع أبدًا. وعند تأكيد الدفع يرى العميل صفحة تأكيد الطلب القياسية. وما دام الدفع غير مؤكد، تعرض صفحة Payment confirmation الرسالة We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: مع زر Check again وزر Pay again الذي يفتح صفحة إتمام الشراء. وتبقى السلة محفوظة، ويُقبل أيضًا أي دفع يتم لاحقًا من صفحة Przelewy24 أقدم لهذه السلة نفسها. وإذا كان الطلب في الانتظار، تعرض صفحة التأكيد Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

إذا تعذّر بدء الدفع، يبقى العميل في صفحة إتمام الشراء مع رسالة قصيرة: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (يُكتب السبب في السجل)، وPayment gateway is not configured properly. Please contact the administrator. (مفاتيح الوضع الحالي ناقصة)، أو رسالة تفيد بأن Przelewy24 لا يستطيع قبول الدفعات بعملة السلة، أو The order total must be greater than zero. ولا تُرسل السلة التي لها طلب بالفعل إلى Przelewy24 مرة أخرى؛ إذ ينتقل العميل إلى تأكيد الطلب.

لا تتضمن الوحدة بطاقات محفوظة أو دفعًا بنقرة واحدة، ولا اشتراكات أو مدفوعات متكررة، ولا اختيارًا لطريقة الدفع P24 (مثل حقل رمز BLIK) في صفحة إتمام الشراء، ولا أدوات تقسيط، ولا ترسل محتويات السلة إلى Przelewy24.

الطلبات والاستردادات

حالات الطلب

No order yet: أُرسل العميل إلى Przelewy24 ولم يدفع، أو أن الدفع لم يُؤكَّد بعد. لا توجد سوى السلة.

Payment accepted: تم التحقق من الدفع. يُسجَّل الدفع برقم طلب P24 كمعرّف للمعاملة، وتعرض ملاحظة رقم طلب P24 والمبلغ والوضع. ويُطبَّق كل دفع مرة واحدة فقط.

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

Refunded: تم استرداد الدفع بالكامل عبر الوحدة.

إذا وصل دفع ثانٍ لسلة طلبها مدفوع أو مُسترد بالفعل (رابط دفع قديم، أو تبويبان في المتصفح)، فلا يُؤكَّد هذا الدفع، لذلك لا يضيفه Przelewy24 إلى الرصيد. وتطلب ملاحظة على الطلب منك التحقق منه في لوحة Przelewy24 وردّه إلى المشتري عند الحاجة.

كتلة دفع Przelewy24

تعرض صفحة الطلب كتلة Przelewy24 payment تتضمن رقم طلب P24 والجلسة والبيئة (شارة Sandbox لمدفوعات sandbox) وحالة الدفع وطريقة التحقق منه (الإشعار أو العودة)، والمبالغ المدفوعة والمستردة، ونموذج الاسترداد، وسجل الاستردادات، وPayment notes الخاصة بالطلب.

الاستردادات

في كتلة Przelewy24 payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واكتب سببًا اختياريًا، ثم اضغط على Refund via Przelewy24. أكّد السؤال Refund this amount through Przelewy24? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة، حتى المبلغ الذي لم يُسترد بعد. ويلزمك حق تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات الوحدات. يُرسل الاسترداد في الوضع الذي تمّت فيه الدفعة (sandbox أو live)، لذلك يجب أن تكون مفاتيح ذلك الوضع مضبوطة. وتصبح الاستردادات متاحة بعد أن يتحقق Przelewy24 من الدفع.

تعالج Przelewy24 الاستردادات بشكل غير متزامن. تعرض الكتلة Refund of … requested at Przelewy24. The result will be added as an order note.، ويظهر في سجل الاستردادات الحالة requested وتُضاف ملاحظة. تصل النتيجة لاحقًا إلى عنوان الإشعار: تصبح الحالة completed مع الملاحظة Przelewy24: refund of … completed.، أو rejected مع ملاحظة تفيد بأن المال لم يُعَد إلى المشتري. يضع الاسترداد الكامل الطلب على Refunded عند طلبه؛ ولا يغيّر الاسترداد الجزئي الحالة. وإذا رُفض استرداد، تحقق منه في لوحة Przelewy24؛ ولا تُعاد حالة الطلب تلقائيًا.

إذا لم يقبل Przelewy24 طلب الاسترداد، تعرض الكتلة Przelewy24 refund failed: مع السبب، ولا يُسجَّل أي استرداد. ولا تُنشئ الوحدة إشعارات ائتمان. وأزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد المال عبر Przelewy24، والاستردادات التي تُجرى مباشرة من لوحة Przelewy24 لا تُضاف إلى الطلب.

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

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

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

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

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

لا يظهر Przelewy24 في صفحة إتمام الشراء: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Merchant ID ومفتاح API ومفتاح CRC للوضع الحالي مُدخلة (مفاتيح Sandbox طالما Test Mode مفعّل، وإلا مفاتيح Live؛ وMerchant ID وPOS ID أرقام فقط)، وأن عملة السلة هي PLN أو EUR أو GBP أو CZK. وتذكر التحذيرات أعلى الإعدادات المشكلة. وفي Payment > Preferences تحقق من أن الوحدة مسموحة لعملة السلة ولدولة العميل ولمجموعة العميل. ويستطيع المطورون تغيير قائمة العملات بالخطاف actionWcpPrzelewy24SupportedCurrencies (العملات ذات الخانتين العشريتين المفعّلة لحسابك لدى Przelewy24 فقط).

تمت الدفعة لكن لم يُنشأ أي طلب: لم يصل إشعار Przelewy24 إلى متجرك، ولم يعد العميل إلى المتجر. تحقق من أن Notification URL متاح من الإنترنت (لا يوجد جدار حماية أو مصادقة HTTP أمامه)، وأن Merchant ID وPOS ID ومفتاح CRC لوضع الدفعة صحيحة. وتُكتب الإشعارات المرفوضة في السجل حتى مع إيقاف Debug Log؛ راجع حقل Log في صفحة الوحدة.

كيف يردّ المتجر على الإشعارات: يُرد على الإشعار المعالَج أو المكرر أو المجهول برمز HTTP 200. وفي غير ذلك ترسله Przelewy24 لاحقًا: 400 (بيانات مفقودة أو غير سليمة)، و401 Invalid signature (مفتاح CRC خاطئ، أو Merchant ID أو POS ID مختلف)، و401 Invalid signature for this payment (إشعار وُقّع بمفاتيح وضع غير وضع الدفعة)، و405 (ليس طلب POST)، و500 Verification failed (فشل التحقق لدى Przelewy24؛ تُضاف ملاحظة إلى الطلب مرة واحدة إن وُجد)، و500 Order could not be created (مثلًا الوحدة معطّلة؛ والإشعار التالي ينشئ الطلب دون تحقق جديد)، و503 Busy, retry later (كانت السلة تُؤكَّد بطلب آخر في اللحظة نفسها).

يرى العميل Payment error: Przelewy24 could not start the payment: رفض Przelewy24 المعاملة، عادةً بسبب مفاتيح خاطئة للوضع الحالي (مفاتيح sandbox تعمل فقط في وضع sandbox، ومفاتيح Live فقط في وضع live). وخطأ Przelewy24 موجود في السجل.

الطلب في حالة Przelewy24 payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Przelewy24 payment. كان المبلغ أو العملة مختلفين عن السلة، أو وصلت الدفعة لطلب أُلغي. تحقق من الدفعة في لوحة Przelewy24، ثم عالج الطلب أو استرد الدفعة.

فشل الاسترداد: This order has no verified Przelewy24 payment. Cannot process refund. تعني أن الطلب لم يُدفع بدفعة Przelewy24 متحقق منها. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (أو الرسالة نفسها لـ Live) تعني أن مفاتيح وضع الدفعة قد حُذفت؛ أدخلها من جديد. Invalid refund amount تعني أن المبلغ فارغ أو ليس رقمًا أو يتجاوز المبلغ الذي لم يُسترد بعد.

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

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

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