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

المتطلبات

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

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

حساب KOMOJU: تحتاج إلى المفتاح السري (sk_live_... ولوضع الاختبار sk_test_...) والرمز السري لـ webhook أُنشئ في لوحة KOMOJU (راجع الإعداد). المفتاح العام غير مطلوب. يجب أن تتمكن KOMOJU من الوصول إلى عنوان webhook الخاص بمتجرك.

عملة الطلب: JPY أو USD أو EUR أو TWD أو KRW أو PLN أو GBP أو HKD أو SGD أو NZD أو AUD أو IDR أو MYR أو PHP أو THB أو CNY أو BRL أو CHF أو CAD أو VND. للطلبات بعملات أخرى يُخفى طريقة الدفع.

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

التثبيت

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

OpenCart 3

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

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

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

4. في لوحة KOMOJU أضف webhook بالعنوان والأحداث المعروضة في قسم Webhook URL، وانسخ رمزه السري (راجع الإعداد).

5. أدخل المفتاح السري للإنتاج والرمز السري لـ webhook الخاص بالإنتاج، وكذلك مفاتيح الاختبار لوضع sandbox. فعّل Enable/Disable واضغط Save.

OpenCart 4

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

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

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

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

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

الإعداد

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox KOMOJU Payment > Edit. تُدرج الأقسام على اليسار؛ يحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات، تعرض الصفحة KOMOJU Sandbox Mode is enabled. طالما وضع الاختبار مفعّل. وتحذّرك إذا لم يكن للوضع الحالي مفتاح سري (فيُخفى عندئذٍ طريقة الدفع عند الدفع)، أو لم يكن له رمز سري لـ webhook (فتُرفض إشعارات KOMOJU ولا تُؤكَّد مدفوعات konbini والتحويل البنكي أبداً)، وإذا كانت KOMOJU لا تدعم العملة الافتراضية للمتجر (فتُخفى طريقة الدفع للطلبات بتلك العملة). وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

دفع KOMOJU

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضاً اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: KOMOJU Payment. إذا تُرك فارغاً، يُستخدم الاسم الافتراضي. بحد أقصى 128 حرفاً.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، أعلى زر التأكيد. الافتراضي: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

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

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

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

مفاتيح API المباشرة

تجد المفاتيح في لوحة KOMOJU (توجد هناك روابط الأقسام): المفتاح السري ضمن Settings > API keys، والرمز السري لـ webhook ضمن Settings > Webhooks (أضف هناك أولاً عنوان webhook المعروض في قسم Webhook URL).

Live Secret Key: المفتاح السري الخاص بالإنتاج في KOMOJU. يبدأ بـ sk_live_.

Live Webhook Secret Token: الرمز السري لـ webhook الخاص بالإنتاج. يُستخدم للتحقق من توقيع كل إشعار.

وضع الاختبار

تستخدم KOMOJU عنوان API نفسه للمدفوعات التجريبية والحقيقية: والمفتاح هو ما يحدد الوضع. تحتفظ المدفوعات بالوضع الذي تمت فيه، لذلك تستخدم عمليات الاسترداد واستعلامات الحالة لطلب ما دائماً مفتاح ذلك الوضع.

Sandbox Mode: Enable test mode (use the test keys below, no real payments). الافتراضي: معطّل. عند التفعيل تعرض خطوة Confirm Order العبارة Test mode فوق الوصف.

Sandbox Secret Key: المفتاح السري للاختبار في KOMOJU. يبدأ بـ sk_test_.

Sandbox Webhook Secret Token: الرمز السري لـ webhook الخاص بوضع الاختبار.

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

عنوان Webhook URL

يُخبر webhook متجرك بالمدفوعات، بما في ذلك مدفوعات konbini والتحويل البنكي المؤجلة. في لوحة KOMOJU ضمن Settings > Webhooks، أضف العنوان المعروض في هذا القسم، سواء للوضع المباشر أو لوضع الاختبار. في OpenCart 3 يبدو العنوان هكذا: https://your-store/index.php?route=extension/payment/wcp_komoju_payment/webhook، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_komoju_payment/payment/wcp_komoju_payment.webhook، ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart لديك. انسخ العنوان تماماً كما تعرضه الإعدادات. ثم انسخ الرمز السري لكل webhook إلى Live Webhook Secret Token أو Sandbox Webhook Secret Token.

حدد هذه الأحداث (مدرجة أيضاً في هذا القسم):

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

الطلبات

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

Order Status After Payment: جرى تحصيل الدفع، وتم التحقق من المبلغ والعملة. الافتراضي: Processing.

