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

المتطلبات

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

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

حساب تاجر Redsys: يمنحك بنكك (المُستحوذ الذي أصدر لك نقطة البيع الافتراضية Redsys) رمز التاجر (FUC) ورقم الطرفية ووصولًا إلى لوحة إدارة Redsys، حيث يظهر المفتاح السري SHA-256 لكل بيئة. مفتاح بيئة الاختبار يختلف عن المفتاح الحقيقي. يجب أن يكون الإشعار الإلكتروني (HTTP) مفعّلًا لطرفيتك. اسأل بنكك إذا لم تكن متأكدًا.

العملة: إحدى العملات التي تدعمها الإضافة (راجع الإعدادات)، ويجب أن يكون طرفية Redsys الخاصة بك مفعّلة من البنك لهذه العملة. تقبل معظم الطرفيات اليورو EUR فقط.

متجر قابل للوصول: يجب أن يتمكن Redsys من الوصول إلى متجرك من الإنترنت، دون تسجيل دخول أو حظر من جدار الحماية، لتسليم إشعارات الدفع.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل رمز التاجر والطرفية ومفتاح السرّ السري لكل بيئة (راجع الإعدادات).

5. فعّل Enable/Disable وانقر على Save. أجرِ دفعة تجريبية مع تفعيل Test Mode، ثم أوقف تفعيل Test Mode لقبول المدفوعات الحقيقية.

OpenCart 4

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Redsys Gateway > Edit. تظهر الأقسام في القائمة على اليسار؛ يحفظ الزر Save أسفل القائمة الصفحة بأكملها. بدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

فوق الإعدادات، تحذّرك الصفحة عندما يكون رمز التاجر مفقودًا أو لا يتكون من أرقام فقط، وعندما لا يكون المفتاح السري مفتاح SHA-256 صالحًا لـ Redsys، وعندما يكون مفتاح الوضع الحالي فارغًا (فتُخفى طريقة الدفع عندئذٍ في الدفع)، وعندما لا تكون العملة الافتراضية للمتجر مدعومة. وطالما وضع الاختبار مفعّل، تعرض الصفحة Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged.

