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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

حساب Przelewy24: تحتاج إلى حساب تاجر لدى Przelewy24 وبيانات الواجهة البرمجية الخاصة به: وهي 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. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد wcp_przelewy24_payment إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

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

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

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

6. أدخل المفاتيح الفعلية (Live)، وألغِ تحديد Test Mode، واحفظ لقبول المدفوعات الحقيقية.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Przelewy24. وتعرض الصفحة فوق الحقول تحذيرات عند نقص أي شيء. أثناء تفعيل 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 عند الحفظ.

الدفع

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

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

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: Enable sandbox (test) mode. عند التفعيل، تُرسل المدفوعات الجديدة إلى sandbox الخاص بـ Przelewy24 (sandbox.przelewy24.pl) بمفاتيح sandbox، ولا يُخصم أي مبلغ حقيقي. ألغِ التحديد لقبول المدفوعات الحقيقية على secure.przelewy24.pl بمفاتيح Live. الافتراضي: مفعّل.

مفاتيح Live

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

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

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

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

مفاتيح Sandbox

Sandbox Merchant ID: Merchant ID لحساب Przelewy24 التجريبي (sandbox).

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

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

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

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

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

يعرض هذا القسم عنوان الإشعار الخاص بمتجرك. ويبدو هكذا: https://your-site/wc-api/wc_p24_payment/. ترسل الإضافة هذا العنوان إلى Przelewy24 مع كل دفعة، لذلك لا يلزم ضبط أي شيء في لوحة Przelewy24. ويستقبل العنوان نفسه نتائج الاسترداد. ويجب أن يكون العنوان متاحًا من الإنترنت: بلا جدار حماية أو وضع صيانة أو مصادقة HTTP أمامه. وبدون الإشعارات، يُؤكَّد الدفع عندما يعود العميل إلى صفحة «تم استلام الطلب» (انظر الدفع)؛ وإذا لم يعد العميل، يبقى الطلب في حالة «في انتظار الدفع».

متقدم

Debug Log: Enable logging يكتب الأحداث التقنية (أرقام الطلبات ومعرّفات معاملات P24 والأخطاء) في WooCommerce > Status > Logs، المصدر wcp_przelewy24_payment. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تُسجَّل المفاتيح ولا أجسام الطلبات ولا البيانات الشخصية أبدًا. الافتراضي: معطّل.

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

الدفع

يختار العميل طريقة الدفع (الافتراضية Przelewy24، مع شعار P24 في كتلة Checkout) ويُتمّ الطلب. في وضع sandbox تعرض كتلة Checkout Sandbox mode — no real money is charged. تُسجّل الإضافة معاملة Przelewy24 بإجمالي الطلب بعملة الطلب، مع البريد الإلكتروني للعميل واسمه وبلد الفوترة، وتضيف إلى الطلب ملاحظة تتضمن معرّف الجلسة والوضع (sandbox أو live). ولكل محاولة دفع معرّف جلسة خاص بها. يُنقل العميل إلى صفحة الدفع الخاصة بـ Przelewy24 فيدفع عبر BLIK أو التحويل المصرفي الإلكتروني أو البطاقة أو أي طريقة أخرى مفعّلة لحسابك في Przelewy24. تُعرض صفحة الدفع بلغة الموقع إن دعمتها Przelewy24، وإلا فبالإنجليزية.

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

بعد الدفع يعود العميل إلى صفحة «تم استلام الطلب». وإذا لم يكن الإشعار قد وصل بعد، تطلب الإضافة من Przelewy24 حالة المعاملة عبر طلب موثَّق من الخادم إلى الخادم (مرة واحدة كحد أقصى كل 10 ثوانٍ لكل طلب)، وتطبّق الفحوصات نفسها. ولا تُعلّم صفحة العودة وحدها أي طلب كمدفوع. وما دام الدفع غير مؤكَّد، تعرض الصفحة 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: مع زر Pay again يفتح صفحة Pay for order. وإذا كان الطلب في حالة الانتظار، تعرض الصفحة Your payment is being verified. We will send you an e-mail as soon as it is confirmed. ولا يزال الدفع الذي يُجرى لاحقًا من صفحة Przelewy24 أقدم للطلب نفسه مقبولًا.

إذا تعذّر بدء الدفع، يرى العميل رسالة قصيرة: 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 مرة أخرى (This order does not need a payment any more.).

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Przelewy24 ولم يدفع بعد، أو أن الدفع لم يُؤكَّد بعد.

Processing or Completed: تم التحقق من الدفع. يضبط WooCommerce الحالة على «قيد التنفيذ»، أو على «مكتمل» للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. تعرض ملاحظة الطلب رقم طلب P24 والمبلغ والوضع. ومعرّف معاملة الطلب هو رقم طلب P24. ويُطبَّق كل دفع مرة واحدة فقط.

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

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

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Przelewy24. يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد في الوضع الذي تمّت فيه الدفعة (sandbox أو live)، لذا يجب ضبط مفاتيح ذلك الوضع. ويعالج Przelewy24 الاستردادات بشكل غير متزامن: تُظهر ملاحظة الطلب أولًا أن الاسترداد قد طُلب، ثم تصل النتيجة لاحقًا إلى عنوان الإشعار وتُضاف كملاحظة: Przelewy24: refund of … completed. أو ملاحظة تفيد بأن الاسترداد رُفض ولم تُعَد الأموال. وإذا رُفض الاسترداد، تحقق منه في لوحة Przelewy24؛ ولا يُحذف استرداد WooCommerce المسجَّل بالفعل على الطلب تلقائيًا.

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

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

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

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

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

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

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

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

تمّ الدفع لكن الطلب ما زال في Pending payment: لم يصل إشعار Przelewy24 إلى متجرك، ولم يعد العميل إلى صفحة «تم استلام الطلب». تحقق من أن العنوان المعروض في Payment notifications متاح من الإنترنت (بلا وضع صيانة أو جدار حماية أو مصادقة HTTP أمام /wc-api/wc_p24_payment/)، ومن أن Merchant ID وPOS ID وCRC key للوضع الخاص بالدفعة صحيحة. وتُسجَّل الإشعارات المرفوضة في WooCommerce > Status > Logs، المصدر wcp_przelewy24_payment، حتى مع إيقاف Debug Log.

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

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

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. كان المبلغ أو العملة مختلفًا عن الطلب، أو وصل الدفع لطلب كان قد أُلغي. تحقّق من الدفع في لوحة 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. (أو الشيء نفسه للمفاتيح الفعلية) تعني أن مفاتيح وضع الدفعة قد أُزيلت؛ أعد إدخالها.

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

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

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

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