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

المتطلبات

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

PHP: 8.0 أو أحدث.

العملة: يجب أن تكون عملة الدفع MXN أو USD. وبالنسبة إلى العملات الأخرى تُخفى طريقة الدفع.

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

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل مفاتيحك الخاصة للاختبار والإنتاج، واختر الوضع، وأضف webhook في لوحة Conekta (انظر Configuration).

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

OpenCart 4

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

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

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

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

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

Configuration

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Conekta Gateway > Edit. تظهر الأقسام في القائمة الموجودة على اليسار، ويحفظ الزر Save أسفل القائمة الصفحة كاملة. وتظهر فوق الإعدادات تحذيرات في الحالات التالية: عند تفعيل Conekta بينما المفتاح الخاص للوضع الحالي فارغ (وفي هذه الحالة تُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تكون العملة الافتراضية للمتجر هي MXN أو USD. وأثناء تفعيل وضع الاختبار تعرض الصفحة الرسالة Test mode is on: payments are simulated with the test private key. وإذا لم تكن لديك صلاحية تعديل الإضافة، فستعرض الصفحة الإعدادات لكنها لن تستطيع حفظها.

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

Conekta

Enable / Disable: تؤدي Enable Conekta payments إلى تفعيل طريقة الدفع أو تعطيلها. Default: off.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع، وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. Default: Conekta. حقل إلزامي، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. Default: Pay securely with card, OXXO cash or SPEI transfer. ستُنقل إلى Conekta لإتمام الدفع.

Payment methods: الطرق المعروضة في صفحة الدفع الخاصة بـ Conekta. Default: card, cash and bank transfer. الدفع النقدي وSPEI وBNPL متاحة لطلبات MXN فقط (طلبات USD تقبل البطاقات فقط)، ويجب تفعيلها في حساب Conekta الخاص بك. وإذا لم يُختر شيء، فستُستخدم البطاقة.

Credit / debit card: الدفع بالبطاقة.

Cash (OXXO and other stores): يحصل العميل على مرجع ويدفع نقدًا في أحد المتاجر.

Bank transfer (SPEI): يحصل العميل على مرجع ويدفع عن طريق التحويل المصرفي.

Buy now, pay later (BNPL): الدفع عبر خيار BNPL، إذا كان مفعّلًا في حساب Conekta الخاص بك.

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

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

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

مفاتيح API

انسخ مفاتيحك الخاصة من لوحة Conekta من القسم Developers > API keys (تحتوي الصفحة على رابط إلى اللوحة). مفاتيح الاختبار ومفاتيح الإنتاج مختلفة.

Test mode: يستخدم المفتاح الخاص للاختبار. لا يُخصم أي مبلغ حقيقي، ويرى العميل في خطوة Confirm Order العبارة TEST MODE — No real charges will be made. وتستخدم الاستردادات دائمًا مفتاح الوضع الذي تمت فيه عملية الدفع. Default: on.

Test private key: مفتاح API الخاص لوضع الاختبار في حساب Conekta الخاص بك.

Live private key: مفتاح API الخاص لوضع الإنتاج في حساب Conekta الخاص بك. احتفظ به سرًا.

لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. لا تُدخل قيمة جديدة إلا إذا أردت تغييرها. ولحذف مفتاح محفوظ، ضع علامة على Clear the saved key on save أسفل الحقل، ثم انقر على Save.

يتذكر كل طلب Conekta وضعه: تستخدم الإشعارات والاستردادات المفتاح المطابق. وأبقِ المفتاحين معبّأين ما دامت طلبات الاختبار القديمة مفتوحة.

Webhook

يُخبر الـ webhook متجرك بالمدفوعات، مثل مدفوعات OXXO أو SPEI التي تتم بعد أن يغادر العميل صفحة Conekta. في لوحة Conekta، انتقل إلى Developers > Webhooks وأضف الرابط المعروض في Webhook URL في هذا القسم، لوضعَي الاختبار والإنتاج معًا. وهو بالشكل التالي في OpenCart 3: https://your-store/index.php?route=extension/payment/wcp_conekta_gateway/webhook، وفي OpenCart 4: https://your-store/index.php?route=extension/wcp_conekta_gateway/payment/wcp_conekta_gateway.webhook، ويُبنى من عنوان الواجهة الأمامية لمتجر OpenCart الخاص بك. انسخ الرابط تمامًا كما تعرضه الإعدادات. ويجب أن يكون متاحًا من الإنترنت.

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

order.paid: تم دفع الطلب.

order.pending_payment: الطلب في انتظار الدفع، مثل صدور مرجع OXXO أو SPEI.

order.declined: رُفضت عملية الدفع.

order.expired: انتهت صلاحية الدفع أو مرجع الدفع.

order.canceled: أُلغي طلب Conekta.

order.refunded: تم استرداد الدفعة، مثل حدوث ذلك في لوحة Conekta.

order.charged_back: اعترض العميل على الدفعة (chargeback)؛ وتضيف الإضافة ملاحظة إلى الطلب.

لا يُخبر محتوى الـ webhook الإضافةَ إلا بالطلب من Conekta الذي تغيّر. وكل إشعار يُتحقق منه بقراءة الطلب مرة أخرى من واجهة Conekta API باستخدام المفتاح الخاص لوضعه؛ ولا يُستخدم ترويسة توقيع Digest في الـ webhook. وتُقبل الإشعارات الخاصة بطلبات Conekta التي لم ينشئها هذا المتجر لذلك الطلب، ثم تُتجاهل. وبدون الـ webhook لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع، أو عند محاولة الدفع التالية لنفس السلة.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order من دون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن تبلغ Conekta بالدفع، سواء عبر الـ webhook أو عند عودة العميل؛ ويُقرأ الطلب دائمًا من Conekta. ويعرض كل حقل أدناه حالات الطلبات الخاصة بـ OpenCart لديك.

Order Status After Payment: الحالة التي تُعيَّن بعد دفعة Conekta موثَّقة. Default: Processing.

Awaiting Conekta Payment Status: صدر للعميل مرجع OXXO أو SPEI، ولم تستلم Conekta المبلغ بعد. Default: Pending.

Conekta Payment On Hold Status: تم الدفع، لكن المبلغ أو العملة يختلفان عن الطلب، أو وصلت دفعة TEST في وضع الإنتاج، أو كان الطلب ملغى من قبل، أو أن الدفع مُصرَّح مسبقًا فقط. وتشرح ملاحظة السبب. Default: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment Expired / Canceled Status: طلب في انتظار الدفع انتهت صلاحية مرجع Conekta الخاص به أو أُلغي طلب Conekta الخاص به. Default: Canceled.

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

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف الإعدادات والسجل. تُحفظ دائمًا معاملات Conekta والاستردادات والطلبات، فيمكن تأكيد الطلبات القديمة واسترداد مبالغها بعد إعادة التثبيت. Default: off.

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

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

Import: الصق ملف JSON المُصدَّر سابقًا، ثم انقر على Import لاستعادة الإعدادات. تبقى المفاتيح الخاصة المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (وهي Conekta افتراضيًا). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to Conekta to complete your payment. وينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة طلب Conekta بإجمالي الطلب بعملة الطلب، مع المنتجات والرسوم الإضافية والخصومات والضرائب والشحن، وتنقل العميل إلى صفحة الدفع المستضافة من Conekta. وتُمرَّر إلى Conekta بيانات العميل من اسم وبريد إلكتروني وهاتف وعنوان شحن، ويظهر الدفع في صفحة Conekta باسم Order # ورقم الطلب. وهناك يدفع العميل بإحدى الطرق المسموح بها. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع. وإذا لم يطلب المتجر عنوان دفع (وهو الإعداد الافتراضي في OpenCart 4)، تُؤخذ بيانات الفوترة من عنوان التوصيل ومن اسم العميل.

بعد الدفع يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Conekta ذلك: تقرأ الإضافة الطلب من واجهة Conekta API عند وصول الـ webhook وعند عودة العميل. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وإذا اختار العميل OXXO أو SPEI وحصل على مرجع للدفع، فسيحصل الطلب على Awaiting Conekta Payment Status، وتعرض صفحة النجاح العبارة Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received. وبالنسبة إلى طلب معلّق، تعرض الصفحة العبارة We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again.

إذا تعذر تأكيد الدفع بعد عودة العميل، فستعرض صفحة Payment confirmation النص نفسه وزر Check again. ويضبط الـ webhook حالة الطلب فور وصوله. وفي OpenCart 4 لا يرسل المتصفح جلسة المتجر عندما ترجع Conekta العميل، لذلك تعرض الإضافة أولًا صفحة قصيرة تفتح عنوان العودة نفسه من متجرك مرة أخرى: يحتفظ العميل بالسلة وبتسجيل الدخول.

إذا رُفض الدفع، يبقى الطلب بلا حالة، ويعود العميل إلى صفحة الدفع مع الرسالة The Conekta payment was not completed. Please try again or choose another payment method. وإذا انتهت صلاحية صفحة الدفع أو أُلغيت، تكون الرسالة The Conekta payment has expired or was cancelled. Please try again. وفي OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع. وتُحفظ السلة. وفي كل محاولة جديدة (ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، بينما يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه)، تُقرأ أولًا صفحات الدفع السابقة لـ Conekta الخاصة بالسلة. وتُعاد استخدام صفحة الدفع المفتوحة للطلب نفسه بالمبلغ نفسه؛ وإلا فإن الصفحة السابقة تُلغى في Conekta قبل إنشاء صفحة جديدة، حتى لا يمكن دفع رابط قديم مرتين. وإذا كانت صفحة دفع سابقة قد دُفعت، فإن طلبها يُؤكَّد بدلًا من خصم المبلغ مرة أخرى. ولا تُدفع السلة إلا مرة واحدة: إذا كان طلب آخر من السلة نفسها لديه بالفعل دفعة Conekta أو مرجع OXXO / SPEI صادر، فلن يبدأ دفع جديد، وينتقل العميل إلى صفحة النجاح. وإذا وصلت دفعة ثانية للسلة نفسها، يبقى طلبها بلا حالة، ويتلقى الطلب المدفوع ملاحظة بضرورة استرداد النسخة المكررة من لوحة Conekta.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب في هذه الأثناء (مثلًا لانتهاء صلاحية مرجع OXXO أو SPEI الخاص به، أو لأنك ألغيته)، فإن Confirm Order يعيد العميل إلى صفحة الدفع مع الرسالة The Conekta payment has expired or was cancelled. Please try again.، وتؤدي النقرة التالية على Confirm Order إلى دفع طلب جديد للسلة. وإذا كان للطلب حالة بالفعل وتغيّرت السلة منذ ذلك (منتجات أخرى أو كميات مختلفة)، يُعاد العميل إلى صفحة الدفع، وتحصل السلة المتغيرة على طلب جديد ودفعة خاصة بها.

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

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

تقبل الإضافة المدفوعات في صفحة Conekta فقط. ولا يوجد نموذج بطاقة في صفحة الدفع لديك، ولا توجد بطاقات محفوظة أو اشتراكات أو تفويض مسبق وتحصيل، أو أقساط شهرية (MSI).

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

حالات الطلب

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

Order Status After Payment (default Processing): أكدت Conekta الدفع بالمبلغ والعملة نفسيهما. وتعرض الملاحظة طريقة الدفع (مثل علامة البطاقة وآخر أربعة أرقام، أو OXXO / النقد، أو تحويل SPEI)، وطلب Conekta، والخصم.

Awaiting Conekta Payment Status (default Pending): حصل العميل على مرجع دفع OXXO أو SPEI. ينتقل الطلب إلى Order Status After Payment عندما تبلغ Conekta بالدفع.

Conekta Payment On Hold Status (default Pending): المبلغ أو العملة المستلمان من Conekta لا يطابقان الطلب، أو وصلت دفعة في وضع الاختبار بينما المتجر في وضع الإنتاج (لم يُحصَّل أي مبلغ حقيقي)، أو وصلت الدفعة لطلب سبق إلغاؤه. وتشرح الملاحظة ذلك. افحص الطلب، ثم جهّزه أو استرد الدفعة. أما الطلب المُصرَّح به مسبقًا فقط في Conekta فيوضع هو أيضًا في حالة الانتظار، مع ملاحظة بضرورة تحصيله أو إلغائه من لوحة Conekta.

Payment Expired / Canceled Status (default Canceled): انتهت صلاحية مرجع OXXO أو SPEI لطلب في انتظار الدفع، أو أُلغي طلب Conekta الخاص به.

Refunded Status (default Refunded): استُرد المبلغ بالكامل عبر الإضافة.

لا يُخفَّض الطلب المدفوع أو المسترد إلى حالة أدنى ولا يُعاد فتحه أبدًا. وإذا وصلت دفعة Conekta أخرى لطلب مدفوع بالفعل، فستظهر ملاحظة WARNING تطلب منك استردادها من لوحة Conekta.

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

تبويب VibeFox Conekta Gateway

في Sales > Orders افتح طلبًا مدفوعًا عبر Conekta. وفي أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Conekta Gateway الحقل Conekta order مع التسمية Test mode لمدفوعات الاختبار، وCharge، والحالة Status للدفع، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، وConekta notes الخاصة بالطلب. ويظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox Conekta Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via Conekta. أكّد السؤال Refund this amount through Conekta? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. وتحتاج إلى صلاحية تعديل الإضافة (وتُضبط في System > Users > User Groups). وتقتصر الاستردادات على المبلغ والعملة اللذين خصمتهما Conekta فعليًا، لذلك بعد اختلاف في المبلغ يمكنك استرداد ما دفعه العميل فقط، وليس إجمالي الطلب. ويُرسل الاسترداد إلى طلب Conekta الذي يحتوي الدفعة، ويستخدم مفتاح الوضع الذي تمت فيه عملية الدفع، لذلك يجب أن يكون ذلك المفتاح مُعدًّا. وإذا لم تقبل Conekta الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع المبلغ والوضع وطلب Conekta ومعرّف الاسترداد والسبب. ويضبط الاسترداد الكامل الطلب على Refunded Status من دون إشعار العميل ومن دون إعادة المنتجات إلى المخزون، تمامًا كتغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. وتصبح الاستردادات متاحة بعد أن تبلغ Conekta بالدفع.

لا تُعيد مرتجعات المنتجات في Sales > Returns أي مبلغ عبر Conekta.

تصل الاستردادات التي تتم في لوحة Conekta عبر الـ webhook، وتُضاف كملاحظة مع المبلغ المسترد في Conekta وفي OpenCart. ولا تُسجَّل تلقائيًا. حدّث الطلب يدويًا من دون استخدام Refund via Conekta. ويُضاف أيضًا أي chargeback تبلغ عنه Conekta كملاحظة.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Conekta Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox Conekta Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموَّهًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-conekta والرابط 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. وإذا تعذر الوصول إلى خادم التراخيص، فستستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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

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

لا يظهر Conekta في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن المفتاح الخاص للوضع الحالي مملوء (Test private key في وضع الاختبار، وLive private key في وضع الإنتاج)، وأن عملة الدفع هي MXN أو USD. وتعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو عملة المتجر غير مدعومة. وتحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، ومن أن الطلب يبلغ Total المحدد في الإعدادات.

تمت عملية الدفع لكن الطلب بقي بلا حالة: الـ webhook لا يعمل. في لوحة Conekta تحقق من وجود الـ webhook للوضع الذي تستخدمه (الاختبار أو الإنتاج)، ومن أن رابطه مطابق تمامًا للرابط المعروض في Webhook URL، ومن أن الأحداث مُحدَّدة. وتحقق من تعيين المفتاح الخاص لذلك الوضع، لأن كل إشعار يُتحقق منه به. ويحصل الطلب على حالته أيضًا عند عودة العميل إلى المتجر، أو عند محاولته دفع السلة نفسها مرة أخرى.

يعرض الـ webhook الرد Temporarily unavailable: تعذر الوصول إلى واجهة Conekta API، أو المفتاح الخاص لوضع الطلب مفقود، أو كان الطلب قيد المعالجة بطلب آخر، أو تعذر تعيين حالة الطلب. وتعيد Conekta محاولة الـ webhook. انظر حقل Log لمعرفة السبب.

يعرض الـ webhook الرد Verification failed أو Invalid payload أو Invalid order id: لم تؤكد واجهة Conekta API الطلب، أو لم يكن الإشعار حدث طلب صالحًا من Conekta.

يعرض الـ webhook الرد Ignored: ينتمي الإشعار إلى طلب Conekta لم ينشئه هذا المتجر لذلك الطلب (مثل متجر آخر أو رابط دفع على الحساب نفسه)، أو إلى كائن غير الطلب.

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

يرى العميل الرسالة We could not check the status of your previous payment attempt: تعذّرت قراءة صفحة الدفع السابقة لـ Conekta الخاصة بالسلة، لذلك لم تُنشأ صفحة جديدة تجنبًا للدفع المزدوج. حاول مرة أخرى بعد قليل.

يرى العميل الرسالة Payment gateway is not configured: المفتاح الخاص للوضع الحالي مفقود.

يرى العميل الرسالة This payment method is not available.: لم تعد جلسة الدفع مطابقة للطلب، أو أُوقفت طريقة الدفع في الأثناء. يعيد العميل تحميل صفحة الدفع.

يرى العميل الرسالة Payment verification failed: رابط العودة من Conekta لم يطابق الطلب. تحقق من الطلب في لوحة Conekta؛ فالـ webhook يؤكد الدفعات الحقيقية في كل الأحوال.

الطلب في حالة الانتظار أو التعليق: اقرأ Conekta notes في تبويب الطلب. لم يدفع العميل مرجع OXXO أو SPEI بعد، أو لم يطابق المبلغ أو العملة، أو وصلت دفعة في وضع الاختبار بينما المتجر في وضع الإنتاج، أو أن الدفعة مُصرَّحة مسبقًا فقط.

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

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

للمطورين: تتيح أحداث OpenCart wc_ckt_supported_currencies وwc_ckt_order_request وwc_ckt_allowed_payment_methods وwc_ckt_refund_reason لإضافات أخرى تغيير العملات المدعومة، وطلب Conekta، وطرق الدفع، وسبب الاسترداد.

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

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

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

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