عند الحفظ، يجب أن يتراوح طول Title بين 1 و128 حرفًا (Enter a title for the payment method (1 to 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (الأرقام السالبة مسموحة)، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن توجد المنطقة الجغرافية وكل حالة طلب. وإلا فلن يُحفظ شيء.

Redsys

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

Title: اسم طريقة الدفع الذي يراه العميل في الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit/Debit Card (Redsys). مطلوب، حتى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order، أعلى زر التأكيد. الافتراضي: Pay securely with your credit or debit card via Redsys.

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

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

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يصل إليه الطلب قبل عرض Redsys: رقم يساوي 0 أو أكبر. اتركه فارغًا لعرض Redsys لأي إجمالي.

حساب Redsys

يمنحك بنكك رمز التاجر (FUC) والطرفية ووصولًا إلى لوحة إدارة Redsys، حيث يظهر المفتاح السري SHA-256 لكل بيئة. يحتوي هذا القسم على رابط إلى لوحة إدارة Redsys.

Merchant Code (FUC): رمز التاجر الخاص بك في Redsys، حتى 9 أرقام. تُحذف أي خانة ليست رقمًا عند الحفظ.

Terminal Number: رقم الطرفية الذي يعيّنه بنكك، حتى 3 أرقام. الافتراضي: 1. يُحفظ الحقل الفارغ كـ 1.

Secret Key (SHA-256) — live: مفتاح SHA-256 بصيغة Base64 للبيئة الحقيقية (الإنتاج)، وعادةً ما يتكون من 32 حرفًا. يُستخدم عندما يكون وضع الاختبار معطّلًا.

وضع الاختبار (SIS-T)

لبيئة اختبار Redsys مفتاح سري خاص بها. يعرض هذا القسم بيانات الاختبار العامة من Redsys: رمز التاجر 999008881، الطرفية 1، المفتاح sq7HjrUOBfKmC576ILgskD5srU870gJ7، البطاقة 4548 8100 0000 0003، تاريخ الانتهاء 12/49، رمز CVV 123. لا يُخصم أي مبلغ حقيقي في وضع الاختبار.

Test Mode: تُرسل المدفوعات والاستردادات إلى بيئة اختبار Redsys (SIS-T) وتُوقَّع بمفتاح الاختبار. الافتراضي: مفعّل. أوقفه لقبول المدفوعات الحقيقية. وطالما هو مفعّل، يرى العملاء TEST MODE: Redsys test environment, no real money is charged. في خطوة Confirm Order.

Secret Key (SHA-256) — test: مفتاح SHA-256 بصيغة Base64 لبيئة الاختبار. استخدم مفتاح الاختبار الخاص بك أو مفتاح الاختبار العام المذكور أعلاه.

لا تُعرض المفاتيح المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. لحذف مفتاح محفوظ، ضع علامة على Clear saved secret on save أسفل الحقل وانقر على Save.

صفحة الدفع والطلبات

Commerce Name: اسم المتجر الذي يظهر في صفحة دفع Redsys، بحد أقصى 25 حرفًا. الافتراضي: اسم متجرك، مقتطَعًا إلى 25 حرفًا.

Order Status After Payment: الحالة التي يحصل عليها الطلب المدفوع.

تحصل فروقات المبلغ أو العملة، ومدفوعات الاختبار أثناء وضع الإنتاج في البوابة، ومدفوعات المحاولات الملغاة دائمًا على On hold (review) status.

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). يحصل الطلب على حالة فقط بعد الإشعار الموقَّع من Redsys. تترك الدفعة المرفوضة أو الملغاة الطلب دون حالة؛ ويعود العميل إلى الدفع مع بقاء السلة محفوظة. تعرض كل خانة أدناه حالات طلبات OpenCart الخاصة بك.

Processing status: يُستخدم عندما تكون Order Status After Payment هي Processing. الافتراضي: قيد المعالجة.

Completed status: يُستخدم عندما تكون Order Status After Payment هي Completed. الافتراضي: مكتمل.

On hold (review) status: للمدفوعات التي تحتاج إلى مراجعتك (راجع أعلاه)، أو لكل طلب مدفوع عندما تكون Order Status After Payment هي On hold (review). الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة On hold؛ وتشرح ملاحظة على الطلب السبب. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

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

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

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

متقدم

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

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

Delete Data: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تبقى سجلات دفع Redsys للطلبات (اللازمة للاستردادات) محفوظة دائمًا. الافتراضي: معطّل.

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

Export: يحفظ Download JSON الإعدادات في ملف JSON. لا تُصدَّر المفاتيح السرية.

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

العملات المدعومة

EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. تُخفى طريقة الدفع عندما لا تكون عملة العميل ضمن هذه القائمة.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (Redsys)). في خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال دون حالة. عندما ينقر العميل على Confirm Order، تُعدّ الإضافة نموذج دفع موقَّعًا، ويرى العميل Redirecting to Redsys for payment. Please wait... ثم ينتقل إلى صفحة الدفع Redsys الخاصة ببنكك. إذا لم ينتقل المتصفح تلقائيًا، ينقر العميل على Pay via Redsys. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

في صفحة Redsys يدفع العميل بالبطاقة عبر 3-D Secure، أو عبر Bizum أو أي طريقة أخرى فعّلها بنكك للطرفية. تستخدم الصفحة لغة العميل (الإسبانية، والإنجليزية، والكتالونية، والفرنسية، والألمانية، والإيطالية، والبرتغالية وغيرها)، أو الإنجليزية للغات الأخرى. المبلغ هو إجمالي الطلب بأصغر وحدات عملة الطلب، فمثلًا EUR 43.45 تُرسل كـ 4345، وJPY وCLP بلا منازل عشرية. يُوصف الدفع بأنه Order مع رقم الطلب واسم متجرك.

بعد الدفع يعود العميل إلى متجرك. ولا تُعلِّم العودة نفسها أي شيء كمدفوع. لا يُعلَّم الطلب كمدفوع إلا عندما يؤكد Redsys ذلك بالإشعار الموقَّع. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع العبارة Your payment with Redsys has been received. إذا حصل الطلب على On hold (review) status، تعرض الصفحة Your payment with Redsys has been received and is being reviewed by the store. إذا لم يصل الإشعار بعد، تظهر صفحة Payment confirmation تعرض Redsys is confirming your payment. If you completed the payment, your order will be confirmed in a few moments — please do not pay again. مع الزرين Check again وBack to checkout.

