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

المتطلبات

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

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

العملة: يجب أن تكون عملة السلة إحدى العملات التي تقبلها MultiSafepay، مثل EUR أو USD أو GBP أو PLN أو CHF أو SEK أو DKK أو NOK. بالنسبة للعملات الأخرى، لا تظهر طريقة الدفع في خطوة الدفع.

حساب MultiSafepay: تحتاج إلى مفتاح API لموقعك في MultiSafepay Control. لحسابي التجربة والإنتاج مفاتيح مختلفة. لا يلزم إعداد أي شيء آخر في MultiSafepay: إذ يُرسل عنوان الإشعار مع كل دفعة.

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

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

التثبيت

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

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

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

4. الصق مفتاح API التجريبي و/أو الإنتاجي من MultiSafepay Control (راجع الإعدادات).

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

عند التثبيت تُنشئ الوحدة حالة الطلب MultiSafepay payment on hold. تقدّم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها في Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox MultiSafepay Gateway > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة بأكملها. وتعرض الصفحة فوق الحقول Test mode: new payments use the MultiSafepay test environment (no real payments). ما دام وضع الاختبار مفعّلًا، وتحذّرك عندما لا يوجد مفتاح API للوضع الحالي (فلا تظهر طريقة الدفع حينئذٍ في خطوة الدفع)، وعندما لا تقبل MultiSafepay العملة الافتراضية لمتجرك. ولا تُحفظ الصفحة من دون Title.

الدفع

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

Title: اسم طريقة الدفع الذي يراه العميل في خطوة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: MultiSafepay. مطلوب.

Description: النص الذي يظهر أسفل طريقة الدفع في خطوة الدفع. الافتراضي: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.

مفاتيح API

تجد مفتاح API في MultiSafepay Control > Manage settings > Website settings. ويحتوي القسم على روابط لحساب التجربة (testmerchant.multisafepay.com) وحساب الإنتاج (merchant.multisafepay.com). ولكل منهما مفتاح مختلف. يستخدم وضع الاختبار مفتاح التجربة فقط، ويستخدم وضع الإنتاج مفتاح الإنتاج فقط.

Test mode: Use the MultiSafepay test environment (no real payments). يبدّل عنوان API ومفتاح API معًا. وتستمر المدفوعات التي تمت بالفعل في استخدام البيئة التي تمت فيها، لفحوص الحالة والاستردادات. الافتراضي: مفعّل. وما دام مفعّلًا، يرى العملاء أسفل طريقة الدفع Test mode: no real payment will be made.

Test API key: مفتاح API لحساب MultiSafepay التجريبي الخاص بك.

Live API key: مفتاح API لحساب MultiSafepay الإنتاجي الخاص بك.

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

Clear saved keys: ضع علامة على مفتاح وانقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

الإشعارات

لا يلزم إعداد شيء. يعرض حقل Notification URL العنوان الذي يُرسل إلى MultiSafepay مع كل دفعة. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_multisafepay_gateway/webhook، وقد يحتوي على رمز لغة مثل /en/. الإشعار يخبر الوحدة فقط بالدفعة التي تغيّرت: الحالة والمبلغ والعملة تُقرأ دائمًا من واجهة MultiSafepay البرمجية باستخدام مفتاح API الخاص بك قبل إنشاء الطلب أو تعديله. تُتجاهل الإشعارات الخاصة بالمدفوعات التي لم تبدأ في متجرك. ويعمل الإشعار أثناء وضع الصيانة للمتجر، ولا يحجبه قيد الدولة الخاص بمتجرك.

الطلبات

Order status after payment: حالة الطلب المدفوع. تُعيَّن الحالة دفعة واحدة، مع تغيير حالة واحد ورسالة بريد إلكتروني واحدة للعميل.

متقدم

Debug log: Log API calls and notifications إلى logs/mspg_debug.log.php في مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تُسجَّل مفاتيح API وبيانات العملاء أبدًا. الافتراضي: معطّل.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات والسجل. تبقى بيانات دفع MultiSafepay للطلبات وحالة الطلب دائمًا، لتظل استردادات الطلبات القديمة ممكنة. تعطيل الوحدة لا يحذف أي شيء أبدًا. الافتراضي: معطّل.

