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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: إحدى العملات التي تدعمها 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. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد wcp_mollie_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

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

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

5. أدخل مفاتيح API الخاصة بالاختبار والإنتاج (راجع قسم الإعداد). لا حاجة لإعداد أي webhook في Mollie.

6. فعّل Enable/Disable. أبقِ Test Mode مفعّلًا حتى تُجري دفعة اختبار، ثم ألغِ تحديده.

الإعداد

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

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

الدفع

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

Title: عنوان طريقة الدفع الذي يظهر للعميل أثناء الدفع. الافتراضي: Mollie.

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

مفاتيح API

تجد مفاتيح API في Mollie Dashboard > Developers > API keys. لا حاجة إلى إعداد webhook: ترسل الإضافة عنوان الـ webhook الخاص بها مع كل دفعة. ويظهر العنوان في هذا القسم بالشكل التالي: https://your-site/?wc-api=molg_mollie_webhook. ويجب أن يكون متاحًا من الإنترنت، وإلا فلن تُحدَّث الطلبات إلا عند عودة العميل من Mollie.

Test Mode: Enable test mode يستخدم مفتاح API الخاص بالاختبار للدفعات الجديدة. لا تُعالَج أي مدفوعات حقيقية. وفي صفحة دفع الاختبار لدى Mollie يمكنك اختيار النتيجة (paid, failed, cancelled, expired). ويرى العملاء في صفحة الدفع العبارة Test mode: no real payment will be made.. أما الدفعات التي أُجريت في الوضع الآخر فتستمر في استخدام مفتاح وضعها الخاص عند فحص الحالة وعند الاسترداد. الافتراضي: مفعّل.

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

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

الطلبات

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

متقدم

Logging: Enable debug logging يكتب استدعاءات API والـ webhooks في WooCommerce > Status > Logs، بالمصدر wcp_mollie_gateway. وتُسجَّل الأخطاء دائمًا. ولا تُسجَّل مفاتيح API ولا بيانات العملاء أبدًا. الافتراضي: معطّل.

Delete Data on Uninstall: Remove the plugin settings and logs when uninstalling. عند تحديده تُحذف إعدادات الإضافة وملفات السجل عند حذف الإضافة. وتبقى معرّفات دفعات Mollie المحفوظة في الطلبات. الافتراضي: معطّل.

الدفع

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

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

عند عودة العميل تتحقق الإضافة من آخر دفعة عبر واجهة Mollie API بالطريقة نفسها. فإذا كانت الدفعة مدفوعة يُوجَّه العميل إلى صفحة «تم استلام الطلب». أما إذا أُلغيت الدفعة أو فشلت أو انتهت صلاحيتها أو لم تكتمل، فيُنقل العميل إلى صفحة Pay for 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 المفتوحة بالمبلغ نفسه بدلًا من إنشاء دفعة ثانية قابلة للدفع. وإذا تغير إجمالي الطلب، تُلغى الدفعة المفتوحة القديمة في 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. وتُضاف السبب التقني إلى ملاحظات الطلب والسجل.

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

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

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

حالات الطلب

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

Processing or Completed: تم تأكيد الدفع. تتبع الحالة الإعداد Order Status After Payment. تُظهر ملاحظة الطلب دفعة Mollie وطريقة الدفع والوضع. ومعرّف المعاملة هو معرّف دفعة Mollie (tr_...) الذي دفع الطلب.

On hold: يوجد تحويل مصرفي ينتظر وصول المال، أو دفعة معتمدة تنتظر التحصيل، أو أبلغت Mollie عن اعتراض (chargeback). كما تُعيَّن هذه الحالة عندما يختلف المبلغ المدفوع أو العملة عن الطلب، أو عندما تُدفع دفعة اختبار والمتجر في الوضع الحي (لم يُستلم أي مال)، أو عندما تصل الدفعة بعد إلغاء الطلب. وتشرح ملاحظة الطلب السبب. تحقق من الدفعة في Mollie Dashboard، ثم عالج الطلب أو استرد الدفعة.

Failed: فشلت آخر محاولة دفع أو انتهت صلاحيتها أو أُلغيت. لا يُغيَّر الطلب المدفوع أبدًا. ويمكن للعميل أن يدفع مرة أخرى.

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

الاستردادات

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

لا تتحول الاستردادات والاعتراضات التي أُنشئت في Mollie Dashboard إلى استردادات في WooCommerce. ويضيف الاعتراض ملاحظة فقط.

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

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

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

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

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

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

لا تظهر Mollie في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح API: Test API Key في وضع الاختبار، وLive API Key في الوضع الحي. وتحقق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) تدعمها Mollie. وتعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات.

اكتملت الدفعة لكن الطلب بقي في حالة Pending payment: لا يستطيع الـ webhook الوصول إلى موقعك. يجب أن يكون عنوان الـ webhook المعروض في الإعدادات متاحًا من الإنترنت (دون وضع الصيانة، أو المصادقة الأساسية، أو جدار حماية يحجبه). ويُحدَّث الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

Webhook answers Unknown payment.: معرّف الدفعة غير معروف لدى Mollie لمفتاح API الخاص بالاختبار أو الإنتاج، مثل دفعة تعود إلى حساب Mollie آخر.

Webhook answers Payment ID mismatch.: الدفعة، بحسب بياناتها، لا تخص هذا الطلب. ولا يتغير الطلب.

Webhook answers Failed to fetch payment.: تعذّر الوصول إلى واجهة Mollie API. ستعيد Mollie إرسال الـ webhook لاحقًا.

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

لا تُنشأ الدفعة: تُظهر ملاحظة الطلب والسجل رمز HTTP ورسالة Mollie. يعني 401 مفتاح API غير صحيح؛ ويشير 422 إلى حقل في الطلب، مثل مبلغ أو عملة لا تقبلها Mollie. فعّل Logging وراجع WooCommerce > Status > Logs، بالمصدر wcp_mollie_gateway.

الطلب في حالة On hold: اقرأ ملاحظة الطلب. والسبب قد يكون عدم تطابق المبلغ أو العملة، أو دفعة اختبار في الوضع الحي، أو دفعة بعد الإلغاء، أو تحويل مصرفي، أو تفويض بلا تحصيل، أو اعتراض.

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

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

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

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

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

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