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

المتطلبات

OpenCart: الإصدار 3.0.x (تم اختباره على 3.0.5.0) أو 4.0.2 وما بعده (تم اختباره على 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

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

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

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

التثبيت

التنزيل ملف zip واحد يضم حزم إصداري OpenCart. فُكَّ ضغطه على جهاز الكمبيوتر لديك. يحتوي الملف على README.txt، وحزمة OpenCart 3 wcp_moyasar_payment_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_moyasar_payment_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف wcp_moyasar_payment_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على أي تعديلات OCMOD، لذا لا يلزم تحديث Extensions > Modifications. وبدلًا من أداة التثبيت يمكنك نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذري لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Moyasar Payment Gateway واضغط Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

4. ألصق المفاتيح السرية لـ Moyasar واضغط Save. يُنشئ الحفظ الأول المفتاح السري المشترك للـ webhook ويعرضه مرة واحدة فوق الإعدادات. أعدّ الـ webhook في لوحة Moyasar Dashboard باستخدام هذا المفتاح (انظر الإعدادات).

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، واضغط Upload، ثم اختر الملف wcp_moyasar_payment_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة إن أُعيدت تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. اضغط Install (زر + الأخضر) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Moyasar Payment Gateway، واضغط Install (زر + الأخضر)، ثم Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح Moyasar والـ webhook كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين، ويختلف عنوان الـ webhook فقط (انظر Webhook URL).

يبدأ التثبيت الجديد وطريقة الدفع معطّلة ووضع الاختبار مفعّل.

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Moyasar Payment Gateway > Edit. تظهر الأقسام في الجهة اليسرى؛ ويحفظ الزر Save الموجود أسفل القائمة الصفحة بأكملها. وفوق الإعدادات تنبهك الصفحة عندما لا يملك الوضع الحالي مفتاحًا سريًا (وتُخفى طريقة الدفع حينها في صفحة الدفع)، وعندما لا يكون هناك مفتاح سري مشترك محفوظ للـ webhook (فيرفض الـ webhook حينها كل استدعاء)، وعندما لا تكون العملة الافتراضية للمتجر مدعومة. وبينما تكون الإضافة مفعّلة في وضع الاختبار تعرض وضع الاختبار مفعّل: تُحاكى المدفوعات ولا يُخصم أي مبلغ. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب أن يكون طول Title بين 1 و128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total عددًا أكبر من أو يساوي 0، ويجب أن توجد المنطقة الجغرافية وحالات الطلب؛ وإلا فلن يُحفظ شيء. ترفض الإضافة مفتاحًا قابلًا للنشر، أو مفتاحًا من الوضع الآخر، أو مفتاحًا يحتوي على مسافات: تُحفظ بقية الإعدادات مع الرسالة تم حفظ الإعدادات، باستثناء المفتاح المعروض باللون الأحمر. ويبقى المفتاح السابق كما هو، ويظهر سبب الرفض. وإذا فُعّلت الإضافة دون المفتاح السري للوضع الحالي، تُحفظ الإعدادات مع تحذير.

Moyasar

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا الاسم المحفوظ في الطلب. الافتراضي: Pay with Moyasar. حقل مطلوب، بحد أقصى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order، أعلى زر التأكيد. الافتراضي: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. وفي وضع الاختبار تُضيف هذه الخطوة (وضع الاختبار: لا تُجرى أي دفعة فعلية.)

Sort Order: ترتيب Moyasar بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Moyasar فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعرَّف المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يصل إليه الطلب قبل عرض Moyasar. اتركه فارغًا لعرض Moyasar مهما كان الإجمالي.

مفاتيح API

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

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

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

Live secret key: المفتاح السري للوضع الفعلي. يبدأ بالبادئة sk_live_.

لا تُعرض المفاتيح والأسرار المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للإبقاء عليه. اكتب قيمة جديدة فقط إذا أردت تغييرها. ولحذف قيمة محفوظة، ضع علامة على Clear the saved value on save أسفل الحقل، ثم اضغط Save.

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

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

Webhook URL: يُعرض للقراءة فقط مع زر Copy. يبدو على OpenCart 3 كالتالي: https://your-store/index.php?route=extension/payment/wcp_moyasar_payment_gateway/webhook، وعلى OpenCart 4 كالتالي: https://your-store/index.php?route=extension/wcp_moyasar_payment_gateway/payment/wcp_moyasar_payment_gateway.webhook. ويُبنى من عنوان واجهة المتجر لتثبيت OpenCart الخاص بك. انسخ العنوان تمامًا كما تعرضه الإعدادات. طريقة HTTP: POST. يجب أن يكون العنوان متاحًا عبر الإنترنت.

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

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

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

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب ناقص). لا يحصل الطلب على حالة إلا بعد أن تؤكد Moyasar الفاتورة. تسرد كل خانة أدناه حالات الطلب في OpenCart الخاص بك.

