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

المتطلبات

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

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

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

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

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

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

التثبيت

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

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

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

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

5. فعّل Enable/Disable وانقر على Save ثم اختبر دفعة في sandbox. بعد ذلك أدخل مفاتيح الإنتاج وأوقف Sandbox mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Montonio Payment > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كلها. فوق الحقول تحذرك الصفحة عندما تكون مفاتيح البيئة الحالية مفقودة (وتُخفى طريقة الدفع حينها في صفحة الدفع)، وعندما لا تكون عملة المتجر EUR أو PLN، وتعرض Sandbox mode is on: payments are simulated and no real money is charged. أثناء تفعيل sandbox. لا يمكن ترك Title فارغًا.

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 مفاتيح sandbox فقط، ويستخدم وضع الإنتاج مفاتيح الإنتاج فقط.

Sandbox mode: يستخدم sandbox الخاص بـ Montonio (دفعات تجريبية دون مال حقيقي). يبدّل عنوان API الخاص بـ Montonio وزوج المفاتيح معًا. الافتراضي: مفعّل. أوقفه فقط بعد إدخال مفاتيح الإنتاج. تستمر الدفعات التي تمت في البيئة الأخرى في استخدام مفاتيح بيئتها الخاصة للتأكيدات والاستردادات.

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

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

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

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

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

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

Notification URL: العنوان الذي ترسل إليه Montonio إشعارات الدفع. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_montonio_payment/webhook. لا تحتاج إلى إدخاله في أي مكان: تُرسله الوحدة إلى Montonio مع كل دفعة.

متقدم

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

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

Delete data: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وسجلها. تعطيل الوحدة لا يحذف شيئًا أبدًا. تُحفظ بيانات الطلبات (معرّفات Montonio UUID والملاحظات) دائمًا. الافتراضي: إيقاف.

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

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

الدفع

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

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

إذا أبلغت Montonio بأن الدفعة ما زالت معلقة عند عودة العميل، تعرض صفحة Payment confirmation النص نفسه وزر Check again. يطلب الزر من Montonio الحالة الحالية للدفعة. يُنشأ الطلب فور وصول الإشعار.

إذا أُلغيت الدفعة أو رُفضت، يعود العميل إلى صفحة الدفع مع إحدى هذه الرسائل: 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. تبقى السلة محفوظة. قبل إنشاء دفعة جديدة، تسأل الوحدة Montonio عن الدفعة السابقة. إذا كانت مدفوعة بالفعل، يُنشأ الطلب ولا تُجرى دفعة ثانية.

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

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Montonio ولم يدفع، أو تبلغ Montonio بأن الدفعة معلقة. السلة وحدها موجودة.

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

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

Payment error: رفض البنك دفعة معتمدة، أو لم يُكملها العميل. لا يغيّر الطلب إلا آخر دفعة للسلة.

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

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

كتلة Montonio payment

تعرض صفحة الطلب كتلة Montonio payment تتضمن معرّف الطلب UUID في Montonio، والبيئة (مع شارة Sandbox للدفعات التجريبية)، والبنك، وحالة الدفع، والمبلغ المدفوع والمسترد، وسجل الاستردادات، وMontonio notes الخاصة بالطلب.

الاستردادات

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

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

لا تُنشئ الوحدة إشعارات خصم (credit slips). أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد المال عبر Montonio. تُضاف الاستردادات التي تتم في Montonio Partner System إلى الملاحظات عندما تبلغ Montonio بها. لا تتغير حالة الطلب وإشعارات الخصم تلقائيًا. حدّثها يدويًا عند الحاجة.

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

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

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

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

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

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

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

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

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

يرد الإشعار بـ Gateway not configured: لم تُضبط أي مفاتيح Montonio، أو مفاتيح بيئة الدفعة مفقودة. أدخل المفاتيح؛ تعيد Montonio محاولة الإشعار.

يرد الإشعار بـ Temporarily unavailable: كانت السلة تُؤكَّد بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة). تعيد Montonio محاولة الإشعار. انظر إلى حقل Log لمعرفة السبب.

يرى العميل خطأ عند اختيار Montonio: انظر إلى حقل Log في صفحة الوحدة. تعني 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 رفضت بيانات الدفعة؛ والسجل يحوي السبب.

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

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

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

للمطورين، تقدّم الوحدة الخطافات actionWcpMontonioSupportedCurrencies وactionWcpMontonioOrderData وactionWcpMontonioLocale لتغيير العملات المدعومة وبيانات الدفع ولغة صفحة Montonio.

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

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

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