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

المتطلبات

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

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

HTTPS: يجب أن يكون متجرك متاحًا عبر HTTPS من الإنترنت حتى تتمكن Comgate من تسليم الإشعار في الخلفية.

العملة: CZK أو EUR أو PLN أو HUF أو USD أو GBP أو RON أو HRK أو NOK أو SEK. بالنسبة للعملات الأخرى، وللمجاميع التي تقل عن الحد الأدنى لـ Comgate، تُخفى طريقة الدفع. تُقرَّب مدفوعات HUF إلى أقرب فورنت صحيح، كما تشترط Comgate.

حساب Comgate: تحتاج إلى معرّف التاجر (Merchant ID) والمفتاح السري (Secret، أي كلمة المرور للاتصال في الخلفية) لاتصال متجرك في بوابة العميل الخاصة بـ Comgate، وإلى عنوان الإشعار المُعدّ فيها (انظر الإعدادات). تستخدم Comgate المعرّف والمفتاح السري نفسيهما للمدفوعات التجريبية والحقيقية.

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

التثبيت

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

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

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

4. أدخل Merchant ID وSecret من بوابة العميل الخاصة بـ Comgate، وعيّن عنوان الإشعار هناك (انظر الإعدادات).

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Comgate Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول، تحذرك الصفحة عندما تكون Comgate مفعّلة لكن معرّف التاجر أو المفتاح السري غير مكتمل (وعندها تُخفى طريقة الدفع في صفحة الدفع إلى أن يُملأ الحقلان)، وعندما لا تكون العملة الافتراضية للمتجر مدعومة من Comgate. وأثناء تفعيل وضع الاختبار تعرض: Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.

Comgate

Enable / Disable: Enable Comgate Payment Gateway يفعّل طريقة الدفع أو يوقفها. Default: off.

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

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. في وضع الاختبار تُضاف إليه العبارة TEST MODE: no real money is charged.، أو تظهر وحدها إذا كان الوصف فارغًا.

اتصال Comgate

احصل على معرّف المتجر (Merchant ID) وكلمة المرور (Secret) من بوابة العميل الخاصة بـ Comgate، في Integration > shop connection settings. وفي المكان نفسه، عيّن URL for passing the payment result (الإشعار في الخلفية) إلى العنوان الظاهر في Notification URL ضمن هذا القسم. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_comgate_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات. تستدعيه Comgate بعد كل دفعة؛ وتعيد الوحدة بعدها التحقق من الدفع عبر واجهة حالة Comgate قبل أن تُجري أي تغيير. تُرسل عناوين العودة للعميل مع كل دفعة. وإذا طلبت البوابة عناوين عودة (مدفوع، ملغى، قيد الانتظار)، فاستخدم العنوان الثاني الظاهر في هذا القسم، وهو ينتهي بـ return?id=${id}&refId=${refId}.

Merchant ID: معرّف متجر Comgate (التاجر).

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

مسح المفتاح السري المحفوظ: ضع علامة ثم انقر على Save لإزالة المفتاح السري المحفوظ. يُبقي الحقل الفارغ القيمة المحفوظة.

Test Mode: يُنشئ دفعات تجريبية (لا يُخصم أي مبلغ). تستخدم Comgate المعرّف والمفتاح السري نفسيهما للدفعات التجريبية والحقيقية؛ وتُعلَّم الدفعات التجريبية بـ test=true. تُرسل عمليات الاسترداد دائمًا بوضع الدفعة الأصلية. Default: on.

صفحة الدفع

Payment Methods: طرق الدفع من Comgate التي يمكن للعميل الاختيار من بينها. لا تظهر إلا الطرق المفعّلة لمتجرك في Comgate.

Language: لغة صفحة الدفع في Comgate. Automatic (shop language, English as fallback) (الافتراضي) أو إحدى اللغات الـ 26.

الطلبات

Order Status After Payment: الحالة التي تُعيَّن عندما تؤكد Comgate الدفع.

المدفوعات التي لا تطابق الطلب، والدفعات التجريبية في وضع الإنتاج، والمدفوعات المفوّضة مسبقًا تذهب دائمًا إلى Comgate payment on hold.

