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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: USD (الإكوادور) أو COP (كولومبيا). بالنسبة إلى العملات الأخرى، يُخفى خيار الدفع في صفحة الدفع.

HTTPS: تشترط Kushki أن تُقدَّم صفحة الدفع عبر HTTPS في الوضع الفعلي.

حساب Kushki: تحتاج إلى Public Merchant ID وPrivate Merchant ID لحساب الاختبار (UAT) وحساب الإنتاج الخاصين بك في Kushki. تجدهما في Kushki Console ضمن Developers > Credentials. بالنسبة إلى الـ Webhook الاختياري تحتاج أيضًا إلى مفتاح توقيع الـ Webhook لكل حساب (راجع قسم الإعدادات).

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل معرّفي Public وPrivate للتاجر في وضع الاختبار، واترك Test mode مفعّلًا. اختياريًا، أعدّ الـ Webhook في Kushki Console والصق مفتاح توقيعه (راجع قسم الإعدادات).

6. فعّل Enable / Disable ونفّذ طلبًا تجريبيًا. عند الجاهزية، أدخل معرّفي التاجر للإنتاج (وتوقيع Webhook الإنتاج) وألغِ تحديد Test mode.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Kushki. فوق الحقول تعرض الصفحة تحذيرًا عندما يكون خيار الدفع مفعّلًا لكن معرّفات التاجر للوضع الحالي غير موجودة (يُخفى خيار الدفع عندها في صفحة الدفع)، وعندما لا تكون عملة المتجر مدعومة، وعندما يُستخدم الوضع الفعلي دون HTTPS، وعندما لا يملك الوضع الحالي توقيعًا للـ Webhook. وأثناء تفعيل وضع الاختبار تعرض Test mode is on: the Kushki test environment is used, no real money is charged. وعند الحفظ مع تفعيل خيار الدفع دون إدخال معرّفات التاجر للوضع الحالي يظهر خطأ يذكّرك بإدخالها. تُزال المسافات حول المعرّفات عند الحفظ.

عام

Enable / Disable: Enable Kushki card payments يفعّل خيار الدفع أو يعطّله. الافتراضي: معطّل.

Title: اسم خيار الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Credit / debit card (Kushki).

Description: النص الذي يظهر فوق نموذج البطاقة في صفحة الدفع. الافتراضي: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

بيانات اعتماد API

انسخ Public Merchant ID وPrivate Merchant ID من Kushki Console (Developers > Credentials). لحساب الاختبار (UAT) وحساب الإنتاج معرّفات مختلفة. يستخدم وضع الاختبار معرّفات الاختبار فقط، ويستخدم الوضع الفعلي معرّفات الإنتاج فقط.

Test mode: Use the Kushki test (UAT) environment يُحوّل معرّفات التاجر ونموذج البطاقة وواجهة API معًا إلى بيئة اختبار Kushki. لا يُخصم أي مبلغ حقيقي، وتظهر شارة TEST MODE في صفحة الدفع. الافتراضي: مفعّل. ألغِ تحديده لاستقبال مدفوعات حقيقية.

Test Public Merchant ID: معرّف التاجر العام لحساب Kushki الاختباري الخاص بك. يُستخدم لتحميل نموذج البطاقة.

Test Private Merchant ID: معرّف التاجر الخاص لحساب Kushki الاختباري الخاص بك. يُستخدم على الخادم لعمليات الخصم والاسترداد.

Live Public Merchant ID: معرّف التاجر العام لحساب Kushki الإنتاجي الخاص بك.

Live Private Merchant ID: معرّف التاجر الخاص لحساب Kushki الإنتاجي الخاص بك. حافظ على سريته.

Webhook (موصى به)

تُؤكَّد المدفوعات فورًا باستجابة واجهة Kushki، لذلك لا يُشترط الـ Webhook. يؤكد الـ Webhook إضافةً المدفوعات التي فُقدت استجابتها (مثلًا عند انتهاء المهلة)، ويبلّغ عن الإلغاءات والاستردادات التي تتم في Kushki Console. في Kushki Console (Webhooks) أضف عنوان URL المعروض في هذا القسم من الإعدادات لمدفوعات البطاقات. يكون بالشكل: https://your-site/wc-api/webhook_kushki_p/. افعل ذلك لحساب الاختبار ولحساب الإنتاج.

