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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

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

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

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

التثبيت

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

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

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

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

5. فعّل Enable / Disable وانقر Save ثم أجرِ طلب اختبار. عند الجاهزية أدخل Merchant ID الفعلية (وتوقيع الـ Webhook الفعلي) وأوقف Test mode.

عند التثبيت تنشئ الوحدة حالة الطلب Kushki payment on hold. يعيّن PrestaShop وحدة الدفع الجديدة إلى عملات متجرك وبلدانه ومجموعات عملائه. في Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة USD أو COP ولكل من الإكوادور أو كولومبيا.

الإعدادات

توجد كل الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox Kushki Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. فوق الحقول تنبّهك الصفحة عندما تكون طريقة الدفع مفعّلة ولكن Merchant ID للوضع الحالي مفقود (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تكون العملة الافتراضية لمتجرك USD أو COP، وعندما يُستخدم الوضع الفعلي دون HTTPS، وعندما لا يملك الوضع الحالي توقيعًا للـ Webhook. وطالما أن وضع الاختبار مفعّل تعرض الرسالة وضع الاختبار مفعّل: يُستخدم بيئة الاختبار في Kushki ولا يُخصم أي مبلغ حقيقي. إذا حفظت وطريقة الدفع مفعّلة دون Merchant ID للوضع الحالي، تُحفظ الإعدادات وتذكّرك رسالة بإدخالها. تُزال المسافات حول المعرّفات عند الحفظ.

Kushki

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

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

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

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

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

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

لا تُعرض معرّفات Private Merchant ID المحفوظة ولا توقيعات الـ Webhook مرة أخرى. يبقى الحقل فارغًا ويعرض محفوظ: اتركه فارغًا للاحتفاظ به. اكتب قيمة جديدة فقط إذا أردت تغييرها.

Webhook (موصى به)

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

تعالج الوحدة إشعارات البطاقات التالية:

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

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

Clear saved secrets: ضع علامة على Private Merchant ID أو توقيع الـ Webhook ثم انقر Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

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

متقدم

Debug log: يكتب طلبات Kushki والـ Webhooks إلى logs/kushki_p_debug.log.php في مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائمًا. لا يتضمن السجل أبدًا Merchant ID أو رموز البطاقات أو عناوين بريد العملاء. الافتراضي: إيقاف.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات والسجلات. تبقى سجلات مدفوعات Kushki (الخصومات والاستردادات) وحالة الطلب Kushki payment on hold دائمًا، حتى يمكن استرداد الطلبات القديمة بعد إعادة التثبيت. الافتراضي: إيقاف.

صفحة الدفع

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

يبقى زر Place order في PrestaShop ظاهرًا لأنه يحمل شروط الخدمة. إذا كانت الشروط مقبولة من قبل، تُرسل عملية الدفع تلقائيًا بعد زر الدفع في Kushki. وإلا يرى العميل الرسالة وافقت Kushki على بطاقتك. اقبل شروط الخدمة واضغط "Place order" للدفع. إذا ضغط العميل Place order دون استخدام نموذج Kushki تظهر الرسالة أدخل بيانات بطاقتك في نموذج Kushki واضغط زر الدفع الخاص به.

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

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

إذا فُقدت استجابة Kushki (مثلًا عند انتهاء المهلة) يرى العميل الرسالة العامة، لكن محاولة الخصم تُحفظ. عندما يبلّغ الـ Webhook الموقّع عن الخصم المعتمد يُنشأ الطلب. لا تُخصم السلة التي لها طلب بالفعل، ولا الخصم المعتمد الذي لم يُنشأ طلبه بعد، مرة أخرى أبدًا: يرى العميل تأكيد ذلك الطلب. إذا دفع العميل مرة أخرى قبل وصول أي Webhook فهذا خصم جديد؛ وعندها تضيف الموافقة المتأخرة على الخصم الأول ملاحظة فقط عن احتمال وجود خصم مزدوج.

يعمل الـ Webhook حتى والمتجر في وضع الصيانة، ولا يتأثر بقيود البلدان في متجرك. تُضبط ميزة 3-D Secure وقواعد مكافحة الاحتيال والأقساط المعروضة في Kushki Console.

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

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

حالات الطلب

No order yet: لم يدفع العميل، أو رُفضت البطاقة، أو فُقدت استجابة Kushki ولم يصل الـ Webhook بعد. لا يوجد إلا السلة.

Payment accepted: أكدت Kushki الخصم (باستجابة API أو عبر الـ Webhook). يُسجَّل الدفع بمرجع المعاملة في Kushki (أو رقم التذكرة) بوصفه معرّف المعاملة. تعرض الملاحظة الوضع ورقم تذكرة Kushki والمرجع.

Kushki payment on hold: أعادت Kushki نجاحًا دون رقم تذكرة، أو أبلغت عن مبلغ أو عملة يختلفان عن السلة، أو جرى تعديل السلة أثناء الدفع. تشرح الملاحظة ذلك. تحقّق من المعاملة في Kushki Console ثم نفّذ الطلب أو استرد الدفعة. تنقل الموافقة الموقّعة اللاحقة برقم التذكرة والمبلغ المطابق الطلب إلى Payment accepted.

Payment error: أبلغ الـ Webhook أن خصم طلب معلّق قد رُفض.

Refunded: استُرد الدفع عبر الوحدة.

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

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

تعرض صفحة الطلب كتلة Kushki payment تتضمن رقم التذكرة ومرجع المعاملة والبيئة (مع شارة Test لمدفوعات الاختبار) وحالة الخصم والمبلغ المخصوم وإجمالي الطلب ونموذج الاسترداد وسجل الاستردادات وKushki notes الخاصة بالطلب.

الاستردادات

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

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Kushki. تصل الإلغاءات والاستردادات التي تتم في Kushki Console عبر الـ Webhook وتُضاف إلى الملاحظات. ولا تتغير حالة الطلب تلقائيًا.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Kushki Payment هي أول كتلة في Modules > Module Manager > VibeFox Kushki Payment > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها السطر Product: presta-payment-kushki والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure لهذه الوحدة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

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

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

بدون مفتاح نشط، لا يُعرض Kushki للعملاء في إتمام الطلب. إذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. واجهة متجر PrestaShop لا تعرف أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها في إتمام الطلب. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الموجودة لا تتأثر: تبقى المدفوعات التي بدأت مؤكدة، وتعمل الاستردادات.

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

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

لا يظهر Kushki في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على Merchant ID كليهما: معرّفات الاختبار في وضع الاختبار، ومعرّفات الإنتاج في الوضع الفعلي. تحقّق من أن عملة السلة USD أو COP. في Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل. تعرض صفحة الإعدادات تحذيرًا عند غياب المعرّفات.

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

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

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

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

يرد الـ Webhook بالرسالة Busy, retry later: كان الطلب قيد المعالجة من طلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطلة). يمكن أن ترسل Kushki الإشعار مرة أخرى. تُكتب الأخطاء دائمًا في السجل.

