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

المتطلبات

PrestaShop: 8.0 إلى 9.x.

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

عملة المتجر: يجب أن تكون عملة السلة إحدى العملات التي تدعمها Mollie: AED، AUD، BGN، BRL، CAD، CHF، CZK، DKK، EUR، GBP، HKD، HUF، ILS، ISK، JPY، MXN، MYR، NOK، NZD، PHP، PLN، RON، SEK، SGD، THB، TWD، USD، ZAR. بالنسبة للعملات الأخرى يُخفى خيار الدفع في صفحة الدفع. تعتمد طرق الدفع التي تعرضها Mollie على العملة وعلى حسابك.

وصول الإنترنت إلى متجرك: ترسل Mollie الـ webhooks إلى متجرك، لذلك يجب أن يكون الموقع متاحًا من الإنترنت. ومن دون الـ webhooks تُنشأ الطلبات عند عودة العميل من Mollie.

حساب Mollie: تحتاج إلى مفاتيح API من Mollie Dashboard > Developers > API keys. تبدأ مفاتيح الاختبار بـ test_، ومفاتيح الإنتاج بـ live_. لا حاجة إلى أي مفاتيح أو أسرار أخرى. تُفعَّل طرق الدفع نفسها في حساب Mollie الخاص بك.

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

التثبيت

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

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

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

4. أدخل مفاتيح API للاختبار والإنتاج (انظر الإعدادات). لا يلزم إعداد أي webhook في Mollie.

5. فعّل Enable/Disable وانقر على Save. اترك Test Mode مفعّلًا حتى تُجري دفعة اختبار، ثم عطّله.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Mollie Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول تحذّرك الصفحة عندما تكون Mollie مفعّلة لكن مفتاح API للوضع الحالي فارغ، وعندما لا تدعم Mollie عملة المتجر الافتراضية. وفي الحالتين يُخفى خيار الدفع في صفحة الدفع.

عند الحفظ لا يُحفظ مفتاح API الذي لا يبدأ بـ test_ أو live_ متبوعًا بـ 30 حرفًا وأرقامًا على الأقل: يظهر خطأ ويبقى المفتاح المحفوظ سابقًا كما هو.

صفحة الدفع

Enable/Disable: Enable Mollie Gateway يفعّل خيار الدفع أو يعطّله. الافتراضي: off.

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

Description: وصف طريقة الدفع الذي يظهر للعميل في صفحة الدفع. الافتراضي: Pay securely via Mollie.

مفاتيح API

تجد مفاتيح API في Mollie Dashboard ضمن Developers > API keys؛ ويحتوي هذا القسم على رابط لتلك الصفحة. مفاتيح الاختبار ومفاتيح الإنتاج منفصلة.

Test Mode: يستخدم مفتاح API للاختبار في الدفعات الجديدة. لا تُعالَج أي دفعة حقيقية. في صفحة دفع الاختبار لدى Mollie يمكنك اختيار نتيجة الدفع. يرى العملاء Test mode: no real payment will be made. أسفل خيار الدفع. وتستمر الدفعات التي أُجريت في الوضع الآخر في استخدام مفتاح وضعها الخاص لفحوصات الحالة والاستردادات. الافتراضي: on.

Test API Key: مفتاح API للاختبار الخاص بـ Mollie (يبدأ بـ test_).

Live API Key: مفتاح API للإنتاج الخاص بـ Mollie (يبدأ بـ live_).

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

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

Webhook: يعرض عنوان الـ webhook. لا حاجة إلى أي إعداد: ترسل الوحدة هذا العنوان إلى Mollie مع كل دفعة. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_mollie_gateway/webhook، وقد يتبعه رمز اللغة. يجب أن يكون متاحًا من الإنترنت، وإلا فلن تُنشأ الطلبات إلا عند عودة العميل من Mollie.

الطلبات

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفعة ناجحة. تُعيَّن الحالة في خطوة واحدة.

تنتظر التحويلات المصرفية في Awaiting Mollie payment. وتذهب الدفعات المعتمدة وحالات عدم تطابق المبلغ أو العملة إلى Mollie payment on hold.

متقدم

Logging: يكتب استدعاءات API والـ webhooks في logs/molg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عند إيقاف هذا الخيار. لا تُسجَّل مفاتيح API وبيانات العملاء أبدًا. الافتراضي: off.

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

Delete Data on Uninstall: عند التفعيل تُحذف إعدادات الوحدة وسجلها عند إلغاء تثبيت الوحدة. تبقى دائمًا معرّفات دفعات Mollie المحفوظة مع الطلبات، وسجلات الاسترداد، وحالات الطلبات الخاصة بالوحدة. الافتراضي: off.

صفحة الدفع

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

لا تحمل webhooks من Mollie أي توقيع، بل معرّف الدفعة فقط. لذلك لا تثق الوحدة بالـ webhook في حد ذاته: فهي تقبل فقط معرّفات الدفعات التي أنشأتها بنفسها، وتقرأ الدفعة من واجهة Mollie API بمفتاح الوضع الذي تمت فيه الدفعة، وتتحقق من أن الدفعة تخص السلة، وتقارن المبلغ المدفوع والعملة بإجمالي السلة. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Mollie ذلك بهذه الطريقة. تتعامل الوحدة مع حالات الدفع التالية من Mollie:

