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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Conekta Gateway > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذّرك الصفحة عندما تكون Conekta مفعّلة لكن المفتاح الخاص للوضع الحالي فارغ (وفي هذه الحالة تُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تكون عملة المتجر الافتراضية MXN أو USD. وعند تفعيل وضع الاختبار تعرض الصفحة: وضع الاختبار مفعّل: تُحاكى المدفوعات باستخدام المفتاح الخاص للاختبار. وعند حفظ بوابة مفعّلة دون مفتاح الوضع الحالي، يطلب منك تحذير إدخاله.

Conekta

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

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

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: الطرق المعروضة في صفحة دفع Conekta. الافتراضي: 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.

مفاتيح API

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

Test mode: يستخدم المفتاح الخاص للاختبار. لا يُخصم أي مبلغ حقيقي، وتظهر شارة TEST MODE مع الرسالة لن يتم تنفيذ أي خصم حقيقي. أسفل طريقة الدفع في صفحة الدفع. وتستخدم الاستردادات دائمًا مفتاح الوضع الذي تم فيه الدفع. الافتراضي: مفعّل.

Test private key: المفتاح الخاص لواجهة API في وضع الاختبار من حسابك لدى Conekta.

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

لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للاحتفاظ به. أدخل قيمة جديدة فقط إذا أردت تغييره.

Clear saved keys: ضع علامة على مفتاح ثم انقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة كما هي.

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

Webhook

يُبلغ الـ webhook متجرك بالمدفوعات، مثل مدفوعات OXXO أو SPEI التي تُجرى بعد أن يغادر العميل صفحة Conekta. انتقل في لوحة Conekta إلى Developers > Webhooks وأضف الرابط المعروض في حقل Webhook ضمن قسم API keys، للوضعين: الاختبار والإنتاج. وعند تفعيل الروابط المختصرة يكون بالشكل: https://your-shop/module/wcp_conekta_gateway/webhook، وقد يتبعه رمز لغة مثل /en/. انسخ الرابط تمامًا كما تعرضه الإعدادات.

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

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

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

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

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

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

order.refunded: تم استرداد الدفعة، مثلًا من لوحة Conekta.

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

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

متقدم

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

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

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

الدفع

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

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

إذا لم يمكن تأكيد الدفع بعد عند عودة العميل، تعرض صفحة تأكيد الدفع الرسالة نحن نؤكد دفعتك عبر Conekta. سيُحدَّث الطلب تلقائيًا — يُرجى عدم الدفع مرة أخرى. مع زر Check again. وينشئ الـ webhook الطلب فور وصوله.

إذا رُفضت الدفعة، لا يُنشأ أي طلب، ويعود العميل إلى صفحة الدفع مع الرسالة لم تكتمل دفعة Conekta. يُرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وإذا انتهت صلاحية صفحة الدفع أو أُلغيت، تكون الرسالة انتهت صلاحية دفعة Conekta أو أُلغيت. يُرجى المحاولة مرة أخرى. وتُحفظ السلة. وعندما يدفع العميل مرة أخرى، تُعاد استخدام صفحة Conekta مفتوحة بالمبلغ نفسه إن وُجدت؛ وإلا تُلغى الصفحة السابقة في Conekta قبل إنشاء صفحة جديدة، حتى لا يُدفع الرابط القديم مرتين. وإذا كانت الصفحة السابقة قد دُفعت بالفعل، يُنشأ الطلب بدلًا من إعادة الخصم.

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

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

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Conekta ولم يدفع، أو رُفضت الدفعة، أو لم تؤكد Conekta الدفع بعد. لا توجد إلا السلة.

Payment accepted: أكدت Conekta الدفع بالمبلغ نفسه والعملة نفسها. يُسجَّل الدفع بمعرّف الخصم لدى Conekta بوصفه معرّف المعاملة، ويعرض ملاحظة تبيّن طريقة الدفع (مثل علامة البطاقة وآخر أربعة أرقام، أو OXXO / النقد، أو تحويل SPEI)، وطلب Conekta، والخصم.

Awaiting Conekta payment: حصل العميل على مرجع دفع OXXO أو SPEI. ويتحول الطلب إلى Payment accepted عندما تُبلغ Conekta بالدفع.

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

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

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

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

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

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

الاسترداد

في كتلة Conekta payment أدخل المبلغ (يُملأ تلقائيًا المبلغ الذي لم يُسترد بعد)، واكتب السبب إن أردت، ثم انقر على Refund via Conekta. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Conekta؟ لا يمكن التراجع عن هذا الإجراء. والاسترداد الكامل والجزئي مدعومان. وتحتاج إلى صلاحية تعديل الطلبات. والاسترداد مقيّد بالمبلغ والعملة اللذين حصّلتهما Conekta فعلًا، لذلك بعد وجود اختلاف في المبلغ يمكنك الاسترداد حتى قيمة ما دفعه العميل، لا إجمالي الطلب. ويُرسل الاسترداد إلى طلب Conekta الذي يحتوي الدفعة، ويستخدم مفتاح الوضع الذي تم فيه الدفع، لذلك يجب أن يكون هذا المفتاح مضبوطًا. وإذا لم تقبل Conekta الاسترداد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع المبلغ والوضع وطلب Conekta ومعرّف الاسترداد والسبب. والاسترداد الكامل يضع الطلب في حالة Refunded. أما الاسترداد الجزئي فلا يغيّر الحالة. والاسترداد متاح بعد أن تُبلغ Conekta بالدفع.

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

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Conekta Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox Conekta Gateway > Configure، فوق الإعدادات. الصق المفتاح في حقل License key ثم انقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموَّهًا، والحالة (مثل التاريخ الذي تظل فيه الرخصة فعّالة ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: presta-payment-conekta ورابط «إدارة التراخيص والنطاقات في حسابك»، الذي يفتح حسابك في vibefox.net. ولا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure للوحدة. وتتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد متعدد المتاجر. ولا تُحرَّر خانة النطاق بإزالة المفتاح من المتجر. حرّر الخانة من حسابك في vibefox.net.

بدون مفتاح نشط لا تظهر Conekta للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل الرسالة طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها في صفحة الدفع. ويظهر تذكير في Modules > Module Manager على تبويب Alerts. ولا تتأثر الطلبات الحالية: الدفعات التي بدأت بالفعل ما زالت تُؤكَّد، وتعمل الاستردادات.

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

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

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

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

يرد الـ 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 فقط.

يرى العميل الرسالة تعذّر التحقق من حالة محاولة الدفع السابقة: تعذّرت قراءة صفحة Conekta السابقة للسلة، لذلك لا تُنشأ صفحة جديدة تفاديًا للدفع المزدوج. حاول مرة أخرى بعد قليل.

يرى العميل الرسالة بوابة الدفع غير مُعدّة: المفتاح الخاص للوضع الحالي مفقود.

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

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

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

للمطورين، يسرد ملف README الخطافات actionWcpConektaSupportedCurrencies وactionWcpConektaOrderRequest وactionWcpConektaAllowedPaymentMethods وactionWcpConektaRefundReason.

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

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

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