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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

4. الصق مفاتيح Moyasar السرية وانقر على Save. اضبط webhook في Moyasar Dashboard (انظر الإعدادات).

5. فعّل Enable/Disable وانقر على Save. نفّذ طلبًا تجريبيًا في وضع الاختبار، ثم أوقف Test mode.

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

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure. ولكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذرك الصفحة عندما لا يوجد مفتاح سري للوضع الحالي (فتُخفى طريقة الدفع في صفحة الدفع حينها)، أو عندما لا يكون سر webhook المشترك محفوظًا (فيرفض webhook حينها كل استدعاء)، أو عندما لا تكون العملة الافتراضية للمتجر مدعومة. وعندما تكون الوحدة مفعّلة في وضع الاختبار تعرض الرسالة 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: يستخدم المفتاح السري للاختبار: تُحاكى المدفوعات ولا يُخصم أي مبلغ. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية بالمفتاح السري للإنتاج.

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

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

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

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

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

Webhook URL: يُعرض للقراءة فقط مع زر Copy. وعند تفعيل الروابط الودية يبدو هكذا: https://your-shop/module/wcp_moyasar_payment_gateway/webhook، وقد يحتوي على رمز لغة مثل /en/. انسخ الرابط تمامًا كما تعرضه الإعدادات. طريقة HTTP: POST.

Webhook shared secret: أدخل القيمة نفسها الموجودة في Shared secret للـ webhook في Moyasar. إذا لم يكن هناك شيء محفوظ، فإن Save يولّد سرًا عشوائيًا؛ وGenerate a new secret يستبدل السر المحفوظ. يظهر السر المُولَّد مرة واحدة فقط فوق الإعدادات بعد الحفظ ولا يظهر بعد ذلك، لذلك انسخه إلى Moyasar فورًا. ويُرفض أي webhook بلا السر المشترك الصحيح.

اختر هذه الأحداث للـ webhook (وهي مدرجة أيضًا في هذا القسم):

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

الطلبات

Status after payment: حالة الطلب التي تُعيَّن بعد تأكيد الدفع. يُنشأ الطلب مباشرة بهذه الحالة.

متقدم

Clear saved secrets: لإزالة أي سر، حدد Test secret key أو Live secret key أو Webhook shared secret ثم انقر على Save. وإذا كان الحقل فارغًا تبقى القيمة المحفوظة كما هي.

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

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

Clean uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وسجلها. أما بيانات الدفع المحفوظة مع الطلبات (معرّفات الفاتورة والدفعة في Moyasar) فتبقى، حتى تظل الاستردادات قابلة للتتبع. الافتراضي: معطّل.

صفحة الدفع

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

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Moyasar: تقرأ الوحدة الفاتورة من واجهة Moyasar البرمجية وتتحقق من أنها مدفوعة، وأنها تخص هذه السلة، وأن مبلغها وعملتها مطابقان تمامًا لمبلغ السلة وعملتها. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with Moyasar has been received. وإذا احتجزت Moyasar الدفعة للمراجعة، تعرض الصفحة Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. وإذا كان الطلب في حالة الانتظار لمراجعتك، تبيّن الصفحة أن الدفعة استُلمت وأن الطلب قيد المراجعة. وإذا فشلت دفعة قيد المراجعة لاحقًا، أو أُلغي الطلب غير المدفوع، تعرض الصفحة Your Moyasar payment was not completed. Please contact us about this 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 وتُنشأ صفحة جديدة، فلا يمكن دفع الصفحة القديمة بعد الآن. وإذا تبيّن أن الفاتورة السابقة مدفوعة بالفعل، يُنشأ الطلب بدلًا من دفعة جديدة.

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

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

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

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

حالات الطلب

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

Payment accepted أو Delivered أو Moyasar payment on hold: تم تأكيد الدفعة. وتتبع الحالة Status after payment. تُسجَّل الدفعة بمعرّف دفعة Moyasar كمعرّف للمعاملة، ويوضح ملاحظة كيفية تأكيد الدفعة (webhook أو إشعار الفاتورة أو عودة العميل أو صفحة الدفع)، ومعرّف الفاتورة، ومعرّف الدفعة، وطريقة الدفع.

Awaiting Moyasar payment: تحتجز Moyasar الدفعة للمراجعة. ينتقل الطلب إلى حالة المدفوع عندما تؤكد Moyasar الدفعة.

خطأ في الدفع: فشلت الدفعة التي كانت قيد المراجعة.

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

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

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

كتلة الدفع في Moyasar

تعرض صفحة الطلب كتلة Moyasar payment تتضمن معرّف فاتورة Moyasar، ومعرّف الدفعة، وطريقة الدفع (مثل علامة البطاقة وآخر أربعة أرقام)، والحالة، والمبالغ المدفوعة والمستردة، وشارة Test mode لمدفوعات الاختبار، وسجل الاستردادات، وMoyasar notes الخاصة بالطلب.

الاستردادات

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

لا تنشئ الوحدة إشعارات دائنة. ولا تُعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Moyasar.

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

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

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

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

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

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

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

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

يرد webhook بـ Unauthorized: السر المشترك في Moyasar يختلف عن المحفوظ. أدخل سر webhook الخاص بـ Moyasar في Webhook shared secret واحفظ، أو حدد Generate a new secret واحفظ ثم الصق السر المعروض في Moyasar.

يرد webhook بـ Webhook secret not configured: لا يوجد سر مشترك محفوظ، مثلًا بعد إزالته بـ Clear saved secrets. انقر على Save لتوليد سر وانسخه إلى Moyasar.

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

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

يعرض رابط webhook الرسالة Method not allowed في المتصفح: هذا طبيعي. الرابط يقبل طلبات POST من Moyasar فقط.

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

يرى العميل خطأً عند اختيار Moyasar: فعّل Debug log وانظر إلى حقل Log في صفحة الوحدة. وتشير الرسالة 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. أن السلة لديها فاتورة مدفوعة تعذر تحويلها إلى طلب؛ راجع السجل.

Order is Moyasar payment on hold after payment: اقرأ Moyasar notes في كتلة Moyasar payment. كان المبلغ أو العملة المدفوعة مختلفًا عن السلة، أو وصلت الدفعة بعد إلغاء الطلب. أنجز الطلب أو استرد الدفعة.

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

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

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

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