تعالج الإضافة إشعارات البطاقات التالية:

Test webhook signature: مفتاح توقيع الـ Webhook لحساب Kushki الاختباري (Console > Webhooks).

Live webhook signature: مفتاح توقيع الـ Webhook لحساب Kushki الإنتاجي.

تُرفض الـ Webhooks التي لا تحمل توقيعًا صالحًا. وبدون مفتاح توقيع تُرفض جميع إشعارات الـ Webhook، لكن المدفوعات تظل تعمل، لأنها تُؤكَّد باستجابة الواجهة.

متقدم

Debug log: Log API calls and webhooks يكتب طلبات Kushki وإشعارات الـ Webhook إلى WooCommerce > Status > Logs، بالمصدر wcp_kushki_payment. تُسجَّل الأخطاء دائمًا. لا تحتوي السجلات أبدًا على معرّفات التاجر أو رموز البطاقات أو عناوين بريد العملاء. الافتراضي: معطّل.

Delete data on uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة الإعدادات والسجلات. تبقى الطلبات ومراجع Kushki الخاصة بها محفوظة. الافتراضي: معطّل.

الدفع

يختار العميل خيار الدفع (افتراضيًا Credit / debit card (Kushki)). يظهر أسفله نموذج بطاقة Kushki مع إجمالي الطلب بعملة الطلب. في صفحة Pay for order يستخدم النموذج إجمالي الطلب. يُدخل العميل البطاقة، ويختار الأقساط إن كان نموذج Kushki يعرضها، ثم يضغط زر الدفع داخل نموذج Kushki.

في صفحة الدفع الكلاسيكية يُخفى زر Place order الخاص بـ WooCommerce طالما Kushki مختار: بعد قبول البطاقة يُرسَل الطلب تلقائيًا. وفي كتلة الدفع يضغط العميل أيضًا زر الدفع داخل نموذج Kushki. إذا حاول العميل تقديم الطلب دون ذلك، تظهر الرسالة Please enter your card details in the Kushki form and press its pay button.

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

إذا رُفضت البطاقة، يرى العميل الرسالة Your payment was declined مع السبب الذي أعادته Kushki، ويمكنه تجربة بطاقة أخرى في النموذج نفسه. وعند وجود مشكلات في الشبكة أو المفاتيح أو الخادم، يرى العميل الرسالة The payment could not be processed right now. Please try again in a moment or choose another payment method. ويُضاف السبب التقني إلى ملاحظات الطلب والسجل. والنقر مرة ثانية أثناء معالجة دفعة يعرض الرسالة A payment for this order is already being processed. Please wait a moment and check your order status.

يعمل خيار الدفع في صفحة الدفع الكلاسيكية، وكتلة الدفع، وصفحة Pay for order. وهو متوافق مع WooCommerce High-Performance Order Storage (HPOS). تُضبط ميزة 3-D Secure وقواعد مكافحة الاحتيال والأقساط المعروضة في Kushki Console.

تقبل الإضافة مدفوعات البطاقات في خطوة واحدة فقط. لا تدعم الاسترداد الجزئي، ولا البطاقات المحفوظة، ولا الاشتراكات أو Add payment method، ولا الدفع النقدي أو التحويل المصرفي (PSE) أو مدفوعات بطاقة الخصم عبر إعادة التوجيه، ولا التفويض والتحصيل المنفصلين.

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

حالات الطلب

Pending payment: أُنشئ الطلب، ولم يُخصم من البطاقة بعد.

Processing: أكدت Kushki الخصم (عبر استجابة الواجهة أو الـ Webhook). تنتقل الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى الحالة Completed، وهي الحالة الافتراضية في WooCommerce. تعرض ملاحظة الطلب الوضع ورقم تذكرة Kushki والمرجع. معرّف المعاملة هو مرجع المعاملة في Kushki (أو رقم التذكرة).

On hold: أعادت Kushki نجاحًا دون رقم تذكرة، أو أبلغت عن مبلغ أو عملة تختلف عن الطلب. توضح ملاحظة الطلب السبب. تحقّق من المعاملة في Kushki Console، ثم أكمل الطلب أو استرد المدفوعات.

