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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

العملة: يجب أن تكون عملة المتجر أو الطلب EUR أو PLN. لأي عملة أخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب Montonio: تحتاج إلى مفتاح الوصول والمفتاح السري لمتجرك، وتجدهما في Montonio Partner System. مفاتيح sandbox والإنتاج مختلفة، لذلك تحتاج إلى زوج لكل بيئة تستخدمها. لا يلزم إعداد أي شيء آخر في Montonio: عنوان الإشعار يُرسَل مع كل دفعة.

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. في Montonio Partner System افتح Stores > your store > API keys وانسخ مفتاح وصول sandbox والمفتاح السري الخاص به. ألصقهما في الإعدادات وأبقِ Sandbox mode مفعّلًا.

6. فعّل Enable/Disable واختبر دفعة في sandbox. ثم أدخل مفاتيح الإنتاج وألغِ تحديد Sandbox mode.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Montonio. تحذّرك الصفحة فوق الحقول عندما تكون مفاتيح البيئة الحالية مفقودة (فتُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تكون عملة المتجر EUR أو PLN، وتعرض Sandbox mode is on: payments are simulated and no real money is charged. ما دام sandbox مفعّلًا. وفي قائمة طرق الدفع يُعرض Montonio على أنه يحتاج إلى إعداد حتى يُملأ المفتاحان الخاصان بالبيئة الحالية.

عام

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. الافتراضي: Bank payment (Montonio).

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay directly from your bank account. You will be redirected to Montonio to choose your bank.

مفاتيح API

تجد المفاتيح في Montonio Partner System ضمن Stores > your store > API keys. مفاتيح sandbox والإنتاج مختلفة. يستخدم sandbox مفاتيحه فقط، ويستخدم وضع الإنتاج مفاتيحه فقط. يعرض هذا القسم من الإعدادات أيضًا عنوان الإشعار، وهو بالشكل التالي: https://your-site/wc-api/wc_mnt_payment/. لا تحتاج إلى إدخاله في أي مكان: تُرسله الإضافة إلى Montonio مع كل دفعة.

Sandbox mode: Use the Montonio sandbox (test payments, no real money). يبدّل عنوان API الخاص بـ Montonio وزوج المفاتيح معًا. الافتراضي: مفعّل. لا تُعطّله إلا بعد إدخال مفاتيح الإنتاج.

Sandbox access key: مفتاح الوصول (UUID) الخاص بمتجرك في sandbox الخاص بـ Montonio.

Sandbox secret key: المفتاح السري الخاص بمتجرك في sandbox الخاص بـ Montonio.

Live access key: مفتاح الوصول (UUID) الخاص بمتجرك في بيئة الإنتاج الخاصة بـ Montonio.

Live secret key: المفتاح السري الخاص بمتجرك في بيئة الإنتاج الخاصة بـ Montonio.

متقدم

Debug log: Log payment events يكتب جميع أحداث الدفع في WooCommerce > Status > Logs، بالمصدر wcp_montonio_payment. تُسجَّل الأخطاء دائمًا، حتى عندما يكون هذا الخيار معطّلًا. لا تُسجَّل المفاتيح والرموز وبيانات العملاء أبدًا. الافتراضي: معطّل.

Delete data: Delete the gateway settings and logs when the plugin is deleted. إلغاء تفعيل الإضافة لا يحذف أي شيء. وتبقى بيانات الطلبات (معرّفات UUID الخاصة بـ Montonio والملاحظات) محفوظة دائمًا. الافتراضي: معطّل.

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

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

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Bank payment (Montonio)) ويقدّم الطلب. تنشئ الإضافة دفعة Montonio بإجمالي الطلب بعملة الطلب، وتُرسل العميل إلى صفحة دفع Montonio. هناك يختار العميل بنكًا ويدفع. تظهر بنوك دولة فاتورة العميل أولًا (بولندا للطلبات بالزلوتي). يظهر الدفع باسم Order مع رقم الطلب. تُفتح صفحة Montonio بلغة المتجر إذا كانت الألمانية أو الإنجليزية أو الإستونية أو الفنلندية أو الليتوانية أو اللاتفية أو البولندية أو الروسية؛ وإلا فبالإنجليزية. في وضع sandbox تعرض صفحة الدفع SANDBOX MODE — test payment, no real money is charged. أسفل الوصف.

لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Montonio الدفع بالحالة PAID والمبلغ والعملة المطابقين تمامًا لمبلغ الطلب وعملته. وبعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. وطالما لم يؤكد Montonio الدفع بعد، تعرض تلك الصفحة Montonio has not confirmed your payment yet. The order is updated as soon as the bank confirms it, and you will receive an e-mail then. وإذا أُلغي الدفع أو رُفض، يعود العميل إلى صفحة Pay for order ويرى إحدى هذه الرسائل: The payment was cancelled or rejected by the bank. You can try again or choose another payment method.، أو The payment was not completed. You can try again or choose another payment method.، أو Montonio could not complete the payment. Please try again or choose another payment method.

