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

المتطلبات

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

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

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

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

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

الإعداد

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

عند الحفظ، يجب أن يتراوح طول Title بين حرف واحد و128 حرفاً، ويجب أن يكون Sort Order عدداً صحيحاً (الأعداد السالبة مسموحة)، ويجب أن يكون Total رقماً أكبر من 0 أو يساويه، ويجب أن تكون المنطقة الجغرافية وحالات الطلب موجودة؛ وإلا فلن يُحفظ أي شيء وتذكر الصفحة المشكلة. إذا كانت طريقة الدفع مفعّلة دون مفتاح API للوضع الحالي، تُحفظ الإعدادات مع تحذير.

Checkout

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

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

Description: النص الذي يُعرض للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.

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

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

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

مفاتيح API

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

Test mode: يستخدم بيئة الاختبار الخاصة بـ MultiSafepay (لا تُجرى مدفوعات حقيقية). وهو يبدّل عنوان API ومفتاح API معاً. تستمر المدفوعات التي تمت بالفعل في استخدام البيئة التي أُجريت فيها لأغراض التحقق من الحالة والاسترداد. الافتراضي: مفعّل. وما دام مفعّلاً، يرى العميل في خطوة Confirm Order الرسالة 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 the saved key on save أسفل الحقل، ثم انقر على Save.

الإشعارات

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

الطلبات

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

Order status after payment: حالة الطلب المدفوع. الافتراضي: قيد المعالجة. اختر Complete لإكمال الطلبات المدفوعة فوراً.

MultiSafepay payment on hold status: تحتاج عملية الدفع إلى انتباه (راجع Order statuses). الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة معلّق. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment error status: عملية دفع لم تُسوَّ أو كانت محجوزة، ثم رُفضت أو انتهت صلاحيتها أو أُلغيت لاحقاً. الافتراضي: فشل.

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

متقدم

Debug log: يسجّل استدعاءات API والإشعارات في mspg_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائماً. لا تُسجَّل مفاتيح API أو بيانات العملاء أبداً. الافتراضي: معطّل.

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

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

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

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

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

الدفع

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

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

