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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: يحتاج موقعك إلى HTTPS، ويجب أن تتمكن KOMOJU من الوصول إلى عنوان URL الخاص بـ webhook.

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

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

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

التثبيت

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

2. انقر Activate.

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

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

5. في لوحة تحكم KOMOJU أضف webhook بعنوان URL والأحداث المدرجة في صفحة الإعدادات، وانسخ رمزه السري (انظر الإعداد).

6. أدخل المفتاح السري ورمز webhook السري للإنتاج، ونظيريهما للاختبار في وضع sandbox. شغّل Enable/Disable واحفظ.

الإعداد

كل الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > KOMOJU Payment. يظهر KOMOJU Sandbox Mode is enabled. فوق الحقول في وضع الاختبار. تحذّرك الصفحة إذا لم يكن للوضع الحالي مفتاح سري (فتُخفى الطريقة عند الدفع)، أو رمز webhook سري (فتُرفض إشعارات KOMOJU ولا تُؤكد مدفوعات konbini والتحويل المصرفي أبدًا)، وعند عدم دعم عملة المتجر. في قائمة طرق الدفع، تُعلَّم KOMOJU بأنها تحتاج إلى إعداد حتى يُضاف المفتاح السري للوضع الحالي، وتعرض شارة اختبار أثناء تشغيل sandbox.

عام

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

Title: اسم طريقة الدفع الذي يراه العميل عند الدفع. الافتراضي: KOMOJU Payment.

Description: النص تحت الطريقة عند الدفع. الافتراضي: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

مفاتيح API للإنتاج

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

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). الافتراضي: off. عند تشغيله، تظهر Test mode فوق الوصف في صفحة الدفع.

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

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

عنوان URL الخاص بـ webhook

يُخبر webhook متجرك بالمدفوعات، بما فيها مدفوعات konbini والتحويل المصرفي المؤجلة. في لوحة تحكم KOMOJU تحت Settings > Webhooks، أضف عنوان URL الظاهر في هذا القسم للاختبار والإنتاج. يكون مثل https://your-site/wc-api/komoju_p_webhook/. إذا استخدم موقعك بادئة لغة في العناوين، انسخ العنوان كما تعرضه الإعدادات تمامًا. ثم انسخ الرمز السري لكل webhook إلى Live Webhook Secret Token أو Sandbox Webhook Secret Token.

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

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

متقدم

Invoice Prefix: بادئة أرقام الطلبات المُرسلة إلى KOMOJU. إذا كانت متاجر متعددة تستخدم الحساب نفسه، اجعلها فريدة لكل متجر. الافتراضي: WC-.

Enable Logging: Log KOMOJU events and API calls في WooCommerce > Status > Logs، المصدر wcp_komoju_payment، بلا مفاتيح أو بيانات عملاء. تُسجَّل الأخطاء دائمًا. الافتراضي: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف شيئًا أبدًا. تبقى بيانات الطلبات (معرّفات دفع KOMOJU في الطلبات) دائمًا. الافتراضي: off.

إتمام الدفع

يختار العميل الطريقة (افتراضيًا KOMOJU Payment) ويقدّم الطلب. تُنشئ الإضافة جلسة KOMOJU بإجمالي الطلب وعملته وتوجّه العميل إلى صفحة دفع KOMOJU. تُرسل إلى KOMOJU بيانات البريد الإلكتروني للفوترة والاسم وعناوين الفوترة والشحن والمنتجات المطلوبة. تظهر الصفحة باليابانية أو الإنجليزية أو الكورية وفق لغة الموقع (الإنجليزية للغات الأخرى). هناك يختار العميل الطريقة. تعتمد الخيارات على حسابك في KOMOJU وعملة الطلب.

بعد الدفع يعود العميل إلى متجرك. تقرأ الإضافة الجلسة من API لدى KOMOJU بمفتاح وضع الطلب. لا يُعلَّم الطلب كمدفوع إلا بتأكيد KOMOJU: عبر webhook الموقَّع أو قراءة الجلسة عند العودة. إذا تعذر الاتصال حينها، يصل العميل إلى صفحة استلام الطلب مع 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.

في konbini والتحويل المصرفي يحصل العميل على قسيمة. يبقى الطلب قيد الانتظار ويكتمل حين يدفع العميل وترسل KOMOJU إشعار webhook. إذا انتهت القسيمة يُلغى الطلب.