Status after payment: الحالة التي تُعيَّن بعد دفعة مؤكدة. الافتراضي: قيد المعالجة. اختر Complete إذا أردت إكمال الطلبات المدفوعة فورًا، أو حالة المراجعة الخاصة بك إذا كان يجب أن ينتظر كل طلب مدفوع مراجعة يدوية.

Awaiting Moyasar payment status: تحتفظ Moyasar بالدفعة للمراجعة؛ وينتقل الطلب إلى Status after payment عندما تؤكدها Moyasar. الافتراضي: قيد الانتظار.

Moyasar payment on hold status: أبلغت Moyasar عن مبلغ أو عملة يختلفان عن إجمالي الطلب، أو دُفعت الفاتورة بعد إلغاء الطلب أو منحه حالة أخرى. لا يُعلَّم الطلب كمدفوع. الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة «معلّق». يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment error status: فشلت الدفعة قيد المراجعة. الافتراضي: فشل.

Refunded status: تُعيَّن بعد استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: مُسترَد.

متقدم

Debug log: يسجل استدعاءات الواجهة البرمجية والإشعارات في الملف moyasar_p_debug.log.php داخل مجلد السجلات في OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى moyasar_p_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تُسجَّل مفاتيح الواجهة البرمجية ولا بيانات البطاقة ولا تفاصيل العميل أبدًا. الافتراضي: معطّل.

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر المفاتيح والأسرار.

Import: ألصق ملف JSON صُدِّر سابقًا واضغط Import لاستعادة الإعدادات. تبقى المفاتيح والأسرار المحفوظة كما هي.

صفحة الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Pay with Moyasar). وفي خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. عندما يضغط العميل Confirm Order، تنشئ الإضافة فاتورة Moyasar بإجمالي الطلب بعملة الطلب، وتوجّه العميل إلى صفحة الدفع الخاصة بها. هناك يدفع العميل بأي وسيلة مفعّلة في حساب Moyasar لديك. على OpenCart 4 يختار العميل طريقة الدفع بالزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، ثم ينقر Confirm Order في أسفل صفحة الدفع. تعرض الفاتورة Order # ورقم الطلب واسم متجرك.

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

إذا عاد العميل دون أن يدفع (مثلًا بزر الرجوع في صفحة الدفع)، يعود إلى صفحة الدفع مع إحدى هذه الرسائل: لم تكتمل عملية الدفع عبر Moyasar. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.، رُفضت دفعتك عبر Moyasar أو انتهت صلاحيتها. يُرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.، أو عندما لا يمكن التحقق من الدفعة بعد، لم نتمكن من تأكيد دفعتك عبر Moyasar بعد. إذا أتممت الدفع، فسيُحدَّث الطلب تلقائيًا خلال دقائق — يُرجى التحقق من بريدك الإلكتروني قبل الدفع مرة أخرى. على OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع. تُحفظ السلة.