خطوة الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا MultiSafepay، مع شعار MultiSafepay) ويؤكد. تُنشئ الوحدة دفعة MultiSafepay بإجمالي السلة بعملة السلة، وتُرسل العميل إلى صفحة دفع MultiSafepay. هناك يختار العميل أي طريقة دفع مفعّلة في حساب MultiSafepay الخاص بك ويدفع. تُنقل عناوين الفوترة والبريد الإلكتروني والهاتف ولغة العميل إلى MultiSafepay، وتظهر الدفعة باسم Order # ورقم السلة واسم متجرك. لا يوجد طلب بعد في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب مدفوعًا إلا بعد أن تؤكده MultiSafepay: إما بالإشعار أو بفحص عبر واجهة MultiSafepay البرمجية عند عودة العميل. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع Your payment with MultiSafepay has been received. وبالنسبة لطلب في الانتظار، تعرض الصفحة We are confirming your payment with MultiSafepay. The order will be updated automatically — please do not pay again. وإذا فشلت الدفعة لاحقًا، تعرض الصفحة Your MultiSafepay payment was not completed. Please contact us about this order. وإذا لم تكن MultiSafepay قد أكدت الدفعة بعد عند عودة العميل (مثلًا عند انتظار تحويل مصرفي)، تعرض صفحة Payment confirmation نص التأكيد نفسه وزر Check again؛ ويُنشئ الإشعار الطلب بمجرد أن تبلغ MultiSafepay بالدفعة.

إذا ألغى العميل في صفحة MultiSafepay، أو رُفضت الدفعة أو انتهت صلاحيتها، يعود العميل إلى خطوة الدفع مع الاحتفاظ بالسلة ومع إحدى هذه الرسائل: The MultiSafepay payment was cancelled. You can try again or choose another payment method. أو The payment was declined. Please try again or choose another payment method. أو The payment session has expired. Please try again.

قبل إنشاء دفعة جديدة للسلة نفسها، تتحقق الوحدة من الدفعة السابقة لدى MultiSafepay. إذا كانت مدفوعة أو قيد المعالجة، يُنشأ الطلب بدلًا من دفعة جديدة. وإذا كانت لا تزال مفتوحة بالمبلغ نفسه، تُعاد استخدام صفحة الدفع نفسها. وإذا تغيّر المبلغ، تُلغى الدفعة القديمة لدى MultiSafepay حتى لا يمكن دفعها بعد ذلك.

إذا تعذّر على MultiSafepay بدء الدفعة، يبقى العميل في خطوة الدفع مع رسالة قصيرة، مثل Could not connect to MultiSafepay. Please try again in a moment. أو MultiSafepay cannot accept this order amount or currency. Please choose another payment method. ويُكتب السبب التقني في السجل.

تقدّم الوحدة طريقة دفع واحدة تقود إلى صفحة MultiSafepay. ليس لديها طرق دفع منفصلة في PrestaShop لكل طريقة دفع من MultiSafepay، ولا حقول بطاقة مدمجة، ولا أزرار دفع سريع Apple Pay أو Google Pay، ولا اشتراكات أو مدفوعات متكررة أو بطاقات محفوظة، ولا يمكن إجراء التحصيل أو الإلغاء من PrestaShop. ولا تُرسل بيانات السلة، لذلك لا تعرض MultiSafepay لهذه الطلبات طرق الدفع الآجل التي تحتاج إليها (مثل Klarna أو in3 أو Riverty).

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى MultiSafepay ولم يدفع، أو لم تؤكد MultiSafepay الدفعة بعد. لا توجد إلا السلة.

Payment accepted أو Delivered: أكدت MultiSafepay الدفعة (مكتملة أو مشحونة). تتبع الحالة Order status after payment. تُسجَّل الدفعة بمعرّف طلب MultiSafepay كمعرّف للمعاملة، وتُظهر ملاحظة الدفعة وطريقتها والبيئة.

