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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > MultiSafepay. يعرض عنوان الصفحة شارة Test mode طالما كان وضع الاختبار مفعّلًا. وفوق الحقول، تنبهك الصفحة عندما لا يحتوي الوضع الحالي على مفتاح API (فتُخفى طريقة الدفع حينئذ في صفحة الدفع) أو عندما لا تقبل MultiSafepay عملة المتجر. وفي قائمة طرق الدفع، يُوسم MultiSafepay بأنه بحاجة إلى إعداد إلى أن يحتوي الوضع الحالي على مفتاح API.

الدفع

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 API key: مفتاح API لحسابك التجريبي في MultiSafepay.

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

الإشعارات

لا يلزم إعداد شيء. يعرض هذا القسم عنوان الإشعار، الذي يُرسل إلى MultiSafepay مع كل دفعة. ويبدو هكذا: https://your-site/?wc-api=mspg_webhook. ويجب أن تستطيع MultiSafepay الوصول إلى موقعك. والإشعار يخبر الإضافة فقط بالدفعة التي تغيّرت: إذ تُقرأ الحالة والمبلغ والعملة دائمًا من واجهة MultiSafepay البرمجية باستخدام مفتاح API الخاص بك قبل تغيير أي طلب. وتُتجاهل الإشعارات المتعلقة بمدفوعات لا تخص طلبًا من طلبات متجرك.

الطلبات

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

متقدم

Debug log: Log API calls and notifications يكتب التفاصيل في WooCommerce > Status > Logs، ومصدرها wcp_multisafepay_gateway. وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل مفاتيح API أو بيانات العملاء. الافتراضي: معطّل.

Delete data on uninstall: Remove settings, logs and MultiSafepay order data when the plugin is deleted. إلغاء تفعيل الإضافة لا يحذف أي شيء أبدًا. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا MultiSafepay) ويقدّم الطلب. تُنشئ الإضافة دفعة MultiSafepay بإجمالي الطلب بعملة الطلب، وتنقل العميل إلى صفحة الدفع الخاصة بـ MultiSafepay. وهناك يختار العميل أي طريقة دفع مفعّلة في حسابك لدى MultiSafepay ويدفع. وتُنقل بيانات الفوترة الخاصة بالعميل ولغة المتجر إلى MultiSafepay، ويظهر الدفع باسم Order # ورقم الطلب واسم موقعك. وفي وضع الاختبار تعرض صفحة الدفع العبارة Test mode: no real payment will be made.

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

وإذا ألغى العميل في صفحة MultiSafepay أثناء الدفع، يُلغى الطلب بالطريقة القياسية في WooCommerce، ويُحرَّر المخزون، وتبقى المنتجات في السلة. وإذا كان العميل يدفع من صفحة Pay for order، يعود إليها، وتشرح الصفحة ما حدث: 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 إلى ملاحظات الطلب.

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى MultiSafepay ولم يدفع بعد.

Processing أو Completed: أكدت MultiSafepay الدفع (مكتمل أو مشحون). وتتبع الحالة Order status after payment. وتعرض ملاحظة الطلب معرّف دفعة MultiSafepay وطريقة الدفع والبيئة. ومعرّف المعاملة هو معرّف طلب MultiSafepay الخاص بالدفعة.

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

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

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

Failed: رُفضت آخر دفعة لطلب غير مدفوع أو أُلغيت أو انتهت صلاحيتها أو أُبطلت (void). ويُحرَّر المخزون المحجوز. ويمكن للعميل أن يحاول مرة أخرى.

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

الاستردادات

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

تُضاف عمليات الاسترداد التي تتم في MultiSafepay Control إلى ملاحظات الطلب عندما تُبلغ بها MultiSafepay. ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce. وإذا لزم الأمر، أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via MultiSafepay.

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

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

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

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

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

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

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

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

يرى العميل خطأً عند تقديم الطلب: افتح ملاحظات الطلب أو فعّل Debug log وراجع WooCommerce > Status > Logs، ومصدرها wcp_multisafepay_gateway. وعادةً ما تعني 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 رفضت المبلغ أو العملة.

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

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

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

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

الإزالة

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

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