يمكن للعميل المحاولة مرة أخرى. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيحتفظ بطلب واحد للدفع ويعيد دفع الطلب نفسه. تتحقق الإضافة أولًا من الفواتير المفتوحة للسلة نفسها: إذا كانت صفحة الدفع المفتوحة لهذا الطلب ما زالت تحمل الوضع والمبلغ والعملة نفسها، فإنها تُعاد استخدامها؛ وإلا فستُلغى الفاتورة القديمة في Moyasar وتُنشأ فاتورة جديدة، بحيث لا يمكن دفع القديمة بعد الآن. وإذا تبيّن أن إحدى الفواتير السابقة للسلة مدفوعة بالفعل، فستُؤكَّد تلك الدفعة بدلًا من إنشاء دفعة جديدة.

يُبقي OpenCart 4 الطلب في عملية الدفع حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا إذا ألغيته أو فشلت دفعته)، يعود العميل إلى الدفع مع الرسالة Your previous order was cancelled or its payment failed. Please confirm the order again.، وينشئ Confirm Order التالي طلبًا جديدًا للدفع. أما الطلب الذي دُفع ثم أُلغي أو أُسترد فلا يُبقي السلة محجوزة بعد الآن.

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

يعمل الـ webhook وإشعار الفاتورة أيضًا أثناء وجود المتجر في وضع الصيانة، لأن OpenCart 3 يسمح بمرور طلبات إضافات الدفع، وعلى OpenCart 4 تُضيف الإضافة إجراء بدء تشغيل (startup action) لهذه الطلبات، وهو يسمح للعميل أيضًا بالعودة من Moyasar.

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

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

حالات الطلب

بلا حالة (طلب ناقص): أُرسل العميل إلى Moyasar ولم يدفع، أو لم تؤكد Moyasar الدفعة بعد، أو رُفضت الدفعة أو انتهت صلاحيتها أو أُلغيت. في Sales > Orders تظهر هذه الطلبات فقط عند ضبط فلتر Order Status على Missing Orders.

Order Status After Payment (الافتراضي قيد المعالجة): أكدت Moyasar الدفعة مع المبلغ والعملة المطابقين تمامًا للطلب. تعرض ملاحظة الطلب كيفية تأكيد الدفعة (الـ webhook، أو إشعار الفاتورة، أو عودة العميل، أو الدفع)، ومعرّف الفاتورة، ومعرّف الدفعة، وطريقة الدفع، مثل علامة البطاقة وأربعة أرقام أخيرة.

Awaiting Moyasar payment status (الافتراضي قيد الانتظار): تحتفظ Moyasar بالدفعة للمراجعة. ينتقل الطلب إلى Status after payment عندما تؤكد Moyasar الدفعة، أو إلى Payment error status عندما تفشل.

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

Payment error status (الافتراضي فشل): فشلت الدفعة قيد المراجعة.

Refunded status (الافتراضي مُسترَد): استُردت الدفعة بالكامل من خلال الإضافة.

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

الملاحظات هي إدخالات في History الطلب لا يراها العميل.

تبويب VibeFox Moyasar Payment Gateway

في Sales > Orders افتح طلبًا دُفع عبر Moyasar. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Moyasar Payment Gateway الفاتورة Moyasar invoice (مع تسمية Test mode للدفعات التجريبية)، وMoyasar payment، وMethod، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد، وMoyasar notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

في تبويب VibeFox Moyasar Payment Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم اضغط Refund via Moyasar. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Moyasar؟ لا يمكن التراجع عن هذا الإجراء. يُدعم الاسترداد الكامل والجزئي. تحتاج إلى صلاحية تعديل الإضافة (وتُحدَّد في System > Users > User Groups). تُنفَّذ عمليات الاسترداد بالمبلغ والعملة اللذين خصمتهما Moyasar؛ لذلك بعد وجود فارق في المبلغ يمكنك استرداد ما دفعه العميل فعلًا، لا إجمالي الطلب. يُعالَج الاسترداد الكامل لبطاقة دُفعت خلال أقل من ساعتين كإلغاء (void: إلغاء قبل التسوية دون رسوم)؛ أما المدفوعات عبر STC Pay وجميع الحالات الأخرى فتُسترد بشكل عادي. يستخدم الاسترداد المفتاح السري للوضع الذي تمت فيه الدفعة (الاختبار أو الفعلي)، لذلك يجب أن يكون ذلك المفتاح مضبوطًا. تتحقق الإضافة أولًا لدى Moyasar من عملة الدفعة وحالتها والمبلغ القابل للاسترداد. وإذا لم تقبل Moyasar الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد أو الإلغاء الناجح إلى سجل الاسترداد والملاحظات. يُعيّن الاسترداد الكامل الطلب إلى Refunded status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا كتغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. وتكون عمليات الاسترداد متاحة بعد أن تؤكد Moyasar الدفعة.