إذا ألغى العميل الدفع أو رفض Redsys الدفعة، يعيد Redsys العميل إلى الدفع مع الرسالة The Redsys payment was not completed. You can try again or choose another payment method. تبقى السلة محفوظة ويمكن للعميل الدفع مجددًا. تحصل كل محاولة جديدة على رقم طلب Redsys جديد، ويظل الدفع المنجز من أي منها، مثل تبويب متصفح ثانٍ، معترفًا به. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order؛ وإذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل، ينتقل العميل مباشرة إلى صفحة النجاح، ولا يُطبَّق الدفع المتأخر للطلب الآخر.

في OpenCart 4 تظهر رسالة الدفع غير المكتمل فوق صفحة الدفع. يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك بعد الإلغاء أو رفض الدفع يدفع العميل الطلب نفسه برقم طلب Redsys جديد. إذا أُغلق ذلك الطلب في هذه الأثناء، يُعاد العميل إلى صفحة الدفع مع Your previous order was closed without a payment. Please confirm the order again to pay with a new order. أو، إذا كان له دفعة Redsys، مع Your order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. وتدفع الخطوة التالية Confirm Order طلبًا جديدًا. وإذا كان طلب الدفع مدفوعًا بالفعل لكن السلة تغيّرت منذ ذلك، بما في ذلك كمية جديدة، يُعاد العميل إلى صفحة الدفع وتُدفع السلة الجديدة بطلب جديد.

إذا تعذّر إرسال الدفعة إلى Redsys، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة: Redsys payments are not configured correctly. Please choose another payment method or contact us.، أو رسالة تفيد بعدم قبول المدفوعات بتلك العملة، أو The order total must be greater than zero.

يعمل الإشعار وعودة العميل أيضًا أثناء وضع الصيانة للمتجر: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وعلى OpenCart 4 تضيف الإضافة إجراء بدء تشغيل لهذه الطلبات.

تقبل الإضافة المدفوعات لمرة واحدة فقط، وتُفوَّض وتُحصَّل فورًا في صفحة Redsys. لا تتضمن نموذج بطاقة على موقعك الخاص (InSite أو iframe)، ولا بطاقات محفوظة، ولا دفعًا بنقرة واحدة أو ترميزًا، ولا اشتراكات أو مدفوعات متكررة، ولا تفويضًا مسبقًا مع تحصيل لاحق، ولا روابط دفع للطلبات التي تُنشأ من لوحة الإدارة.

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

حالات الطلب

بدون حالة (طلب مفقود): أُرسل العميل إلى Redsys ولم يدفع، أو رُفض الدفع أو أُلغي، أو لم يصل إشعار Redsys بعد. في Sales > Orders تظهر هذه الطلبات فقط مع الفلتر Order Status المضبوط على Missing Orders.

Processing أو Completed أو On hold (review): تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تعرض ملاحظة رقم طلب Redsys (Ds_Order) ورمز التفويض ورمز الاستجابة، مع وسم [TEST] للمدفوعات التجريبية.

On hold (review) بعد الدفع: أبلغ Redsys عن مبلغ أو عملة تختلف عن إجمالي الطلب، أو وصلت دفعة اختبار أثناء وضع الإنتاج في البوابة (لم يُخصم أي مبلغ حقيقي)، أو دفع العميل بعد إلغاء تلك الدفعة في صفحة Redsys. وتوضح الملاحظة ذلك. تحقق من الدفعة في لوحة إدارة Redsys، ثم عالج الطلب أو استرد الدفعة.

Refunded status: استُرد الدفع بالكامل من خلال الإضافة.

لا تغيّر الدفعة المرفوضة أبدًا طلبًا له حالة بالفعل. وبالنسبة لرموز الاستجابة الشائعة، يعطي السجل والملاحظات سببًا موجزًا، مثل Insufficient funds أو Card expired أو Cancelled by the customer. إذا وصلت دفعة ثانية مختلفة لطلب أو سلة مدفوعة بالفعل، لا يتغير الطلب. تطلب ملاحظة منك استرداد الدفعة المكررة في لوحة إدارة Redsys. إذا أبلغ Redsys أن الدفعة ما زالت قيد التنفيذ، تُضاف ملاحظة وينتظر الطلب النتيجة النهائية.

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

تبويب VibeFox Redsys Gateway

في Sales > Orders افتح طلبًا مدفوعًا عبر Redsys. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Redsys Gateway الـ Redsys order number (Ds_Order) وAuthorisation code / response وEnvironment (إنتاج أو اختبار) مع تسمية Test mode، وStatus الدفعة، وPaid / refunded، وتلميحًا للمراجعة للطلبات المعلّقة، ونموذج الاسترداد، وسجل الاستردادات، وRedsys notes الخاصة بالطلب، وRedsys order numbers issued for this cart. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

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

