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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

العملة: USD (الإكوادور) أو COP (كولومبيا). بالنسبة للطلبات بعملات أخرى، لا تظهر طريقة الدفع عند إتمام الشراء.

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

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Kushki Payment > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ الزر Save الموجود أسفل القائمة الصفحة بأكملها. وفوق الإعدادات، تُظهر الصفحة تحذيرًا عندما تكون طريقة الدفع مفعّلة لكن معرّفات التاجر للوضع الحالي مفقودة (وعندها تُخفى طريقة الدفع عند إتمام الشراء)، وعندما لا تكون العملة الافتراضية لمتجرك USD أو COP، وعندما يُستخدم الوضع الحي من دون HTTPS (في OpenCart 4، عندما يبدأ عنوان الواجهة الأمامية بـ http://)، وعندما لا يملك الوضع الحالي مفتاح توقيع Webhook. وبينما يكون وضع الاختبار مفعّلًا، تعرض الصفحة الرسالة Test mode is on: the Kushki test environment is used, no real money is charged. ومن دون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب ألّا يكون Title فارغًا وألّا يتجاوز 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا (يُسمح بالأعداد السالبة)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0، ويجب أن توجد كل حالة طلب. إذا كان أي حقل خاطئًا، فلن يُحفظ شيء وستشير الصفحة إلى الحقل. تُزال المسافات حول المعرّفات عند الحفظ.

Kushki

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

Title: اسم طريقة الدفع الذي يراه العملاء عند إتمام الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit / debit card (Kushki). حقل إلزامي، حتى 128 حرفًا.

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

Sort Order: موضع Kushki بين طرق الدفع عند إتمام الشراء. اتركه فارغًا أو أدخل عددًا صحيحًا.

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

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

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

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

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

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

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

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

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

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

Webhook (موصى به)

تُؤكَّد المدفوعات فورًا من استجابة واجهة Kushki API، لذلك لا يُعد Webhook مطلوبًا. إنه يؤكد بالإضافة إلى ذلك مدفوعة فُقدت استجابتها (مثلًا بسبب انتهاء المهلة)، ويبلّغ عن عمليات الإلغاء والاسترداد والـ chargebacks التي تتم في Kushki Console. في Kushki Console (Webhooks)، أضف الرابط المعروض في Webhook URL ضمن هذا القسم. في OpenCart 3 يبدو بالشكل التالي: https://your-store/index.php?route=extension/payment/wcp_kushki_payment/webhook، وفي OpenCart 4 بالشكل التالي: https://your-store/index.php?route=extension/wcp_kushki_payment/payment/wcp_kushki_payment.webhook. ويُبنى من عنوان متجرك في تثبيت OpenCart الخاص بك. انسخ الرابط تمامًا كما تعرضه الإعدادات. افعل ذلك لحساب الاختبار ولحساب الإنتاج.

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

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

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

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

الطلبات

ينشئ OpenCart الطلب في الخطوة Confirm Order من دون حالة (طلب مفقود). يحصل الطلب على حالة فقط بعد أن توافق Kushki على خصم البطاقة. يسرد كل حقل أدناه حالات الطلبات في OpenCart الخاص بك.

Order Status After Payment: وافقت Kushki على الخصم برقم تذكرة، للمبلغ والعملة الخاصين بالطلب. الافتراضي: قيد التنفيذ.

On Hold (Review) Status: وافقت Kushki على الخصم من دون رقم تذكرة، أو أبلغت عن مبلغ أو عملة مختلفة. توضح ملاحظة السبب؛ تحقق من الدفعة في Kushki Console قبل التنفيذ. الافتراضي: بانتظار الدفع، لأن OpenCart لا يملك حالة "في الانتظار". يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Failed Status: طلب في حالة المراجعة أبلغت Kushki لاحقًا بأن خصمه قد رُفض (Webhook). الافتراضي: فشل.

Canceled Status: لا تُعاد فتح الطلبات في هذه الحالة (أو في حالة الاسترداد) أبدًا بواسطة Webhook متأخر. الافتراضي: ملغى.

Refunded Status: يُعيَّن بعد استرداد الدفعة من علامة تبويب الطلب. الافتراضي: مسترد.

متقدم

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

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

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

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

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

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

إتمام الشراء

في الخطوة Payment Method، يختار العميل طريقة الدفع (افتراضيًا Credit / debit card (Kushki)). ينشئ OpenCart الطلب في الخطوة Confirm Order، ولا يزال من دون حالة. هناك يرى العميل وصفك ونموذج بطاقة Kushki مع إجمالي الطلب بعملة الطلب. يُدخل العميل بطاقته، ويختار أقساط الدفع إذا كان نموذج Kushki يعرضها، ويضغط زر الدفع داخل نموذج Kushki. ثم تُرسل الدفعة تلقائيًا، كما تنص الملاحظة أسفل النموذج: Enter your card in the secure Kushki form above and press its pay button — the payment is sent automatically. وإذا نقر العميل بدلًا من ذلك على زر Confirm Order في OpenCart، تظهر الرسالة Please enter your card details in the Kushki form and press its pay button.

في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، داخل النافذة Payment method options. يظهر نموذج بطاقة Kushki بعد ذلك في كتلة تأكيد الطلب أسفل صفحة الدفع، فوق زر Confirm Order، ويُعاد بناؤه بإجمالي الطلب الحالي كلما أعاد OpenCart تحميل تلك الكتلة.

ثم يخصم متجرك البطاقة على الخادم. لا يُعلَّم الطلب بأنه مدفوع إلا بعد أن تؤكده Kushki برقم تذكرة. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويُفرغ السلة، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your card payment has been received. تُقارَن المبلغ والعملة اللذان تبلغ عنهما Kushki بالطلب. يعرض الطلب الموجود في حالة المراجعة الرسالة Your payment is being reviewed. We will update your order as soon as the review is complete.

إذا رُفضت البطاقة، يبقى الطلب من دون حالة، ويظل العميل في الخطوة Confirm Order مع الرسالة 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.

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

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تظهر صفحة النجاح. وإذا أُغلق هذا الطلب في الأثناء دون دفع (مثلاً إذا رُفض لاحقاً خصم في حالة المراجعة، أو ألغيته)، أو كان قد دُفع لسلة سابقة وغيّر العميل السلة منذ ذلك، يُعاد العميل عند الدفع إلى صفحة إتمام الشراء، ويُنشئ Confirm Order التالي طلباً جديداً. وتظهر فوق صفحة الدفع الرسالة Your previous order is closed (declined, cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order. إذا أُغلق الطلب، أو Your previous order is already paid for other cart contents. Please confirm the order again: the current cart will be paid with a new order. إذا كان قد دُفع لسلة سابقة. ويُحسب تغيير السلة، بما فيه الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

يعمل Webhook أيضًا عندما يكون المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة في OpenCart 4 startup action يسمح بمرور الإشعار وعودة العميل. تُضبط خدمة 3-D Secure وقواعد مكافحة الاحتيال والأقساط المعروضة في Kushki Console.

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

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

حالات الطلب

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

Order Status After Payment (الافتراضي قيد التنفيذ): أكدت Kushki الخصم (عبر استجابة API أو عبر Webhook). تعرض ملاحظة الوضع والمبلغ ورقم تذكرة Kushki والمرجع.

On Hold (Review) Status (الافتراضي بانتظار الدفع): أعادت Kushki نجاحًا من دون رقم تذكرة، أو أبلغت عن مبلغ أو عملة مختلفين عن الطلب. تشرح الملاحظة ذلك. تحقق من المعاملة في Kushki Console ثم نفّذ الطلب أو استرد الدفعة. وتنقل الموافقة الموقّعة اللاحقة برقم تذكرة ومبلغ مطابق الطلب إلى Order Status After Payment.

Failed Status (الافتراضي فشل): أبلغ Webhook بأن خصم طلب في حالة المراجعة قد رُفض.

Refunded Status (الافتراضي مسترد): تم استرداد الدفعة عبر الإضافة.

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

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

علامة تبويب VibeFox Kushki Payment

في Sales > Orders افتح طلبًا دُفع عبر Kushki. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Kushki Payment Ticket number (مع تسمية TEST للمدفوعات التجريبية)، وTransaction reference، وEnvironment، وResult، والمبالغ Charged / order amount، ونموذج الاسترداد، وسجل الاسترداد، وKushki notes الخاصة بالطلب. تُعرض علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

تسترد Kushki الخصم كاملًا، لذا لا يمكن إلا الاسترداد الكامل. في علامة التبويب VibeFox Kushki Payment يُملأ Amount الذي خصمته Kushki. يمكنك اختياريًا إدخال Reason (optional)، ثم النقر على Refund via Kushki، ثم تأكيد السؤال Refund the full payment through Kushki? This cannot be undone. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). لأي مبلغ آخر تعرض الإضافة Kushki refunds the full payment only. Enter the full charged amount مع المبلغ، ولا يُرسل أي شيء. يتم الاسترداد بالمبلغ والعملة اللذين خصمتهما Kushki، لذلك بعد اختلاف في المبلغ يستعيد العميل ما خُصم فعلًا وليس إجمالي الطلب. لا يمكن استرداد الدفعة إلا مرة واحدة.

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

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

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

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

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

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

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

لا تظهر Kushki عند إتمام الشراء: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على معرّفَي التاجر: معرّفات الاختبار في وضع الاختبار، ومعرّفات الإنتاج في الوضع الحي. تعرض صفحة الإعدادات تحذيرًا عندما تكون المعرّفات مفقودة. تحقق من أن عملة الطلب USD أو COP، وأن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمت الدفعة لكن الطلب يبقى من دون حالة: فُقدت استجابة Kushki API، مثلًا بسبب انتهاء المهلة. يؤكد Webhook مثل هذه المدفوعات. في Kushki Console تحقق من أن رابط Webhook مطابق تمامًا للرابط المعروض في Webhook URL، لحساب الوضع الذي تستخدمه، وأن مفتاح التوقيع الخاص بذلك الحساب موجود في الحقل المناسب (Test webhook signature أو Live webhook signature). يضع الخصم المعتمد الذي لا يتضمن المبلغ والعملة المدفوعين الطلب في On Hold (Review) Status.

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

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

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

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

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

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

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

يرى العميل خطأ عند الدفع: فعّل Debug log وانظر إلى الحقل Log في صفحة الإضافة. تعني الرسالة This payment method is not available. Please reload the checkout page. أن جلسة إتمام الشراء لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في الأثناء: على العميل إعادة تحميل صفحة إتمام الشراء. ويؤدي معرّف التاجر الخاص الخاطئ أو المفقود إلى الرسالة العامة بأن الدفع تعذّر معالجته.

يرى العميل الرسالة Your payment was received, but the order could not be completed automatically: وافقت Kushki على الخصم، لكن OpenCart لم يتمكن من ضبط حالة الطلب. يوضح السجل السبب. تضبط محاولة الدفع التالية للسلة نفسها الحالة من دون خصم جديد.

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

لا يوجد نموذج استرداد في العلامة: تشرح العلامة السبب: الدفعة مستردة بالفعل، أو ليس للطلب رقم تذكرة Kushki (No Kushki ticket number found for this order — refund it in the Kushki Console.)، أو مجموعة المستخدمين الخاصة بك لا تملك صلاحية تعديل الإضافة، أو لم يُضبط معرّف التاجر الخاص لوضع الدفعة.

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

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

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

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