Failed: رُفضت البطاقة أو تعذر إتمام الخصم. تعرض ملاحظة الطلب رمز Kushki ورسالتها. يمكن للعميل أن يدفع مرة أخرى.

إذا أبلغ Webhook عن خصم معتمد آخر لطلب مدفوع أو ملغى أو مسترد من قبل، فلا يُعدَّل الطلب. تطلب ملاحظة منك التحقق من الخصم المزدوج واستراده في Kushki Console. ويُتجاهل Webhook من بيئة الاختبار لطلب إنتاجي (أو العكس) مع ملاحظة.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل إجمالي الطلب كاملًا، ثم انقر Refund via Credit / debit card (Kushki) (يعرض الزر Title الخاص بك). تسترد Kushki المدفوعات كاملة، لذلك تُقبل الاستردادات الكاملة فقط. وعند إدخال مبلغ جزئي تعرض الإضافة Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. ولا يمكن استرداد الدفعة أكثر من مرة واحدة.

يُرسل الاسترداد في الوضع الذي تمت فيه عملية الدفع (الاختبار أو الإنتاج)، لذلك يجب أن يكون معرّف Private Merchant ID لذلك الوضع مُعدًّا. وإذا لم تقبل Kushki الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع تذكرة استرداد Kushki.

تصل الإلغاءات والاستردادات التي تتم في Kushki Console عبر الـ Webhook، وتُضاف إلى ملاحظات الطلب. ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce.

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

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

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

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

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

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

لا تظهر Kushki في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على معرّفي التاجر: معرّفات الاختبار في وضع الاختبار، ومعرّفات الإنتاج في الوضع الفعلي. وتحقّق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي USD أو COP. تعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات.

تم الدفع لكن الطلب في حالة Failed أو يبقى في Pending payment: فُقدت استجابة واجهة Kushki، مثلًا بسبب انتهاء المهلة. يؤكد الـ Webhook هذه المدفوعات. في Kushki Console تحقّق من أن عنوان URL للـ Webhook مطابق تمامًا للعنوان المعروض في الإعدادات، ولحساب الوضع الذي تستخدمه، وأن مفتاح التوقيع الخاص بذلك الحساب موجود في الحقل المناسب (Test webhook signature أو Live webhook signature). أما الخصم المعتمد دون المبلغ والعملة المدفوعين فيضع الطلب قيد الانتظار بدلًا من ذلك.

يرد الـ Webhook بـ Webhook signature not configured: لم يُعدّ أي توقيع للـ Webhook. ألصق مفتاح التوقيع في الإعدادات.

يرد الـ Webhook بـ Invalid signature: مفتاح التوقيع يخص حسابًا أو وضعًا آخر، أو تم تعديل الإشعار أثناء النقل.

يرد الـ Webhook بـ Order mismatch: الإشعار لا يخص هذا الطلب (مفتاح طلب أو معاملة غير صحيحة). لا يُعدَّل الطلب.

يرد الـ Webhook بـ Busy, retry later: كان طلب آخر يعالج هذا الطلب في الوقت نفسه. قد تعيد Kushki إرسال الإشعار.

لا يُحمَّل نموذج البطاقة: يرى العميل الرسالة The Kushki card form could not be loaded. Please reload the page or choose another payment method. تحقّق من Public Merchant ID للوضع الحالي.

يرى العميل الرسالة This payment option is not available in this store. Please pay by card.: اختير في نموذج Kushki خيار دفع غير البطاقة. تخصم الإضافة من البطاقات فقط.

يرى العميل خطأً أثناء الدفع: افتح ملاحظات الطلب، أو فعّل Debug log وراجع WooCommerce > Status > Logs بالمصدر wcp_kushki_payment. يعطي معرّف Private Merchant ID الخاطئ أو المفقود رسالة عامة بأن الدفع تعذّرت معالجته.

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

يفشل الاسترداد مع الرسالة No Kushki ticket number found for this order: ليس للطلب خصم مؤكد من Kushki. استرده في Kushki Console.

عملات أخرى: يمكن للمطورين تغيير قائمة العملات بالفلتر kushki_p_supported_currencies، على مسؤوليتهم. يجب أن تكون العملة مفعّلة في حساب Kushki الخاص بك.

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

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

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

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