متقدم

Debug Log: يكتب طلبات واجهة البرمجة والإشعارات في logs/comgate_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا يُسجَّل المفتاح السري ولا البيانات الشخصية أبدًا. تُسجَّل الأخطاء دائمًا. Default: off.

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Comgate) ويؤكد الطلب. تنشئ الوحدة الدفعة في Comgate بقيمة إجمالي السلة وبعملة السلة، وتوجّه العميل إلى صفحة الدفع الخاصة بـ Comgate. يُمرَّر البريد الإلكتروني واسم العميل إلى Comgate، وتُوسَم الدفعة بـ Cart مع رقم السلة. يلزم بريد إلكتروني صالح. في صفحة Comgate يدفع العميل بإحدى الطرق التي سمحت بها. لا يوجد طلب في هذه المرحلة بعد.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Comgate ذلك: تقرأ الوحدة الدفعة من واجهة حالة Comgate البرمجية، سواء عند وصول الإشعار في الخلفية أو عند عودة العميل. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية. إذا وُضع الطلب قيد المراجعة، تضيف الصفحة العبارة Your payment is being reviewed. We will contact you if anything else is needed. وإذا أُلغي طلب مُفوَّض مسبقًا لاحقًا، تعرض الصفحة Your Comgate payment was not completed. Please contact us about this order.

إذا لم تكن الدفعة مؤكدة عند عودة العميل، مثل تحويل بنكي ما زال في الطريق، تعرض صفحة Payment confirmation الرسالة Comgate has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. مع زر Check again وزر Back to checkout.

إذا أُلغيت الدفعة أو انتهت مدة صلاحيتها، يعود العميل إلى صفحة الدفع مع الرسالة The Comgate payment was cancelled or has expired. You can try again or choose another payment method. وتبقى السلة محفوظة. تفحص كل محاولة جديدة المحاولة السابقة أولًا، فلا تُخصم دفعة اكتملت بالفعل مرتين، وتُلغى المحاولة السابقة في Comgate إن كانت ما زالت مفتوحة. والدفعة المتأخرة لمحاولة أقدم تُنشئ الطلب أيضًا.

إذا تعذر على Comgate بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل The Comgate payment could not be started. Please try again or choose another payment method.، تفيد بأن Comgate لا تقبل هذا المبلغ أو هذه العملة، أو أن طريقة الدفع المختارة من Comgate غير متاحة. يُكتب السبب التقني في السجل.

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

تقتصر الوحدة على المدفوعات الفردية في صفحة Comgate فقط. لا تدعم المدفوعات المتكررة أو الاشتراكات أو البطاقات المحفوظة، ولا صفحة الدفع المضمّنة من Comgate، ولا أزرار Apple Pay أو Google Pay على موقعك (فهي متاحة في صفحة Comgate)، ولا تحصيل التفويضات المسبقة أو إلغاؤها من PrestaShop. ومن دون الإشعار لا يُستعلم عن حالة الدفع تلقائيًا، بل تُفحص فقط عند عودة العميل.

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Comgate ولم يدفع بعد، أو أن Comgate تُبلغ بأن الدفعة قيد الانتظار. الموجود هو السلة فقط.

Payment accepted or Delivered: أبلغت Comgate بأن الدفعة PAID بالمبلغ والعملة نفسيهما. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة بمعرّف معاملة Comgate. تحصل الدفعات التجريبية على الملاحظة Comgate test payment — no money was charged.

Comgate payment on hold: المبلغ أو العملة المدفوعة يختلفان عن الطلب، أو أُكدت دفعة تجريبية والمتجر في وضع الإنتاج (لم يُستلم أي مال)، أو أن الدفعة مفوَّضة فقط (تفويض مسبق في حسابك لدى Comgate). تصبح الدفعة المفوَّضة مدفوعة تلقائيًا عند تحصيلها في بوابة Comgate. وتشرح الملاحظة السبب.

