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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل Enable / Disable واحفظ. اختبر دفعة في وضع الاختبار، ثم ألغِ تحديد Test mode.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Conekta. وفوق الحقول تنبهك الصفحة عندما يكون Conekta مفعّلًا لكن مفتاح Private Key الخاص بالوضع الحالي فارغ (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تكون عملة المتجر MXN أو USD. وأثناء تفعيل وضع الاختبار تعرض الصفحة Test mode is on: payments are simulated with the test private key. وعند حفظ بوابة مفعّلة دون مفتاح الوضع الحالي تظهر رسالة خطأ تطلب منك إدخاله.

عام

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. القيمة الافتراضية: البطاقة والنقد والتحويل المصرفي. وتتوفر طرق النقد وSPEI وBNPL للطلبات بعملة MXN فقط (أما الطلبات بعملة USD فلا تقبل إلا البطاقات)، ويجب تفعيلها في حساب Conekta. وإذا لم يُحدَّد أي شيء، تُستخدم البطاقة.

مفاتيح API

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

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

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

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

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

Webhook

يُبلغ webhook متجرك بالمدفوعات التي تمت بعد مغادرة العميل لصفحة Conekta، مثل مدفوعات OXXO أو SPEI. في لوحة Conekta انتقل إلى Developers > Webhooks وأضف الرابط المعروض في هذا القسم لوضعي الاختبار والإنتاج. يبدو الرابط هكذا: https://your-site/wc-api/webhook_wc_conekta/.

اختر هذه الأحداث:

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

متقدم

Debug log: Log API calls and notifications يكتب التفاصيل في WooCommerce > Status > Logs، والمصدر wcp_conekta_gateway. تُسجَّل الأخطاء دائمًا. ولا تتضمن السجلات مفاتيح API ولا بيانات اتصال العميل أبدًا. القيمة الافتراضية: معطّل.

Delete data on uninstall: Remove the settings, Conekta order references and logs when the plugin is deleted. القيمة الافتراضية: معطّل.

الدفع

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

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

إذا رُفض الدفع، يُعلَّم الطلب بحالة «فشل»، ويعود العميل إلى صفحة Pay for order مع الرسالة The Conekta payment was not completed. Please try again or choose another payment method. وإذا انتهت صلاحية صفحة الدفع أو أُلغيت، يرى العميل الرسالة The Conekta payment has expired or was cancelled. Please place the order again. وعندما يدفع العميل الطلب مرة أخرى، تُعاد استخدام صفحة دفع Conekta المفتوحة بالمبلغ نفسه إن وُجدت؛ وإلا فإن الصفحة السابقة تُلغى في Conekta قبل إنشاء صفحة جديدة، حتى لا يُدفع الرابط القديم مرتين. وإذا كانت الصفحة السابقة قد دُفعت بالفعل، يُسجَّل الدفع بدلًا من خصم المبلغ مرة أخرى.

إذا تعذّر على Conekta بدء الدفع، يرى العميل رسالة قصيرة، مثل The payment could not be started. Please try again in a moment or choose another payment method. ويُكتب السبب التقني في السجل.

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Conekta ولم يدفع بعد. تُظهر ملاحظة الطلب طلب Conekta والوضع.

Processing: أكدت Conekta الدفع بالمبلغ والعملة نفسيهما (الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط تنتقل إلى «مكتمل»، وهي القيمة الافتراضية في WooCommerce). وتُظهر ملاحظة الطلب طريقة الدفع (مثل علامة البطاقة وآخر أربعة أرقام، أو OXXO / النقد أو التحويل المصرفي SPEI)، وطلب Conekta، والخصم. ومعرّف المعاملة للطلب هو معرّف الخصم في Conekta (charge ID).

On hold, waiting for OXXO or SPEI: حصل العميل على مرجع دفع. ينتقل الطلب إلى «قيد التنفيذ» عندما يُبلغ Conekta بالدفع.

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

Failed: رُفض الدفع. تُظهر الملاحظة السبب. ويمكن للعميل الدفع مرة أخرى.

Cancelled: انتهت صلاحية صفحة Conekta الحالية أو أُلغيت.

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

الاستردادات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الطلب في حالة On hold: اقرأ ملاحظات الطلب. لم يدفع العميل بعد مرجع OXXO أو SPEI، أو لم يتطابق المبلغ أو العملة، أو وصلت دفعة من وضع الاختبار بينما كان المتجر في الوضع المباشر.

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

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

للمطوّرين: يذكر readme الفلتر wc_ckt_supported_currencies الخاص بقائمة العملات.

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

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

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