يعرض عنوان الـ Webhook في المتصفح POST فقط: هذا طبيعي. يقبل العنوان إشعارات Kushki فقط.

لا يُحمَّل نموذج البطاقة: يرى العميل تعذّر تحميل نموذج بطاقة Kushki. يُرجى إعادة تحميل الصفحة أو اختيار طريقة دفع أخرى. تحقّق من Public Merchant ID للوضع الحالي.

يرى العميل الرسالة "هذه الطريقة غير متاحة في هذا المتجر. يُرجى الدفع بالبطاقة.": اختير في نموذج Kushki خيار دفع غير البطاقات. تحصّل الوحدة من البطاقات فقط.

يرى العميل خطأً عند الدفع: فعّل Debug log وراجع الحقل Log في صفحة الوحدة. يؤدي Private Merchant ID خاطئ أو مفقود إلى الرسالة العامة بأنه تعذّرت معالجة الدفع.

يرى العميل الرسالة "تم استلام دفعتك، لكن تعذّر إكمال الطلب تلقائيًا": وافقت Kushki على الخصم لكن PrestaShop لم يستطع إنشاء الطلب. يُظهر السجل السبب. تُنشئ محاولة الدفع التالية لنفس السلة الطلب دون خصم جديد.

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

لا يُعرض الاسترداد وتظهر الرسالة "لم يُعثر على رقم تذكرة Kushki لهذا الطلب": ليس لهذا الطلب خصم مؤكد من Kushki. استرده في Kushki Console.

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

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

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