Awaiting KOMOJU Payment Status: الدفع مُفوَّض: صدر إيصال konbini أو تحويل بنكي، أو أن الدفع ينتظر التحصيل في لوحة KOMOJU. الافتراضي: Pending.

KOMOJU Payment On Hold Status: المبلغ المدفوع أو العملة يختلفان عن الطلب، أو وصل الدفع بعد إلغاء الطلب. توضح ملاحظة السبب. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold.

Cancelled Payment Status: انتهت صلاحية دفع طلب معلّق أو أُلغي، مثلاً لأن إيصال konbini لم يُدفع في الوقت المحدد. الافتراضي: Canceled.

Failed Payment Status: فشل دفع طلب معلّق. الافتراضي: Failed.

Refunded Status: يُعيَّن بعد استرداد الدفع بالكامل، من صفحة الطلب أو من لوحة KOMOJU. الافتراضي: Refunded.

يمكنك إنشاء حالاتك الخاصة، مثل Awaiting KOMOJU payment أو On hold، في System > Localisation > Order Statuses واختيارها هنا.

متقدم

Invoice Prefix: البادئة لأرقام الطلبات المرسلة إلى KOMOJU. يتكون الرقم لدى KOMOJU من البادئة ورقم طلب OpenCart ولاحقة عشوائية قصيرة، مثل OC-123-A1B2C3. إذا كنت تستخدم عدة متاجر مع حساب KOMOJU نفسه، فاجعل البادئة فريدة لكل متجر. الافتراضي: OC-.

Enable Logging: يكتب أحداث KOMOJU واستدعاءات API في komoju_p_debug.log.php ضمن مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح وبيانات العملاء. تُكتب الأخطاء والتحذيرات دائماً. الافتراضي: معطّل.

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

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

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

Export: يحفظ Download JSON الإعدادات في ملف JSON. لا تُصدَّر المفاتيح السرية ورموز webhook.

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضياً KOMOJU Payment). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the KOMOJU payment page to complete the payment.. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال دون حالة. عندما ينقر العميل Confirm Order، تنشئ الإضافة جلسة دفع KOMOJU بمبلغ إجمالي الطلب وبعملة الطلب، وتنقل العميل إلى صفحة دفع KOMOJU. تُنقل إلى KOMOJU البريد الإلكتروني والاسم وعناوين الدفع والشحن والمنتجات المطلوبة. تُعرض الصفحة باليابانية أو الإنجليزية أو الكورية، حسب لغة العميل (وبالإنجليزية للغات الأخرى). وهناك يختار العميل طريقة دفع. تعتمد طرق الدفع المتاحة على حسابك في KOMOJU وعلى عملة الطلب.

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

بعد الدفع يعود العميل إلى متجرك. تقرأ الإضافة جلسة الدفع من واجهة KOMOJU API باستخدام مفتاح وضع الدفع. لا يُعلَّم الطلب مدفوعاً إلا بعد أن تؤكده KOMOJU: إما عبر webhook الموقَّع، أو بقراءة الجلسة عند عودة العميل. وبعدها يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح طلب OpenCart مع العبارة Your payment with KOMOJU has been received.. إذا تعذّر الوصول إلى KOMOJU في تلك اللحظة، أو تأكد الدفع لكنه لم يُطبَّق بعد، تظهر صفحة Payment confirmation مع We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. وزر Check again.

في مدفوعات konbini والتحويل البنكي يحصل العميل على إيصال دفع. يحصل الطلب على Awaiting KOMOJU Payment Status، وتخبر صفحة النجاح العميل بأن الدفع مُفوَّض ويجب إتمامه وفق تعليمات KOMOJU (مثلاً في متجر مريح أو عبر التحويل البنكي). ينتقل الطلب إلى Order Status After Payment عندما يدفع العميل وترسل KOMOJU الـ webhook. وإذا انتهت صلاحية الإيصال، ينتقل الطلب إلى Cancelled Payment Status.