عندما يعود العميل، تتحقق الوحدة بالطريقة نفسها من آخر دفعة للسلة عبر واجهة Mollie API. تؤدي الدفعة المكتملة إلى صفحة تأكيد الطلب القياسية مع Your payment with Mollie has been received. وفي حالة التحويل المصرفي تعرض الصفحة Your order will be processed as soon as Mollie receives your bank transfer. وإذا كان الطلب في حالة الانتظار، تعرض الصفحة We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again. وإذا فشلت دفعة طلب موجود أو أُلغي الطلب، تعرض الصفحة Your Mollie payment was not completed. Please contact us about this order.

إذا أُلغيت الدفعة أو فشلت أو انتهت صلاحيتها أو لم تكتمل، يعود العميل إلى صفحة الدفع مع رسالة، مثل You cancelled the Mollie payment. You can try again or choose another payment method. أو The Mollie payment has expired. Please try again or choose another payment method. تبقى السلة محفوظة. وإذا تعذّر الوصول إلى Mollie أو لم تحسم أمرها بعد، تظهر صفحة Payment confirmation تطلب من العميل عدم الدفع مرة أخرى، وتعرض زر Check again؛ وينشئ الـ webhook الطلب فور وصوله.

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

إذا تعذّر على Mollie بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل The payment provider could not be reached. Please try again in a moment. أو This payment method is temporarily unavailable. Please choose another payment method. (مفتاح API خاطئ) أو Mollie cannot accept a payment of this amount or currency. Please choose another payment method. يُكتب السبب التقني في السجل.

يعمل الـ webhook أثناء وضع الصيانة للمتجر، ولا يتأثر بقيود الدول في متجرك.

يختار العميل طريقة Mollie في صفحة Mollie وليس في صفحة الدفع الخاصة بمتجرك. لا تتضمن الوحدة اشتراكات أو مدفوعات متكررة، ولا بطاقات أو تفويضات محفوظة، ولا حقول بطاقات على موقعك، ولا أزرار Apple Pay أو PayPal السريعة، ولا تستخدم Orders API؛ لذلك لا تقدم Mollie لهذه الدفعات طرق الدفع التي تتطلب بنود طلب (مثل بعض متغيرات Klarna أو Billie أو in3). تُحصَّل المدفوعات المعتمدة أو تُلغى في Mollie Dashboard، وليس من PrestaShop.

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

حالات الطلب

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

Payment accepted أو Delivered: تم تأكيد الدفعة. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة بمعرّف دفعة Mollie (tr_...) كمعرّف للمعاملة، وتعرض ملاحظة الدفعة وطريقتها ووضعها.

Awaiting Mollie payment: اختار العميل التحويل المصرفي في صفحة Mollie. ينتقل الطلب إلى حالة المدفوع عندما تستلم Mollie المال.

Mollie payment on hold: دفعة مُعتمدة تنتظر التحصيل، أو أبلغت Mollie عن اعتراض، أو اختلف المبلغ المدفوع أو العملة عن السلة (مثلًا تغيرت السلة بعد بدء الدفع)، أو دُفعت دفعة اختبار والمتجر في وضع الإنتاج (لم يُستلم أي مال)، أو وصلت الدفعة بعد إلغاء الطلب. تشرح الملاحظة السبب. تحقق من الدفعة في Mollie Dashboard، ثم عالج الطلب أو استرد الدفعة.

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

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

إذا دُفعت دفعة ثانية للسلة نفسها، فلن يتغير الطلب. وتطلب منك ملاحظة استرداد الدفعة المكررة في Mollie Dashboard.

كتلة Mollie payment

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

الاستردادات

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

لا تنشئ الوحدة إشعارات دائن (credit slips). أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد المال عبر Mollie. الاستردادات التي تُنشأ في Mollie Dashboard لا تظهر على الطلب؛ والاعتراض يضيف ملاحظة فقط.

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

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

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

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

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

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

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

يرد الـ webhook بـ Unknown payment.: الدفعة لم تُنشأ بواسطة هذا المتجر، أو أن Mollie لا تعرفها بمفتاح API الخاص بوضعها، مثل دفعة من حساب Mollie آخر.

يرد الـ webhook بـ Payment ID mismatch.: الدفعة لا تخص السلة التي أُنشئت لها. لا يتغير شيء.

يرد الـ webhook بـ Failed to fetch payment.: تعذّر الوصول إلى واجهة Mollie API، أو أن مفتاح API لوضع الدفعة غير مُعدّ. ستعيد Mollie محاولة الـ webhook لاحقًا.

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

يعرض عنوان الـ webhook في المتصفح Method not allowed.: هذا طبيعي. العنوان يقبل الطلبات الواردة من Mollie فقط.

لا يُحفظ مفتاح API: يجب أن يبدأ المفتاح بـ test_ أو live_ متبوعًا بـ 30 حرفًا وأرقامًا على الأقل. انسخه من جديد من Mollie Dashboard.

يرى العميل خطأ عند اختيار Mollie: انظر إلى حقل Log في صفحة الوحدة. يعرض رمز HTTP ورسالة Mollie. يعني 401 مفتاح API خاطئًا؛ ويشير 422 إلى حقل في الطلب، مثل مبلغ أو عملة لا تقبلها Mollie.

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

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

عملات أو بيانات دفع أخرى: يمكن للمطورين تغيير قائمة العملات بالخطاف actionWcpMollieSupportedCurrencies، وطلب الدفع بالخطاف actionWcpMolliePaymentData.

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

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

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