إذا لم يكتمل الدفع يعود العميل إلى Pay for order مع The payment was not completed. You can try again or choose another payment method. تعيد المحاولة استخدام الجلسة المفتوحة إذا لم يتغير الإجمالي. تُلغى الجلسة ذات الإجمالي القديم في KOMOJU، وتؤكد الجلسة المدفوعة في الأثناء الطلب. عند إلغاء طلب غير مدفوع (بواسطتك أو العميل أو مؤقت حجز المخزون في WooCommerce)، تُلغى جلسته المفتوحة أيضًا، فلا يمكن دفعها بعد ذلك.

إذا تعذر على KOMOJU بدء الدفع، يرى العميل رسالة قصيرة مثل 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. تُضاف التفاصيل إلى ملاحظات الطلب والسجل.

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

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

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

حالات الطلبات

Pending payment: وُجّه العميل إلى KOMOJU ولم يدفع بعد، أو لم تؤكد KOMOJU الدفع بعد.

Processing or Completed: أكدت KOMOJU الدفع. يحدد WooCommerce الحالة المعتادة للطلب المدفوع. تعرض الملاحظة معرّف دفع KOMOJU والطريقة ومسار التأكيد (webhook أو العودة). معرّف المعاملة هو معرّف دفع KOMOJU، ويربط من شاشة الطلب إلى الدفع في لوحة تحكم KOMOJU.

On hold: أُصدرت قسيمة konbini أو تحويل وتنتظر الدفع، أو ينتظر الدفع التحصيل في لوحة التحكم. يوضع الطلب قيد الانتظار أيضًا عند عدم تطابق المبلغ أو العملة، أو التحصيل بعد إلغاء الطلب. تشرح الملاحظة ذلك. نفّذ الطلب أو استرد الدفع.

Failed: فشل الدفع. يمكن للعميل إعادة المحاولة.

Cancelled: انتهت صلاحية القسيمة أو أُلغي الدفع.

Refunded: استُرد الدفع كاملًا من WooCommerce أو لوحة تحكم KOMOJU.

إذا حُصِّل دفع ثانٍ لطلب مدفوع بالفعل، فلا يتغير الطلب مجددًا. تطلب ملاحظة استرداده في لوحة التحكم إن كان مكررًا. لا تُفتح الطلبات المستردة مجددًا أبدًا.

الاستردادات

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

للمدفوعات المحوَّلة إلى عملة أخرى (مثل konbini بعملة JPY لطلب EUR)، لا يمكن من WooCommerce إلا الاسترداد الكامل. نفّذ الجزئي في لوحة تحكم KOMOJU.

تصل استردادات لوحة KOMOJU عبر webhook وتُسجَّل تلقائيًا كاستردادات WooCommerce. يضبط الكامل الطلب على تم رد المبلغ. يُكتفى بملاحظة للاستردادات الجزئية من اللوحة للمدفوعات المحوَّلة: سجّل المبلغ المقابل في WooCommerce عبر "Refund manually".

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

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

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

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

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

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

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

نجح الدفع لكن الطلب Pending payment: webhook لا يعمل. تحقق في لوحة التحكم من وجوده للوضع المستخدم، وتطابق URL تمامًا مع الإعدادات، واختيار الأحداث. تحقق من الرمز في الحقل المناسب (Live Webhook Secret Token أو Sandbox Webhook Secret Token) وراجع WooCommerce > Status > Logs، المصدر wcp_komoju_payment. تؤكد البطاقات عند العودة أيضًا، أما konbini والتحويلات فبالـ webhook فقط.

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

يرد webhook برسالة Mode mismatch, ignored: وُقّع برمز وضع مختلف عن وضع دفع الطلب. استخدم webhooks ورموزًا منفصلة للإنتاج والاختبار.

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

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

فشل الاسترداد: اقرأ الرسالة. ربما غاب مفتاح وضع الدفع، أو تعذر الاسترداد الآلي (نفّذه في اللوحة)، أو اقتصر الدفع المحوَّل على الاسترداد الكامل.

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

يمكن للمطورين تغيير العملات بالمرشح komoju_p_supported_currencies وجلسة الدفع، مثل طرق الدفع، بالمرشح komoju_p_session_params.

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

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

KOMOJU علامة تجارية لمالكها المعني. هذه الإضافة ليست تابعة لـ KOMOJU ولا معتمدة منها.