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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

1. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، ثم انقر Install Now. يمكنك أيضًا رفع مجلد wcp_redsys_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

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

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

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

6. فعّل Enable/Disable. اختبر دفعة مع تفعيل Test Mode، ثم ألغِ تحديد Test Mode لقبول الدفعات الحقيقية.

الإعدادات

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

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: Credit/Debit Card (Redsys).

Description: النص الظاهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely with your credit or debit card via Redsys.

حساب Redsys

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

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

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

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

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

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

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

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

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

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

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفعة ناجحة. تُعيَّن الحالة مرة واحدة، لذلك يتلقى العميل رسالة بريد إلكتروني واحدة.

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

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

متقدم

Debug log: Enable debug logging يكتب تفاصيل الدفعات والإشعارات والاستردادات في WooCommerce > Status > Logs، ومصدرها wcp_redsys_gateway. تُسجَّل الأخطاء دائمًا، حتى عندما يكون هذا الخيار معطّلًا. لا تُسجَّل المفاتيح والتوقيعات وبيانات البطاقات أبدًا. الافتراضي: معطّل.

Delete Data: Delete the gateway settings when the plugin is deleted. عند التفعيل، يؤدي حذف الإضافة إلى إزالة إعدادات البوابة وسجلات الإضافة. الافتراضي: معطّل.

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

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. تُخفى طريقة الدفع للعملات الأخرى. في صفحة Pay for order تكون عملة الطلب هي المعتمدة.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (Redsys)) ويقدّم الطلب. يُعيَّن الطلب إلى بانتظار الدفع، ويرى العميل Redirecting to Redsys for payment. Please wait...، ثم ينتقل إلى صفحة دفع Redsys في بنكك. إذا لم ينتقل المتصفح تلقائيًا، ينقر العميل Pay via Redsys. في صفحة Redsys يدفع العميل بالبطاقة عبر 3-D Secure، أو عبر Bizum أو طريقة أخرى يفعّلها بنكك للجهاز الطرفي. تستخدم الصفحة لغة متجرك (الإسبانية، والإنجليزية، والكتالانية، والفرنسية، والألمانية، والإيطالية، والبرتغالية، وغيرها)، أو الإنجليزية للغات الأخرى.

يُرسل المبلغ بأصغر وحدات عملة الطلب، فمثلًا EUR 43.45 يُرسل كـ 4345، أما JPY وCLP فبلا منازل عشرية. يُوصف الدفع بعبارة Order مع رقم الطلب واسم موقعك. يُخفض المخزون عند تأكيد الدفع، لا قبله.

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Redsys ذلك عبر الإشعار الموقَّع. وحتى يصل، تعرض الصفحة Redsys is confirming your payment. If you completed the payment, your order will be updated in a few moments — please do not pay again.

إذا ألغى العميل الدفع أو رُفض الدفع، تعيد Redsys العميل إلى متجرك. بالنسبة لطلب من الدفع، يُلغى الطلب بالطريقة المعيارية في WooCommerce ويُحتفظ بالسلة. بالنسبة لطلب أنشأته من لوحة الإدارة (رابط دفع)، يعود العميل إلى صفحة Pay for order مع الرسالة The Redsys payment was not completed. You can try again or choose another payment method. ولا يُلغى الطلب. تعرض صفحة إعادة التوجيه في متجرك أيضًا Cancel order & restore cart، أو بالنسبة للطلبات التي أنشأتها من الإدارة Choose another payment method.

يمكن للعميل إعادة دفع طلب غير مدفوع من صفحة Pay for order. تحصل كل محاولة على رقم طلب Redsys جديد، ويظل الدفع المنجز من أي منها، مثل الدفع من تبويب متصفح ثانٍ، معترفًا به.

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

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Redsys ولم يدفع بعد، أو لم يصل إشعار Redsys بعد. تقول ملاحظة الطلب Awaiting Redsys payment.

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

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

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

Cancelled: ألغى العميل الدفع، أو أُلغي الطلب من قِبلك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce.

إذا وصلت دفعة ثانية مختلفة لطلب مدفوع أو مُعاد مبلغه بالفعل، فلن يتغير الطلب. تطلب منك ملاحظة استرداد الدفعة المكررة في لوحة إدارة Redsys. إذا أفادت Redsys بأن الدفعة لا تزال قيد المعالجة، تُضاف ملاحظة وينتظر الطلب النتيجة النهائية.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر زر الاسترداد عبر طريقة دفع Redsys (افتراضيًا Refund via Credit/Debit Card (Redsys)). يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد عبر واجهة REST الخاصة بـ Redsys إلى البيئة التي تمت فيها الدفعة (الاختبار أو الإنتاج)، ويُوقَّع بمفتاح تلك البيئة، ويُتحقق من توقيع الرد. إذا لم تقبل Redsys الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى ملاحظات الطلب مع رقم طلب Redsys والسبب.

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

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

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

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

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

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

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

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

تمت الدفعة لكن الطلب بقي في Pending payment: لم يصل إشعار Redsys إلى متجرك. اطلب من بنكك التحقق من أن الإشعار الإلكتروني (HTTP) مفعّل للجهاز الطرفي الخاص بك. تحقق من أن العنوان الظاهر في إشعارات الدفع يمكن الوصول إليه عبر الإنترنت دون تسجيل دخول أو صفحة صيانة أو حجب من جدار الحماية. فعّل Debug log وراجع WooCommerce > Status > Logs، المصدر wcp_redsys_gateway.

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

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

يردّ الإشعار بـ Busy: كان الطلب قيد المعالجة بإشعار آخر في الوقت نفسه. تعيد Redsys محاولة الإشعار.

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

الطلب في حالة On hold after payment: اقرأ ملاحظة الطلب. اختلف المبلغ أو العملة المدفوعة عن الطلب، أو وصلت دفعة اختبار والمتجر في وضع الإنتاج، أو وصلت الدفعة بعد إلغاء الطلب. نفّذ الطلب أو أعد مبلغ الدفعة.

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

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

يقبل جهازك الطرفي عملة ليست في القائمة: يمكن للمطورين تغيير قائمة العملات باستخدام المرشّح rdsg_currency_codes. أضف عملة فقط إذا كان بنكك قد فعّلها للجهاز الطرفي.

بعد التحديث من الإصدار 1.0: المفتاح الذي استخدمته في وضع الاختبار أصبح الآن في Secret Key (SHA-256) — test. أدخل المفتاح الحقيقي قبل إلغاء تحديد Test Mode. تظل الطلبات المنشأة بالإصدار 1.0 تستقبل الإشعارات والاستردادات.

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

الإلغاء والحذف

تعطيل الإضافة يحتفظ بجميع البيانات. لحذفها، عطّلها ثم احذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. تُحذف إعدادات البوابة وسجلات الإضافة فقط إذا كان Delete Data مفعّلًا؛ وإلا فستبقى لإعادة التثبيت لاحقًا. تبقى بيانات Redsys المخزنة في الطلبات دائمًا، لأنها توثّق الدفعات وتلزم للاسترداد. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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