لا ترد مرتجعات المنتجات في Sales > Returns الأموال عبر Redsys.

لا تُسجَّل الاستردادات التي تُجرى في لوحة إدارة Redsys كاستردادات للإضافة. عندما يرسل Redsys إشعارًا بشأنها، تُضاف ملاحظة إلى الطلب. ولا تتغير حالة الطلب تلقائيًا.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Redsys Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox Redsys Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. تحتها يوجد السطر Product: opencart-payment-redsys والرابط 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.

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

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

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

لا يظهر Redsys في الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن رمز التاجر والطرفية مملوءان، وأن الوضع الحالي يحتوي على مفتاح صالح: Secret Key (SHA-256) — test في وضع الاختبار، وSecret Key (SHA-256) — live في وضع الإنتاج. تحقّق من أن عملة العميل ضمن قائمة العملات المدعومة. تعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات. تحقّق أيضًا من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمّت الدفعة لكن الطلب بقي دون حالة: لم يصل إشعار Redsys إلى متجرك. اطلب من بنكك التحقق من أن الإشعار الإلكتروني (HTTP) مفعّل لطرفيتك. تحقّق من أن العنوان الظاهر في Notification URL يمكن الوصول إليه من الإنترنت دون تسجيل دخول أو حظر من جدار الحماية. فعّل Debug log وراجع الحقل Log في صفحة الإضافة.

يرد الإشعار بـ Forbidden: لم يتطابق التوقيع مع المفتاح السري للبيئة التي بدأ فيها الدفع، أو أن رمز التاجر في الإشعار ليس رمزك. تحقّق من أن المفاتيح السرية ورمز التاجر في الإعدادات تعود لطرفيتك.

يرد الإشعار بـ Order not found: الإشعار موقَّع بشكل صحيح، لكن لا يوجد أي طلب في هذا المتجر يستخدم رقم طلب Redsys هذا.

يرد الإشعار بـ Busy: كانت السلة تُعالَج بإشعار آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. يعيد Redsys محاولة الإشعار. يعرض السجل السبب.

يرد الإشعار بـ Bad request: لم يحتوِ الطلب على معاملات Redsys أو كانت تالفة. لم يصل من Redsys بالصيغة المتوقعة.

الطلب في حالة on hold بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Redsys Gateway (راجع حالات الطلب)، ثم عالج الطلب أو استرد الدفعة.

مدفوعات الاختبار لا تؤكد الطلبات في وضع الإنتاج: لا تدفع دفعة الاختبار طلبًا أبدًا طالما أن Test Mode معطّل. يُوضع الطلب في حالة الانتظار مع ملاحظة بدلًا من ذلك. استخدم وضع الاختبار مع مفتاح الاختبار للمدفوعات التجريبية.

يفشل الاسترداد: اقرأ الخطأ. Redsys refund: the merchant code or the TEST secret key is not configured. (أو LIVE) يعني أن مفتاح بيئة الدفع مفقود. تُشرح رموز أخطاء Redsys في الرسالة، مثل SIS0057 (المبلغ يتجاوز المتبقي من الدفعة)، وSIS0056 (لم تُوجد الدفعة الأصلية: بيئة أو طرفية أخرى)، وSIS0042 (خطأ في التوقيع: تحقّق من مفتاح هذه البيئة)، وSIS0026 (رمز تاجر أو طرفية غير معروف)، وSIS0027 (العملة غير مُعدّة للطرفية). إذا تعذّر الوصول إلى Redsys، لا يتم الاسترداد. حاول لاحقًا.

لا يوجد نموذج استرداد في التبويب: يوضح التبويب السبب، مثل أن الطلب لا يملك دفعة Redsys مؤكدة، أو أنه مُسترد بالكامل، أو أن مجموعة المستخدمين الخاصة بك لا تملك صلاحية تعديل الطلبات.

للمطورين: تُطلق الإضافة أحداث OpenCart wcp_redsys_gateway/merchant_parameters (معاملات الدفع والطلب) وwcp_redsys_gateway/currency_codes (قائمة العملات المدعومة). أضف عملة فقط إذا فعّلها بنكك للطرفية.

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

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

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

Redsys علامة تجارية تعود ملكيتها إلى مالكها. هذه الإضافة غير مرتبطة بـ Redsys ولا تحظى بتأييده.