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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

حساب Comgate: تحتاج إلى Merchant ID وSecret (كلمة المرور لتواصل الخلفية) لربط متجرك في بوابة العملاء لدى Comgate، وإلى عنوان الإشعار مضبوطًا فيها (راجع قسم الإعدادات). تستخدم Comgate Merchant ID وSecret نفسيهما للدفعات التجريبية والحقيقية.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل Merchant ID وSecret من بوابة العملاء في Comgate، واضبط عنوان الإشعار فيها (راجع قسم الإعدادات).

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

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Comgate. تحذّرك الصفحة فوق الحقول عندما تكون Comgate مفعّلة لكن Merchant ID أو Secret ناقص (فتبقى طريقة الدفع مخفية عند الدفع حتى يُملأ الحقلان)، وعندما لا تكون عملة المتجر مدعومة. وما دام وضع الاختبار مفعّلًا تعرض الصفحة Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.

عام

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

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

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: 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 (إشعار الخلفية) على العنوان الظاهر في هذا القسم. ويبدو بالشكل https://your-site/wc-api/comgate_payment_callback/. تستدعيه Comgate بعد كل دفعة، ثم تعيد الإضافة التحقق من الدفعة عبر Comgate status API قبل أن تغيّر الطلب. وتُرسل عناوين العودة للعميل مع كل دفعة. وإذا طلبت البوابة عناوين عودة (مدفوع، ملغى، معلّق) أيضًا، فاستخدم العنوان الثاني الظاهر في هذا القسم، ويبدو بالشكل https://your-site/wc-api/comgate_payment_return/?id=${id}&refId=${refId}.

Merchant ID: معرّف المتجر الإلكتروني في Comgate (merchant).

Secret: كلمة المرور لتواصل الخلفية (secret) الخاصة بربط المتجر هذا.

Test Mode: Create test payments (no money is charged). تستخدم Comgate Merchant ID وSecret نفسيهما للدفعات التجريبية والحقيقية، وتُعلَّم الدفعات التجريبية بـ test=true. وتُرسل الاستردادات دائمًا في وضع الدفعة الأصلية. الافتراضي: مفعّل.

صفحة الدفع في Comgate

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

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

الطلبات

Order Status After Payment: الحالة التي تُضبط عندما تؤكد Comgate الدفع. تُضبط الحالة مرة واحدة فورًا، دون تغيير ثانٍ للحالة.

متقدم

Debug Log: Log API requests and notifications يكتب إلى WooCommerce > Status > Logs، والمصدر wcp_comgate_gateway. لا يُسجَّل الـ Secret والبيانات الشخصية أبدًا. تُسجَّل الأخطاء دائمًا. الافتراضي: إيقاف.

Delete Data on Uninstall: Remove the gateway settings and log files when the plugin is deleted. الطلبات ومعرّفات معاملات Comgate الخاصة بها تبقى دائمًا. الافتراضي: إيقاف.

صفحة الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Comgate: تقرأ الإضافة الدفعة من Comgate status API، سواء عند وصول إشعار الخلفية أو عند عودة العميل. وإذا لم تُؤكَّد الدفعة بعد، كتحويل بنكي في الطريق، تعرض صفحة استلام الطلب Comgate has not confirmed your payment yet. The order will be updated automatically as soon as the payment is confirmed — please do not pay again. وإذا وُضع الطلب في الانتظار، تعرض الصفحة Your payment is being reviewed. We will contact you if anything else is needed.

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

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

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Comgate ولم يدفع بعد، أو تُبلغ Comgate بأن الدفعة معلقة. تعرض ملاحظة الطلب الدفعة التي أُنشئت في Comgate.

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

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

Cancelled: أُلغيت الدفعة الحالية لدى Comgate أو انتهت صلاحيتها. وإذا أكدت Comgate الدفعة بعد أن ألغى WooCommerce الطلب غير المدفوع (مثل تحويل بنكي بطيء)، يُعاد فتح الطلب كمدفوع مع ملاحظة للتحقق من المخزون قبل الشحن.

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

الاستردادات

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

لا تُرسَل الاستردادات التي تُجرى في بوابة Comgate إلى المتجر. وإذا لزم الأمر، أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via الخاص بالبوابة.

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

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

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

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

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

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

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

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

يرد الإشعار بالرسالة Invalid merchant or secret: Merchant ID أو Secret في الإعدادات لا يطابق ربط المتجر في بوابة Comgate.

يرد الإشعار بالرسالة Gateway not configured: Merchant ID أو Secret فارغ في الإعدادات. تُعيد Comgate المحاولة بعد ملء الحقلين.

يرد الإشعار بالرسالة Order not found أو Unknown transaction أو Reference mismatch: الإشعار يخص دفعة لم تنشئها هذه المتجر لذلك الطلب. لا يتغير الطلب.

يرد الإشعار بالرسالة Status verification failed أو Status verification rejected أو Busy, retry later: تعذّر الوصول إلى Comgate status API، أو رفضت الطلب، أو كان الطلب يُعالَج بطلب آخر في الوقت نفسه. تُعيد 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 بوضعه الحالي.

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. اختلف المبلغ أو العملة المدفوعان، أو وصلت دفعة تجريبية في وضع الإنتاج، أو أن الدفعة مُفوَّضة فقط. تحقق من الدفعة في بوابة 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. تعني مشكلة في الاتصال.

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

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

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

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