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

المتطلبات

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

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

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

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

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

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

التثبيت

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

2. عند انتهاء الرفع انقر على Configure، أو ابحث لاحقًا عن VibeFox Redsys Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالة الطلب Redsys payment on hold. تعرض PrestaShop وحدة الدفع الجديدة للدول النشطة في تلك اللحظة، ولجميع العملات ومجموعات العملاء. يمكنك تغيير ذلك في Payment > Preferences؛ ويجب تحديد الدول التي تفعّلها لاحقًا هناك للوحدة.

Configuration

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Redsys Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول تحذّرك الصفحة عندما يكون رمز التاجر مفقودًا أو لا يتكون من أرقام فقط، وعندما لا يكون المفتاح السري مفتاح Redsys SHA-256 صالحًا، وعندما يكون مفتاح الوضع الحالي فارغًا (عندها يُخفى أسلوب الدفع في الدفع)، وعندما لا تكون عملة المتجر مدعومة. وأثناء تفعيل وضع الاختبار تعرض الصفحة Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. وإذا كان Title فارغًا تعرض الصفحة Enter a title for the payment method. ولا يُحفظ شيء.

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 لبيئة الإنتاج الحقيقية، وعادةً يكون 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. أسفل أسلوب الدفع.

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

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

Clear saved secrets: حدّد مفتاحًا وانقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

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

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

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفعة ناجحة.

عدم تطابق المبلغ أو العملة، ودفعات الاختبار أثناء وضع الإنتاج في المتجر، ودفعات المحاولات الملغاة تذهب دائمًا إلى Redsys payment on hold.

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

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

متقدم

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

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

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

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

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. يُخفى أسلوب الدفع للسلال المقومة بعملات أخرى.

الدفع

في خطوة الدفع يختار العميل أسلوب الدفع (افتراضيًا Credit/Debit Card (Redsys)) ويؤكد الطلب. يرى العميل Redirecting to Redsys for payment. Please wait... ثم ينتقل إلى صفحة الدفع الخاصة بـ Redsys في بنكك. إذا لم ينتقل المتصفح تلقائيًا، ينقر العميل على Pay via Redsys، أو على Choose another payment method للرجوع. لا يوجد طلب في هذه المرحلة بعد.

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Redsys بالإشعار الموقَّع: الإشعار هو الذي ينشئ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية مع Your payment with Redsys has been received. وإذا انتقل الطلب إلى Redsys payment on hold، تعرض الصفحة 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 created in a few moments — please do not pay again. مع الزرين Check again وBack to checkout.

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

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

تعمل الإشعارات أثناء وضع الصيانة في المتجر، ولا يحجبها تقييد الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Redsys ولم يدفع، أو رُفضت الدفعة أو أُلغيت، أو لم يصل إشعار Redsys بعد. لا توجد سوى السلة.

Payment accepted, Delivered or Redsys payment on hold: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة برقم طلب Redsys (Ds_Order) كمعرّف للمعاملة، وتعرض ملاحظة رقم طلب Redsys ورمز التفويض ورمز الرد، مع الإشارة إلى [TEST] للدفعات التجريبية.

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

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

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

كتلة دفع Redsys

تعرض صفحة الطلب كتلة Redsys payment تتضمن رقم طلب Redsys (Ds_Order)، ورمز التفويض والرد، والبيئة (حقيقية أو اختبار)، والمبلغ المدفوع والمسترد، وشارة Test mode للدفعات التجريبية، وتنبيه مراجعة للطلبات المعلّقة، وسجل الاستردادات، وRedsys notes الخاصة بالطلب، وجميع أرقام طلبات Redsys الصادرة للسلة.

الاستردادات

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

لا تنشئ الوحدة إشعارات دائن. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تُعيد الأموال عبر Redsys.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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