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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

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

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

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

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

التثبيت

يحتوي التنزيل على ملف zip واحد يضم الحزم الخاصة بإصداري OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_przelewy24_payment-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_przelewy24_payment.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر فوق Upload، ثم اختر الملف wcp_przelewy24_payment-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا تحتاج Extensions > Modifications إلى تحديث. وبدلًا من أداة التثبيت، يمكنك أيضًا نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذري لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox Przelewy24 Payment، وانقر فوق Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

5. أدخل مفاتيح الإنتاج، وألغِ تفعيل Test Mode، ثم انقر فوق Save لقبول المدفوعات الحقيقية.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر فوق Upload، ثم اختر الملف wcp_przelewy24_payment.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة بعد إعادة تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر فوق Install (زر + الأخضر) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Przelewy24 Payment، وانقر فوق Install (زر + الأخضر)، ثم فوق Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح Przelewy24 كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. يختلف عنوان الإشعارات فقط (انظر إشعارات الدفع).

يبدأ التثبيت الجديد بطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Przelewy24 Payment > Edit. تظهر الأقسام في الجهة اليسرى، ويحفظ زر Save أسفل القائمة الصفحة بأكملها. وفوق الإعدادات، تعرض الصفحة تحذيرات عند نقص شيء ما. أثناء تفعيل بيئة الاختبار: 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. (أو الرسالة نفسها لمفاتيح الإنتاج). وإذا لم يقبل Przelewy24 العملة الافتراضية لمتجرك، يذكر التحذير العملة والعملات المدعومة. وبعد الحفظ، تتبع التحذيرات الوضع والمفاتيح الجديدة فورًا. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا يُحفظ شيء إذا كان أحد الحقول خاطئًا: لا يجوز أن يكون Title فارغًا (Enter a title for the payment method (at most 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (القيم السالبة مسموحة)، ويجب أن يكون Total عددًا أكبر من 0 أو يساويه، ويجب أن تكون Geo Zone وحالات الطلب موجودة. لا تمنع المفاتيح الناقصة الحفظ. وتُزال المسافات وفواصل الأسطر المنسوخة مع المفاتيح من لوحة Przelewy24 عند الحفظ.

Przelewy24

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Przelewy24. حقل مطلوب، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay with BLIK, online bank transfer or card via Przelewy24.

Sort Order: ترتيب Przelewy24 بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Przelewy24 فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المختارة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي سلة الشراء، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Przelewy24. اتركه فارغًا لعرض Przelewy24 مهما كان المبلغ.

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

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

Test Mode: يستخدم بيئة sandbox التابعة لـ Przelewy24 ومفاتيح Sandbox. لا يُخصم أي مبلغ حقيقي. أوقفه لقبول المدفوعات الحقيقية بمفاتيح Live. الافتراضي: on. وطالما هو مفعّل، يرى العملاء Sandbox mode - no real money is charged في خطوة Confirm Order.

مفاتيح الإنتاج

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: معرّف التاجر لحساب Przelewy24 الخاص ببيئة الاختبار.

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

Sandbox API key (report key): مفتاح API لحساب بيئة الاختبار.

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

لا تُعرض مفاتيح API وCRC key المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح محفوظ، ضع علامة على Clear the saved value أسفل الحقل، ثم انقر فوق Save.

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

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

Notification URL: العنوان الذي يستقبل إشعارات الدفع من Przelewy24. يبدو في OpenCart 3 هكذا: https://your-store/index.php?route=extension/payment/wcp_przelewy24_payment/notify، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_przelewy24_payment/payment/wcp_przelewy_24payment.notify ويُنشأ من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. ترسل الإضافة هذا العنوان إلى Przelewy24 مع كل دفعة وكل استرداد، لذلك لا يلزم ضبط أي شيء في لوحة Przelewy24. ويجب أن يكون عنوان URL متاحًا من الإنترنت: دون جدار حماية أو مصادقة HTTP أمامه. ويستمر عمله أثناء وضع الصيانة للمتجر: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، ويضيف الإضافة على OpenCart 4 إجراء بدء تشغيل (startup action) لعنوان الإشعارات وعودة العميل. ومن دون الإشعارات، يُؤكَّد الدفع عندما يعود العميل إلى المتجر (انظر الدفع)؛ وإذا لم يعد العميل، يبقى الطلب بلا حالة.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن يؤكد Przelewy24 الدفع وتتحقق الإضافة منه. يسرد كل حقل أدناه حالات طلبات OpenCart لديك.

Paid Order Status: الحالة بعد دفعة تم التحقق منها. الافتراضي: Processing.

On Hold (Review) Status: تحصل المدفوعات التي لا يتطابق مبلغها أو عملتها مع الطلب (غير المتحقق منها)، أو التي تصل بعد إلغاء الطلب، على هذه الحالة مع ملاحظة تشرح السبب. الافتراضي: Pending، لأن OpenCart ليس لديه حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Cancelled Order Status: لا تضبطها الإضافة أبدًا. والدفعة المتحقق منها لطلب بهذه الحالة تضع الطلب في حالة التعليق بدلًا من إعادة فتحه بصمت. الافتراضي: Canceled.

Refunded Status: تُضبط بعد استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: Refunded.

خيارات متقدمة

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

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

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

الاستيراد / التصدير

Export: يحفظ Download JSON الإعدادات في ملف JSON. ولا تُصدَّر مفاتيح API وCRC key.

Import: الصق ملف JSON المُصدَّر سابقًا وانقر فوق Import لاستعادة الإعدادات. تبقى مفاتيح API وCRC key المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Przelewy24). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the secure Przelewy24 page to complete the payment. وينشئ OpenCart الطلب في هذه الخطوة، ما زال دون حالة. وعندما ينقر العميل على Confirm Order، تسجّل الإضافة معاملة لدى Przelewy24 بإجمالي الطلب بعملة الطلب، مع البريد الإلكتروني للعميل واسمه وبلد الفوترة، والوصف Order # متبوعًا برقم الطلب واسم متجرك. ولكل محاولة دفع معرّف جلسة خاص بها. ويُرسل العميل إلى صفحة الدفع الخاصة بـ Przelewy24 ويدفع عبر BLIK أو التحويل المصرفي الإلكتروني أو البطاقة أو طريقة أخرى مفعّلة لحسابك لدى Przelewy24. وتُعرض صفحة الدفع بلغة الطلب إذا كان Przelewy24 يدعمها، وإلا فبالإنجليزية. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في نافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع.

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

بعد الدفع يعود العميل إلى متجرك. وإذا لم يصل الإشعار بعد، تطلب الإضافة من Przelewy24 حالة المعاملة عبر طلب خادم إلى خادم موثَّق (مرة واحدة كحد أقصى كل 10 ثوانٍ لكل محاولة)، وتطبّق الفحوصات نفسها. وصفحة العودة وحدها لا تُعلّم الطلب كمدفوع أبدًا. وعند تأكيد الدفع، يرى العميل صفحة نجاح طلب OpenCart. وطالما لم يُؤكَّد، تعرض صفحة 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. وعندما ينقل دفع لاحق الطلب من حالة التعليق إلى Paid Order Status، يُخطَر العميل بالبريد الإلكتروني. وإذا ألغيت الطلب قبل الدفع ولم يكن لدى Przelewy24 أي دفعة له، يرى العميل العائد الرسالة Order #… was cancelled by the store before the payment was completed. No Przelewy24 payment was received for it. Please place a new order or contact us.

إذا تعذّر بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر: 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. وينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order؛ ولا يُرسل الطلب أو السلة المدفوعة سابقًا إلى Przelewy24 مرة أخرى، ويذهب العميل إلى صفحة النجاح.

يحتفظ OpenCart 4 بطلب واحد لصفحة الدفع ويحدّثه في كل مرة تُعرض فيها خطوة Confirm Order، لذلك يبدأ Pay again معاملة Przelewy24 جديدة للطلب نفسه. إذا أغلق المتجر ذلك الطلب في الأثناء (مثلًا بالإلغاء أو الاسترداد)، يعود العميل إلى صفحة الدفع مع Your previous order was closed by the store. Please confirm the order again to place and pay a new order. (لطلب أُلغي قبل أي دفع، مع رسالة الطلب الملغى أعلاه)، ويدفع Confirm Order التالي طلبًا جديدًا. وإذا كان طلب صفحة الدفع مدفوعًا بالفعل لكن السلة تغيّرت منذ ذلك، بما في ذلك كمية جديدة، يرى العميل Your previous order #… has already been placed. Your cart has changed: please confirm the new order to pay for it. وتُدفع السلة الجديدة بطلب جديد. وفي OpenCart 4 تظهر هذه الرسائل، وكذلك We could not match this payment to an order. If you were charged, please contact us.، فوق صفحة الدفع.

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

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى Przelewy24 ولم يدفع، أو أن الدفع لم يُؤكَّد بعد. وفي Sales > Orders لا تظهر مثل هذه الطلبات إلا مع الفلتر Order Status مضبوطًا على Missing Orders.

Paid Order Status (الافتراضي Processing): تم التحقق من الدفع. تعرض ملاحظة معرّف طلب P24 والمبلغ والوضع. ويُطبَّق كل دفع مرة واحدة فقط.

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

Refunded Status (الافتراضي Refunded): تم استرداد الدفع بالكامل من خلال الإضافة.

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

الملاحظات هي إدخالات في History الطلب لا يراها العميل.

تبويب VibeFox Przelewy24 Payment

في Sales > Orders افتح طلبًا دُفع عبر Przelewy24. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Przelewy24 Payment معرّف طلب P24 وSession وEnvironment (Sandbox أو Live) وStatus الدفع وكيفية التحقق منه (إشعار أو عودة) والمبالغ Paid / refunded ونموذج الاسترداد وسجل الاستردادات وPayment notes الخاصة بالطلب. ويُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

في تبويب VibeFox Przelewy24 Payment أدخل Amount (تُملأ القيمة التي لم تُسترد بعد تلقائيًا)، واختياريًا Reason (optional)، ثم انقر فوق Refund via Przelewy24. أكّد السؤال Refund this amount through Przelewy24? This cannot be undone. والاسترداد الكامل والجزئي مدعومان حتى المبلغ الذي لم يُسترد بعد. وتحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يُرسل الاسترداد في الوضع الذي تمت فيه الدفعة (بيئة الاختبار أو الإنتاج)، لذلك يجب أن تكون مفاتيح ذلك الوضع مضبوطة. ويصبح الاسترداد متاحًا بعد أن يتحقق Przelewy24 من الدفع.

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

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Przelewy24 Payment هي أول كتلة في Extensions > Extensions > Payments > VibeFox Przelewy24 Payment > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر فوق Activate. بعد ذلك تعرض الكتلة المفتاح مموّهًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-przelewy24 والرابط Manage licenses and domains in your account، الذي يفتح حسابك على vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify على الإضافة. وتتبع نصوص الكتلة لغة لوحة الإدارة (تتضمن الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر فوق Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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

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

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

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

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

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

يرى العميل الرسالة We could not match this payment to an order: رابط العودة من Przelewy24 لم يطابق أي طلب في المتجر. وإذا خُصم من العميل مبلغ، فابحث عن الدفعة في لوحة Przelewy24.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox 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. (أو الرسالة نفسها للإنتاج) تعني أن مفاتيح وضع الدفعة قد أُزيلت؛ أعد إدخالها. وInvalid refund amount تعني أن المبلغ فارغ، أو ليس رقمًا، أو أكبر من المبلغ الذي لم يُسترد بعد.

للمطوّرين: يمكن تغيير قائمة العملات عبر حدث OpenCart المسمى wc_p24_supported_currencies (العملات ذات الخانتين العشريتين فقط).

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر فوق Uninstall (الزر الأحمر −) بجانب VibeFox Przelewy24 Payment. يُزال دائمًا مفتاح ترخيص هذه الإضافة وحالة الترخيص. ويزيل OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Orders، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. ويُحذف أيضًا حدث OpenCart الخاص بالإضافة (في OpenCart 4 يُحذف أيضًا إجراء بدء التشغيل الذي يسمح بمرور الإشعارات وعودة العميل في وضع الصيانة). وإذا كان Delete data on uninstall مفعّلًا، تُحذف إعدادات البوابة الأخرى (العنوان والوصف ووضع الاختبار والمفاتيح ومفتاح سجل التصحيح) والسجل. وإذا كان معطّلًا، تُحفظ من أجل إعادة التثبيت لاحقًا. ويُحتفظ دائمًا ببيانات دفع الطلبات لدى Przelewy24 (الجلسات ومعرّفات طلبات P24 والاستردادات)، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Przelewy24 Payment في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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