Canceled: أُلغيت دفعة مفوَّضة أو انتهت صلاحيتها في Comgate. إذا أكدت Comgate الدفع بعد ذلك، يُعاد فتح الطلب كمدفوع مع ملاحظة تطلب التحقق من المخزون قبل الشحن.

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

إذا أبلغت Comgate عن دفعة PAID أخرى لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة التحقق من ذلك في بوابة Comgate واسترداد المبلغ المكرر. ولا يعيد تأكيدٌ مُعاد إرساله فتح طلب مُسترد أبدًا.

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

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

الاسترداد

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

الاسترداد متاح للطلبات المدفوعة فقط. لا يمكن استرداد طلب موضوع قيد الانتظار بعد اختلاف المبلغ أو العملة من PrestaShop؛ استرده من بوابة Comgate. لا تنشئ الوحدة إشعارات دائن. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا ترسل المال عبر Comgate. والاستردادات التي تُجرى في بوابة Comgate لا تُبلَّغ إلى المتجر.

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

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

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

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

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

لا تظهر Comgate في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن Merchant ID وSecret مملوآن، وأن عملة السلة مدعومة، وأن إجمالي الطلب ليس أقل من الحد الأدنى لـ Comgate (مثلًا 1 CZK أو 0.10 EUR أو 100 HUF). وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

تمت الدفعة لكن لم يُنشأ أي طلب: لم تسلّم Comgate الإشعار في الخلفية. تحقق من URL for passing the payment result في بوابة Comgate (يجب أن يطابق Notification URL في الإعدادات تمامًا)، ومن أن متجرك متاح عبر HTTPS من الإنترنت، ومن السجل (فعّل Debug Log). تعيد Comgate إرسال الإشعارات غير المسلَّمة؛ وترد الوحدة بخطأ في كل مرة لا تعالج فيها إشعارًا، فسيُعاد إرساله. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر.

يرد الإشعار بـ Invalid merchant or secret: معرّف التاجر أو المفتاح السري في الإعدادات لا يطابق اتصال المتجر في بوابة Comgate.

يرد الإشعار بـ Gateway not configured: معرّف التاجر أو المفتاح السري فارغ في الإعدادات. ستعيد Comgate المحاولة بعد ملئهما.

يرد الإشعار بـ Unknown transaction أو Order not found أو Reference mismatch: الإشعار يتعلق بدفعة لم ينشئها هذا المتجر لتلك السلة. لا يُغيَّر شيء.

يرد الإشعار بـ Status verification failed أو Status verification rejected أو Busy, retry later: تعذر الوصول إلى واجهة حالة Comgate البرمجية، أو رفضت الطلب، أو كانت السلة تُعالج بطلب آخر في اللحظة نفسها. ويُرد بـ Busy أيضًا عندما يتعذر إنشاء الطلب؛ والسبب موجود في السجل. وتعيد Comgate محاولة الإشعار.

يعرض عنوان الإشعار في المتصفح code=1&message=POST%20required: هذا طبيعي. لا يقبل العنوان إلا الطلبات الواردة من Comgate.

يرى العميل الرسالة We could not verify the Comgate payment: رابط العودة لم يطابق السلة. إذا خُصم المبلغ، فسيظل الإشعار يُنشئ الطلب. تحقق من الدفعة في بوابة Comgate قبل أن يدفع العميل مرة أخرى.

يرى العميل الرسالة The order total is below the minimum amount accepted by Comgate أو A valid billing e-mail address is required for Comgate payments: لا يمكن دفع هذه السلة عبر Comgate كما هي.

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

فشل الاسترداد: اقرأ الرسالة في الكتلة. Comgate rejected the refund: the amount exceeds the refundable amount. تعني أن المبلغ أكبر من المتبقي القابل للاسترداد؛ ولا يمكن استرداد دفعة في حالة غير PAID. Comgate could not be reached. The refund was not made — please try again later. تعني مشكلة في الاتصال.

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

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

Comgate علامة تجارية مسجلة لمالكها. هذه الوحدة غير تابعة لـ Comgate ولا معتمدة من قِبلها.