إذا لم يكتمل الدفع، يعود العميل إلى صفحة الدفع مع العبارة The payment was not completed. You can try again or choose another payment method. وإذا كان الطلب قد أُلغي بالفعل، تكون الرسالة The KOMOJU payment was not completed and the order has been cancelled. تبقى السلة محفوظة. في OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع. وفي كل محاولة جديدة (ينشئ OpenCart 3 طلباً جديداً في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيُحدِّث طلب الدفع في صفحة الدفع، فيدفع العميل الطلب نفسه من جديد) تُفحص جلسات KOMOJU المفتوحة لهذا الطلب ولطلبات أخرى من السلة نفسها: تُعاد استخدام الجلسة المفتوحة لهذا الطلب إذا لم يتغير إجماليها، وتُلغى الجلسات المفتوحة الأخرى لدى KOMOJU، والجلسة التي دُفعت في الأثناء تؤكد طلبها بدلاً من إنشاء دفعة جديدة. ويُحسب تغيير السلة، بما فيه الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تظهر صفحة النجاح. وإذا أُغلق هذا الطلب في الأثناء (مثلاً انتهت صلاحية إيصال konbini أو فشل الدفع أو ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled or its payment failed. Please confirm the order again. وإذا كان الطلب قد تم تقديمه بالفعل وتحتوي السلة الآن على منتجات أخرى، فالرسالة هي Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. وفي الحالتين، يدفع Confirm Order التالي طلباً جديداً للسلة.

إذا تعذّر على KOMOJU بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل KOMOJU could not accept this payment: مع السبب، أو KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. أو Payment error: Could not connect to KOMOJU. Please try again in a moment.. ويُكتب السبب التقني في السجل.

يعمل الـ webhook أيضاً أثناء وجود المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة في OpenCart 4 startup action يسمح بمرور الـ webhook وعودة العميل.

لا تتضمن الإضافة نموذج بطاقة على موقعك، ولا بطاقات محفوظة، ولا اشتراكات. ولا تقيّد طرق الدفع: إذ تُختار على صفحة KOMOJU. ولا تتضمن إجراء تحصيل يدوياً: يجب تحصيل المدفوعات المُفوَّضة للتحصيل اليدوي في لوحة KOMOJU، ويبقى الطلب في Awaiting KOMOJU Payment Status حتى ذلك الحين.

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

حالات الطلب

No status (missing order): أُرسل العميل إلى KOMOJU ولم يدفع، أو لم تؤكد KOMOJU الدفع بعد. تظهر هذه الطلبات في Sales > Orders فقط عند ضبط فلتر Order Status على Missing Orders.

Order Status After Payment (default Processing): أكدت KOMOJU الدفع. تعرض ملاحظة معرّف دفع KOMOJU وطريقة الدفع وكيفية التأكيد (webhook أو عودة).

Awaiting KOMOJU Payment Status (default Pending): صدر إيصال konbini أو تحويل بنكي وينتظر الدفع، أو أن دفعة تنتظر التحصيل في لوحة KOMOJU.

KOMOJU Payment On Hold Status (default Pending): أبلغت KOMOJU عن مبلغ أو عملة مختلفين عن إجمالي الطلب، أو جرى تحصيل الدفع بعد إلغاء الطلب. توضح الملاحظة ذلك. تحقق من الطلب ثم أكمله أو استرد الدفع.

Cancelled Payment Status (default Canceled): انتهت صلاحية إيصال الدفع أو أُلغي الدفع.

Failed Payment Status (default Failed): فشل دفع طلب معلّق.

Refunded Status (default Refunded): استُرد الدفع بالكامل، من صفحة الطلب أو من لوحة KOMOJU.

إذا جرى تحصيل دفعة ثانية لطلب مدفوع أصلاً، أو لطلب آخر من سلة مدفوعة، فلن يتغير الطلب. وتطلب الملاحظة منك استرداد الدفعة من لوحة KOMOJU إذا كانت مكررة. لا تُعاد فتح الطلبات المستردة أبداً.

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

تبويب VibeFox KOMOJU Payment

في Sales > Orders افتح طلباً مدفوعاً عبر KOMOJU. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox KOMOJU Payment معرّف دفع KOMOJU (مع رابط إلى الدفعة في لوحة KOMOJU)، وتسمية Test mode للمدفوعات التجريبية، وطريقة الدفع، والجلسة، ورقم الطلب لدى KOMOJU، والحالة، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد (من OpenCart أو من لوحة KOMOJU)، وKOMOJU notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox KOMOJU Payment أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد تلقائياً)، واختيارياً Reason (optional)، ثم اضغط Refund via KOMOJU. أكّد السؤال Refund this amount through KOMOJU? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). الاستردادات محدودة بالمبلغ الذي حصّلته KOMOJU فعلياً، لذلك بعد اختلاف في المبلغ يمكنك الاسترداد حتى مقدار ما دفعه العميل، لا إجمالي الطلب. يُرسل الاسترداد بمفتاح الوضع الذي تمت فيه الدفعة، لذلك يجب ضبط المفتاح السري لذلك الوضع. تتحقق الإضافة أولاً من الدفعة لدى KOMOJU، وترفض الاستردادات التي تتجاوز المبلغ المتبقي القابل للاسترداد. إذا تعذّر على KOMOJU استرداد الدفعة تلقائياً (بعض الوسائل، مثل konbini، تحتاج إلى البيانات البنكية للعميل)، فستظهر رسالة الخطأ من KOMOJU ولا يُسجَّل شيء: عالج هذه الاستردادات في لوحة KOMOJU. لا يُعد الاسترداد منجزاً إلا عندما تؤكده KOMOJU. يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات. ويضبط الاسترداد الكامل الطلب على Refunded Status دون إعادة المنتجات إلى المخزون، كما في تغيير الحالة يدوياً. ولا يغيّر الاسترداد الجزئي الحالة. وتصبح الاستردادات متاحة بعد أن تكون KOMOJU قد حصّلت الدفعة.

