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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. مع إصدار أقدم من WooCommerce تعرض الإضافة إشعارًا ولا يتم تحميلها.

PHP: 8.0 أو أحدث.

العملة: يجب أن تكون عملة المتجر أو الطلب إحدى العملات SAR أو AED أو USD أو EUR أو KWD أو BHD أو OMR. ولأي عملة أخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب Moyasar: تحتاج إلى مفاتيح API السرية لحسابك لدى Moyasar (للاختبار وللإنتاج). ولا تُستخدم إلا المفاتيح السرية. ولا حاجة إلى المفتاح القابل للنشر (publishable key) لأن الدفع يتم في صفحة Moyasar. ويُنصح بإعداد webhook في Moyasar Dashboard (انظر قسم الإعدادات).

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

التثبيت

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

2. انقر على Activate.

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

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

5. الصق مفاتيح Moyasar السرية واحفظ. ثم أعدّ webhook في Moyasar Dashboard باستخدام الرابط والسر المشترك المعروضين في الإعدادات (انظر قسم الإعدادات).

6. فعّل Enable/Disable. أجرِ طلبًا تجريبيًا في وضع الاختبار، ثم ألغِ تحديد Test mode.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Moyasar. يعرض عنوان الصفحة شارة TEST MODE أو LIVE. وفوق الحقول، تنبهك الصفحة عندما لا يحتوي الوضع الحالي على مفتاح سري (فتُخفى طريقة الدفع حينئذ في صفحة الدفع) أو عندما لا تكون عملة المتجر مدعومة، وتعرض Test mode is active: payments are simulated, no money is charged. طالما كان وضع الاختبار مفعّلًا. وفي قائمة طرق الدفع، يُوسم Moyasar بأنه بحاجة إلى إعداد إلى أن يحتوي الوضع الحالي على مفتاح سري. وعند الحفظ، ترفض الإضافة المفتاح القابل للنشر، أو مفتاحًا من الوضع الآخر، أو مفتاحًا يحتوي على مسافات، وتحتفظ بالقيمة السابقة وتعرض السبب. كما تنبّه إذا كانت البوابة مفعّلة لكن المفتاح السري للوضع الحالي فارغ.

عام

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. الافتراضي: Pay with Moyasar.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. وفي وضع الاختبار تضيف صفحة الدفع العبارة (Test mode: no real payment is made.).

مفاتيح API

انسخ المفاتيح السرية من Moyasar Dashboard > Settings > API Keys. مفاتيح الاختبار ومفاتيح الإنتاج منفصلة. ويستخدم وضع الاختبار مفتاح الاختبار فقط، ويستخدم وضع الإنتاج مفتاح الإنتاج فقط.

Test mode: Enable test mode يستخدم المفتاح السري للاختبار: تُحاكى المدفوعات ولا يُخصم أي مبلغ. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية بالمفتاح السري للإنتاج.

Test secret key: المفتاح السري لوضع الاختبار. يبدأ بـ sk_test_.

Live secret key: المفتاح السري لوضع الإنتاج. يبدأ بـ sk_live_.

إشعارات الدفع (webhook)

يُنصح بـ webhook لكنه ليس إلزاميًا. وتُؤكَّد الطلبات أيضًا عندما يعود العميل إلى المتجر، وعبر إشعار الفاتورة الذي ترسله Moyasar تلقائيًا إلى متجرك عند دفع الفاتورة. ويغطي webhook العملاء الذين يغلقون المتصفح قبل العودة، ويخبرك بعمليات الاسترداد التي تتم في Moyasar Dashboard. في Moyasar Dashboard > Settings > Webhooks أضف webhook بالرابط والسر المشترك الواردين في هذا القسم، وطريقة HTTP هي POST.

Webhook URL: يُعرض للقراءة فقط مع زر Copy. ويبدو هكذا: https://your-site/wp-json/moyasar_p/v1/webhook. طريقة HTTP: POST.

Webhook shared secret: أدخل القيمة نفسها الموجودة في Shared secret للـ webhook في Moyasar. اترك الحقل فارغًا واحفظ لتوليد سر عشوائي، ثم انقر على Show وانسخه إلى Moyasar. ويُرفض أي webhook لا يحمل السر المشترك الصحيح.

اختر هذه الأحداث للـ webhook:

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

الطلبات

Status after payment: حالة الطلب بعد تأكيد الدفع. تُضبط الحالة فورًا دون تغيير ثانٍ.

متقدم

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

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. تبقى بيانات الدفع المحفوظة في الطلبات (معرّفات فاتورة Moyasar ودفعتها) لتظل عمليات الاسترداد قابلة للتتبع. الافتراضي: معطّل.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Pay with Moyasar) ويقدّم الطلب. تنشئ الإضافة فاتورة Moyasar بإجمالي الطلب بعملة الطلب، وتنقل العميل إلى صفحة الدفع. وهناك يدفع العميل بأي طريقة مفعّلة في حسابك لدى Moyasar، مثل mada أو Visa أو Mastercard أو Apple Pay أو STC Pay. وتعرض الفاتورة Order ورقم الطلب واسم موقعك.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Moyasar: تقرأ الإضافة الفاتورة من واجهة Moyasar البرمجية، وتتحقق من أنها مدفوعة، وأنها تخص هذا الطلب، وأن مبلغها وعملتها يطابقان الطلب تمامًا. وبعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. وإذا عاد العميل دون أن يدفع (مثلًا بزر الرجوع في صفحة الدفع)، يعود إلى صفحة الدفع أو إلى صفحة Pay for order مع إحدى هذه الرسائل: The payment at Moyasar was not completed. You can try again or choose another payment method.، أو Your Moyasar payment was declined or has expired. Please try again or choose another payment method.، أو، عندما لا يمكن التحقق من الدفع بعد، We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again.

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