لا ترسل المرتجعات في Sales > Returns أي أموال عبر Moyasar.

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Moyasar Payment Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Moyasar Payment Gateway > Edit، فوق الإعدادات. ألصق المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: opencart-payment-moyasar ورابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل 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. ويظل مستخدم الإدارة الذي سجّل الدخول إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع علامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. على OpenCart 4 هذه المعاينة غير متاحة: لا يرى المتجر تسجيل دخول الإدارة، لذلك بدون مفتاح فعّال تُخفى طريقة الدفع عن الجميع. بعد فتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بالزر × لإخفائه لمدة 7 أيام. لا تتأثر الطلبات الحالية: تظل الدفعات التي بدأت مؤكدة، وتعمل عمليات الاسترداد.

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

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

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

تمت الدفعة لكن الطلب بقي بلا حالة: لم تصل التأكيدات إلى متجرك. اضبط الـ 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 the saved value on save. اضغط 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_.

يرى العميل خطأً بعد Confirm Order: فعّل Debug log وانظر خانة Log في صفحة الإضافة. تعني الرسالة This payment method is not available. أن جلسة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في هذه الأثناء: على العميل إعادة تحميل صفحة الدفع. وتشير الرسالة 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. أن السلة تحتوي فعلًا على فاتورة مدفوعة لم يتمكن النظام من ضبط حالة طلبها؛ راجع السجل.

الطلب في حالة التعليق بعد الدفع: اقرأ Moyasar notes في تبويب VibeFox Moyasar Payment Gateway. كان المبلغ أو العملة المدفوعان مختلفين عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. نفّذ الطلب أو استرد الدفعة.

لا يوجد نموذج استرداد في التبويب: يذكر التبويب السبب: الدفعة غير مؤكدة بعد، أو مستردة بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة.

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

للمطورين: تُطلق الإضافة أحداث OpenCart التالية moyasar_p_supported_currencies وmoyasar_p_invoice_params لتغيير العملات المدعومة وبيانات الفاتورة.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم اضغط Uninstall (الزر الأحمر −) بجوار VibeFox Moyasar Payment Gateway. يُزال مفتاح ترخيص هذه الإضافة وحالة الترخيص دائمًا. يزيل OpenCart إعدادات الإضافة الخاصة به دائمًا: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلب في قسم Orders، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما يُزال حدث OpenCart الخاص بالإضافة (وعلى OpenCart 4 أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح للـ webhook بالمرور في وضع الصيانة). وإذا كان Clean uninstall مفعّلًا، تُزال بقية إعدادات البوابة (العنوان والوصف ووضع الاختبار والمفاتيح والسر المشترك للـ webhook وسجل التصحيح) والسجل. وإذا كان معطّلًا فتُحفظ لإعادة التثبيت لاحقًا. تُحفظ سجلات الفواتير والمدفوعات والاسترداد الخاصة بـ Moyasar دائمًا، لذلك يمكن استرداد الطلبات القديمة المدفوعة بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

على OpenCart 4، ولإزالة ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد الإلغاء، واضغط Uninstall (الزر البرتقالي −) بجوار VibeFox Moyasar Payment Gateway في قائمة الإضافات المثبتة، ثم Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

Moyasar علامة تجارية مسجّلة لمالكها. هذه الإضافة غير تابعة لـ Moyasar ولا معتمدة من قبلها.