ينشئ OpenCart 3 طلباً جديداً في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيحتفظ بطلب واحد للدفع ويعيد دفع الطلب نفسه. وقبل إنشاء عملية دفع جديدة، تتحقق الإضافة من عمليات الدفع السابقة لسلة التسوق نفسها لدى MultiSafepay. فإذا كانت إحداها مدفوعة بالفعل أو قيد المعالجة، فإنها تُؤكَّد ويذهب العميل إلى صفحة النجاح بدلاً من الدفع مرة أخرى. وإذا كانت عملية دفع هذا الطلب ما زالت مفتوحة بالبيئة نفسها والمبلغ والعملة نفسها، فإن صفحة الدفع نفسها تُعاد استخدامها. وإلا فإن عملية الدفع القديمة تُلغى لدى MultiSafepay بحيث لا يمكن دفعها بعد الآن.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. إذا أُغلق هذا الطلب دون دفع في هذه الأثناء (مثلاً بعد رفض دفعه أو انتهاء صلاحيته وهو معلّق، أو لأنك ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، وعند Confirm Order التالي يُدفع طلب جديد. وإذا دُفع الطلب ثم أغلقه المتجر (مثلاً بعد استرداده)، تكون الرسالة Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. وإذا كان الطلب الخاص بالدفع قد سُجّل بالفعل ثم تغيّرت السلة، فالرسالة هي Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. ويُعد أي تغيير في السلة، بما في ذلك تغيير الكمية، سلة جديدة تحتاج إلى دفعة خاصة بها. ولا يحتفظ طلب السلة الذي دُفع ثم أُلغي أو أُسترد بالسلة بعد الآن.

إذا لم يتمكن MultiSafepay من بدء عملية الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل 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. ليس لديها طرق دفع منفصلة في OpenCart لكل طريقة من طرق MultiSafepay، ولا حقول بطاقة مضمّنة، ولا أزرار دفع سريع لـ Apple Pay أو Google Pay، ولا اشتراكات أو مدفوعات متكررة أو بطاقات محفوظة، ولا تحصيل أو إلغاء من OpenCart. لا تُرسل بيانات سلة التسوق، لذلك لا تقدّم MultiSafepay طرق الدفع اللاحق التي تتطلبها (مثل Klarna أو in3 أو Riverty) لهذه الطلبات.

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

Order statuses

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

Order status after payment (default Processing): أكد MultiSafepay عملية الدفع (مكتملة أو مُرسلة) بالمبلغ والعملة الدقيقين للطلب. تعرض ملاحظة عملية الدفع وطريقة الدفع والبيئة.

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

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

MultiSafepay payment on hold status, after a chargeback: أبلغ MultiSafepay عن استرداد مبلغ بإلغاء (chargeback) لعملية دفع طلب مدفوع: أُخذ المال من حسابك.

Payment error status (default Failed): عملية دفع لم تُسوَّ أو كانت محجوزة، ثم رُفضت أو أُلغيت أو انتهت صلاحيتها أو أُبطلت لاحقاً.

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

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

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

تبويب VibeFox MultiSafepay Gateway

في Sales > Orders افتح طلباً مدفوعاً عبر MultiSafepay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox MultiSafepay Gateway الـMultiSafepay order (مع التسمية Test environment لعمليات الدفع التجريبية)، وMethod، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد، وMultiSafepay notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

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

لا ترسل المرتجعات الخاصة بالمنتجات في Sales > Returns أي أموال عبر MultiSafepay.

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

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

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

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

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

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

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

MultiSafepay does not appear at checkout: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على مفتاح API: Test API key في وضع الاختبار، وLive API key في الوضع الفعلي. تعرض صفحة الإعدادات تحذيراً عند غياب المفتاح. يجب أن يدفع العميل بعملة يقبلها MultiSafepay (العملة المختارة في المتجر). تحقّق أيضاً من أن عنوان الدفع موجود في Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

The payment went through, but the order stays without a status: لم يصل الإشعار إلى متجرك. تحقق من أن المتجر متاح من الإنترنت، وأن مفتاح API لبيئة الدفع مضبوط، لأن الإضافة تقرأ الحالة من واجهة MultiSafepay البرمجية. إذا تعذّر الوصول إلى الواجهة البرمجية أو كان المفتاح مفقوداً، يردّ الإشعار بـ ERROR ويعيد MultiSafepay المحاولة. يحصل الطلب أيضاً على حالته عندما يعود العميل إلى المتجر، وعندما يحاول دفع سلة التسوق نفسها مرة أخرى.

Notification answers Invalid request: لم يكن في الطلب معرّف معاملة صالح. إشعارات MultiSafepay تتضمن دائماً معرّفاً.

The customer sees an error after Confirm Order: فعّل Debug log وانظر إلى الحقل Log في صفحة الإضافة. تعني This payment method is not available. أن جلسة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في هذه الأثناء: على العميل إعادة تحميل صفحة الدفع. وتعني 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 رفض المبلغ أو العملة.

The customer comes back and sees Payment verification failed.: لم يطابق عنوان العودة أي عملية دفع لهذا المتجر، مثل رابط قديم أو معدّل. يمكن للعميل الدفع مرة أخرى من صفحة الدفع.

Order is in the on hold status: اقرأ الملاحظات في تبويب VibeFox MultiSafepay Gateway. قد تكون عملية الدفع غير مُسوّاة أو محجوزة، أو قد يكون المبلغ أو العملة المدفوعة مختلفين عن الطلب، أو قد تكون عملية دفع تجريبية وصلت في الوضع الفعلي، أو قد تكون عملية الدفع وصلت بعد إلغاء الطلب، أو قد يكون هناك استرداد بإلغاء (chargeback). تحقق من المعاملة في MultiSafepay Control.

Test payments do not confirm a live order: لا تدفع عملية دفع تجريبية أي طلب ما دامت الإضافة في الوضع الفعلي؛ بل يُوضع الطلب في حالة معلّق. تستمر عمليات الدفع التجريبية السابقة في التحقق منها واستردادها بمفتاح الاختبار بعد التحويل إلى الوضع الفعلي.

No refund form in the tab: يوضح التبويب السبب: عملية الدفع لم تُبلَّغ بعد، أو مُستردة بالكامل، أو مجموعة المستخدمين الخاصة بك ليس لديها صلاحية تعديل الإضافة.

Refund fails with a message about the environment: تمت عملية الدفع في بيئة الاختبار أو البيئة الفعلية، ومفتاح API لتلك البيئة غير مضبوط. أدخله وأعد المحاولة.

للمطورين: تُطلق الإضافة أحداث OpenCart mspg_supported_currencies وmspg_order_request لتغيير العملات المدعومة وبيانات الدفع المرسلة إلى MultiSafepay.

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

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

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

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