وإذا تعذّر على Moyasar بدء الدفع، يرى العميل رسالة قصيرة، مثل The Moyasar payment service is not responding. Please try again in a few minutes.، ويمكنه اختيار طريقة دفع أخرى. وتُكتب التفاصيل في السجل.

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

تقبل الإضافة المدفوعات لمرة واحدة فقط في صفحة Moyasar. ولا يوجد نموذج بطاقة في صفحة الدفع الخاصة بمتجرك، ولا بطاقات محفوظة أو ترميز (tokenization)، ولا WooCommerce Subscriptions، ولا تفويض وتحصيل منفصلان.

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

حالات الطلب

Pending payment: أُنشئت الفاتورة ولم يدفع العميل بعد. تعرض ملاحظة الطلب معرّف الفاتورة والمبلغ والوضع.

Processing أو Completed أو On hold: تم تأكيد الدفع. وتتبع الحالة إعداد Status after payment. وتعرض ملاحظة الطلب كيفية تأكيد الدفع (webhook أو إشعار الفاتورة أو عودة العميل أو صفحة الدفع)، ومعرّف الفاتورة، ومعرّف الدفعة، وطريقة الدفع. ومعرّف المعاملة هو معرّف دفعة Moyasar.

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

On hold before payment: تحتجز Moyasar الدفعة للمراجعة. ويُحدَّث الطلب عندما تقرر Moyasar.

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

Cancelled: أُلغي الطلب من العميل أو منك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce. وتُلغى أيضًا فاتورة Moyasar المفتوحة للطلب، فلم تعد قابلة للدفع.

لا يتغيّر الطلب المدفوع أو الملغى أو المسترد أبدًا بسبب أحداث لاحقة. وإذا دُفعت فاتورة ثانية لطلب مدفوع بالفعل (مثلًا من علامتي تبويب في المتصفح)، فلا يُعدَّل الطلب مرة أخرى. وتطلب ملاحظة منك استرداد الدفعة المكررة في Moyasar Dashboard.

الاستردادات

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

تصل عمليات الاسترداد والإلغاء التي تتم في Moyasar Dashboard عبر webhook. وإذا أظهرت Moyasar مبلغًا مستردًا أكبر مما يسجله WooCommerce، تُضاف ملاحظة إلى الطلب. ولا تُسجَّل هذه العمليات تلقائيًا كاستردادات في WooCommerce. وإذا لزم الأمر، أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Pay with Moyasar.

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

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

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

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

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

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

لا يظهر Moyasar في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على مفتاح سري (Test secret key في وضع الاختبار، وLive secret key في وضع الإنتاج)، وأن عملة المتجر أو الطلب هي SAR أو AED أو USD أو EUR أو KWD أو BHD أو OMR. وتعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو العملة غير مدعومة.

تمت عملية الدفع لكن الطلب يبقى في حالة Pending payment: لم تصل التأكيدات إلى متجرك. أعدّ webhook: في Moyasar Dashboard تحقق من وجوده، وأن رابطه مطابق تمامًا لـ Webhook URL في الإعدادات، وأن الطريقة POST، وأن الأحداث الأربعة محددة، وأن سره المشترك يساوي Webhook shared secret. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر، وعندما يحاول دفع الطلب نفسه مرة أخرى.

يرد webhook بالرسالة Unauthorized: السر المشترك في Moyasar يختلف عن Webhook shared secret. انقر على Show، وانسخ القيمة، والصقها في webhook داخل Moyasar.

يرد webhook بالرسالة Webhook secret not configured: لم تُحفظ الإعدادات بعد مع سر مشترك. احفظ الإعدادات لتوليده، وانسخه إلى Moyasar.

يرد webhook بالرسالة Key not configured: دُفع الطلب في وضع (اختبار أو إنتاج) مفتاحه السري فارغ. أدخل ذلك المفتاح.

يرد webhook بالرسالة Verification failed أو Try again later: تعذّرت قراءة الفاتورة من واجهة Moyasar البرمجية، أو كان الطلب يُحدَّث بطلب آخر في اللحظة نفسها. ستعيد Moyasar محاولة الـ webhook.

خطأ عند الحفظ يتعلق بالمفتاح: لُصق مفتاح قابل للنشر (pk_...) أو مفتاح من الوضع الآخر. حُفظت القيمة السابقة. تبدأ مفاتيح الاختبار بـ sk_test_، وتبدأ مفاتيح الإنتاج بـ sk_live_.

يرى العميل خطأً عند تقديم الطلب: فعّل Debug log وراجع WooCommerce > Status > Logs، ومصدرها wcp_moyasar_payment_gateway. وعادةً ما تعني This payment method is temporarily unavailable. Please choose another payment method or contact us. أن المفتاح السري خاطئ أو مفقود. وتعني A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. أن الطلب لديه فاتورة مدفوعة تحتاج إلى مراجعتك.

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

يفشل الاسترداد: اقرأ الرسالة. إذا تمت الدفعة في الوضع الآخر، فأدخل المفتاح السري لذلك الوضع. وإذا كان المبلغ أكبر من المبلغ القابل للاسترداد لدى Moyasar، فقد استُرد جزء من الدفعة مسبقًا، مثلًا من Moyasar Dashboard. وإذا لم تؤكد Moyasar المبلغ المسترد، فتحقق من الدفعة في Moyasar Dashboard قبل المحاولة مرة أخرى.

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

الإزالة

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

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