بالنسبة للمدفوعات التي حوّلتها KOMOJU إلى عملة أخرى (مثلاً konbini بالين الياباني لطلب باليورو)، لا يمكن من OpenCart إلا الاسترداد الكامل. أجرِ الاستردادات الجزئية من لوحة KOMOJU.

لا تعيد المرتجعات في Sales > Returns المال عبر KOMOJU.

تصل الاستردادات التي أُجريت في لوحة KOMOJU عبر webhook، وتُضاف إلى سجل الاسترداد مع ملاحظة. وعندما يُسترد الدفع بالكامل، يُعيَّن الطلب على Refunded Status. أما الاستردادات الجزئية التي أُجريت من اللوحة لمدفوعات حُوّلت إلى عملة أخرى، فتُسجَّل في الطلب كملاحظة فقط: سجّل المبلغ المقابل يدوياً في OpenCart.

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

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

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

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

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

لا يظهر KOMOJU عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح سري: Sandbox Secret Key في وضع الاختبار، وLive Secret Key في الوضع المباشر. يجب أن يدفع العميل بعملة تدعمها KOMOJU. تعرض صفحة الإعدادات تحذيراً عند غياب شيء. وتحقق أيضاً من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تم الدفع، لكن الطلب يبقى دون حالة: الـ webhook لا يعمل. في لوحة KOMOJU تحقق من وجود الـ webhook للوضع الذي تستخدمه، وأن عنوانه مطابق تماماً للعنوان المعروض في قسم Webhook URL، وأن الأحداث محددة. تحقق من أن رمزه السري موجود في الحقل المناسب (Live Webhook Secret Token أو Sandbox Webhook Secret Token)، وانظر إلى الحقل Log في صفحة الإضافة. تُؤكَّد مدفوعات البطاقات أيضاً عندما يعود العميل إلى متجرك، لكن مدفوعات konbini والتحويل البنكي تُؤكَّد بالـ webhook فقط.

يجيب webhook بـ Failed to verify KOMOJU webhook signature.: الرمز السري مفقود أو يخص webhook آخر. ستعيد KOMOJU محاولة الإشعار.

يجيب webhook بـ Mode mismatch, ignored.: وُقّع الـ webhook بالرمز السري لوضع مختلف عن الوضع الذي تمت فيه الدفعة. استخدم webhooks ورموزاً منفصلة للوضع المباشر ولوضع الاختبار، وتحقق من عدم تبادلها.

يجيب webhook بـ Order not found.: الدفعة لا تخص طلباً في هذا المتجر، مثلاً لأن متجراً آخر على الحساب نفسه في KOMOJU أجراها. يُتجاهل الحدث.

يجيب webhook بـ Order is busy, retry later. أو Temporary error, retry later.: كان الطلب يُحدَّث بواسطة طلب آخر، أو تعذّرت معالجة الدفعة في تلك اللحظة. ستعيد KOMOJU محاولة الإشعار. السبب موجود في السجل.

يعرض عنوان webhook خطأ في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الموقّعة من KOMOJU فقط.

الطلب في حالة الانتظار أو التعليق: اقرأ KOMOJU notes في تبويب الطلب. إما أن إيصالاً ينتظر الدفع، أو أن دفعة تنتظر التحصيل في لوحة KOMOJU، أو أن المبلغ أو العملة لم يتطابقا، أو أن الدفعة وصلت بعد إلغاء الطلب.

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

يفشل الاسترداد: اقرأ الرسالة. قد يكون المفتاح السري للوضع الذي تمت فيه الدفعة مفقوداً، أو قد لا تكون الدفعة قابلة للاسترداد تلقائياً (استردها في لوحة KOMOJU)، أو قد لا تعرف KOMOJU الدفعة بالمفتاح المضبوط، أو قد لا يكون ممكناً إلا الاسترداد الكامل لدفعة محوّلة.

للمطورين: تُطلق الإضافة أحداث OpenCart komoju_p_supported_currencies (لتغيير قائمة العملات) و komoju_p_session_params (لتغيير جلسة الدفع، مثل طرق الدفع).

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

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

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

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