MultiSafepay payment on hold before payment: الدفعة غير مسواة (تراجعها MultiSafepay) أو محجوزة (مُفوَّضة). لاستلام المال، قم بتحصيل الدفعة المحجوزة في MultiSafepay Control. ينتقل الطلب تلقائيًا إلى حالة المدفوع عندما تبلغ MultiSafepay بأن الدفعة مكتملة.

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

MultiSafepay payment on hold after a chargeback: أبلغت MultiSafepay عن عملية استرجاع لطلب مدفوع: استُرجع المال من حسابك.

Payment error: دفعة غير مسواة أو محجوزة رُفضت أو أُلغيت أو انتهت صلاحيتها أو أُبطلت لاحقًا.

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

لا يُعاد فتح طلب مدفوع أو مسترد بسبب إشعار متأخر. وإذا اكتملت دفعة ثانية لسلة مدفوعة بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد الدفعة المكررة في MultiSafepay Control.

كتلة دفع MultiSafepay

تعرض صفحة الطلب كتلة MultiSafepay payment تتضمن معرّف طلب MultiSafepay وطريقة الدفع والحالة والمبلغ المدفوع والمسترد، وشارة Test mode للدفعات التجريبية، وسجل الاستردادات وMultiSafepay notes الخاصة بالطلب.

الاستردادات

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

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

تُضاف الاستردادات التي تتم في MultiSafepay Control إلى الملاحظات عندما تبلغ MultiSafepay بها. لا تتغير حالة الطلب وإشعارات الدائن تلقائيًا. حدّثها يدويًا عند الحاجة.

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

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

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

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

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

لا تظهر MultiSafepay في خطوة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح API (Test API key في وضع الاختبار، وLive API key في وضع الإنتاج)، وأن عملة السلة مقبولة لدى MultiSafepay. تعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو عندما لا تُقبل عملة المتجر. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

تمّت الدفعة لكن لم يُنشأ أي طلب: لم يصل الإشعار إلى متجرك. تحقق من أن المتجر متاح من الإنترنت وأن مفتاح API لبيئة الدفعة مضبوط، لأن الوحدة تقرأ الحالة من واجهة MultiSafepay البرمجية. وإذا تعذّر الوصول إلى الواجهة أو كان المفتاح مفقودًا، يجيب الإشعار بـ ERROR وتعيد MultiSafepay المحاولة. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر، وعندما يحاول دفع السلة نفسها مرة أخرى.

يجيب الإشعار بـ Invalid request: لم يحتوِ الطلب على معرّف معاملة صالح. وإشعارات MultiSafepay تحتوي دائمًا على معرّف معاملة.

يرى العميل خطأ عند اختيار MultiSafepay: فعّل Debug log وراجع حقل Log في صفحة الوحدة. عادةً ما تعني This payment method is temporarily unavailable. Please choose another payment method. وجود مفتاح API خاطئ أو مفقود. أما MultiSafepay cannot accept this order amount or currency. Please choose another payment method. فتعني أن MultiSafepay رفضت المبلغ أو العملة.

الطلب في حالة MultiSafepay payment on hold: اقرأ الملاحظات في كتلة MultiSafepay payment. قد تكون الدفعة غير مسواة أو محجوزة، أو يكون المبلغ المدفوع أو العملة مختلفين عن السلة، أو قد تكون دفعة تجريبية وصلت في وضع الإنتاج، أو قد تكون الدفعة وصلت بعد إلغاء الطلب، أو قد تكون هناك عملية استرجاع. تحقق من المعاملة في MultiSafepay Control.

لا تؤكد الدفعات التجريبية طلبًا حقيقيًا: لا تدفع الدفعة التجريبية أي طلب ما دامت الوحدة في وضع الإنتاج؛ بل يُوضع الطلب في حالة الانتظار. وتظل الدفعات التجريبية السابقة تُفحص وتُسترد بمفتاح التجربة بعد التحويل إلى الإنتاج.

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

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

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

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