يمكن للعميل دفع طلب غير مدفوع مرة أخرى من صفحة Pay for order. وقبل إنشاء دفعة جديدة، تسأل الإضافة Montonio عن الدفعة السابقة. فإذا كانت مدفوعة، يُؤكَّد الطلب ولا تُنشأ دفعة ثانية.

إذا تعذّر على Montonio بدء الدفع، يرى العميل رسالة قصيرة، مثل Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method.، ويمكنه اختيار طريقة دفع أخرى. وتُضاف رسالة الخطأ من Montonio إلى ملاحظات الطلب والسجل.

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

تقبل الإضافة المدفوعات البنكية فقط (بدء الدفع). لا تتضمن مدفوعات بالبطاقات، أو BLIK، أو Apple Pay أو Google Pay، أو Pay Later أو التمويل، أو شحن Montonio، أو الاشتراكات، أو طرق الدفع المحفوظة، أو اختيار البنك على موقعك.

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

حالات الطلب

بانتظار الدفع: أُرسل العميل إلى Montonio ولم يدفع بعد. تُضاف ملاحظة عندما يُبلغ Montonio بأن الدفع معلّق.

مكتمل أو قيد المعالجة: أكد Montonio الدفع (PAID). يتبع الطلب الحالة القياسية لـ WooCommerce للطلبات المدفوعة. تعرض ملاحظة الطلب البنك ومعرّف UUID لدفعة Montonio والمبلغ والبيئة. ومعرّف المعاملة هو معرّف UUID لدفعة Montonio.

قيد الانتظار: لم يؤكد البنك الدفع بعد (AUTHORIZED)؛ يصبح الطلب مدفوعًا عندما يُبلغ Montonio بالحالة PAID. ويُوضع الطلب قيد الانتظار أيضًا عندما يُبلغ Montonio بمبلغ أو عملة مختلفين عن إجمالي الطلب، أو عندما يصل دفع sandbox بينما المتجر في وضع الإنتاج، أو عندما يصل الدفع بعد إلغاء الطلب. تشرح ملاحظة الطلب السبب. تحقق من الدفع في Montonio Partner System، ثم جهّز الطلب أو استرد الدفعة.

فشل: لم يُكمل العميل الدفع، أو رفضه البنك. لا يمكن أن يُفشل الطلب إلا آخر دفعة لطلب غير مدفوع. ويمكن للعميل المحاولة مرة أخرى من صفحة Pay for order.

لا تُعاد الطلبات المدفوعة أو الملغاة أو المستردة إلى الفتح بالإشعارات اللاحقة. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد الدفعة الثانية في Montonio Partner System.

الاستردادات

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

يؤكد Montonio كل استرداد أو يرفضه لاحقًا عبر إشعار. وتُضاف التأكيدات إلى ملاحظات الطلب. وإذا رفض Montonio الاسترداد، فستذكر الملاحظة أن المبلغ لم يُعَد إلى العميل؛ تحقق من ذلك في Montonio Partner System وصحّح الاسترداد في WooCommerce.

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

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

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

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

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

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

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

لا يظهر Montonio في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاحين الخاصين بالبيئة الحالية مُدخلان (Sandbox access key وSandbox secret key في وضع sandbox، وLive access key وLive secret key في وضع الإنتاج)، وأن عملة المتجر أو الطلب هي EUR أو PLN. تعرض صفحة الإعدادات تحذيرًا عندما تكون المفاتيح مفقودة أو العملة غير مدعومة.

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

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

يرد الإشعار بـ Payment does not belong to this order أو Wrong environment: لم يُنشئ هذا المتجر الدفعة لهذا الطلب، أو أُنشئت في البيئة الأخرى (sandbox أو الإنتاج). يحدث هذا عندما يستخدم متجران الحساب نفسه في Montonio وأرقام الطلبات نفسها.

يرد الإشعار بـ Gateway not configured: لم تُعيَّن أي مفاتيح Montonio. أدخل المفاتيح؛ وسيعيد Montonio محاولة الإشعار.

يرى العميل خطأ عند تقديم الطلب: افتح ملاحظات الطلب أو فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_montonio_payment. عادة ما تعني رسالة This payment method is temporarily unavailable. Please choose another payment method. وجود مفاتيح خاطئة أو مفقودة. أما Montonio could not start the payment. Please check your order details or choose another payment method. فتعني أن Montonio رفض بيانات الدفع؛ والملاحظة تحمل السبب.

الطلب قيد الانتظار بعد الدفع: اقرأ ملاحظة الطلب. لم يؤكد البنك الدفع بعد، أو أن المبلغ أو العملة المدفوعين يختلفان عن الطلب، أو وصلت دفعة sandbox في وضع الإنتاج، أو وصل الدفع بعد إلغاء الطلب. تحقق من الدفع في Montonio Partner System.

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

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

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

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

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

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