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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

حساب 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. يعمل مفتاح واحد على نطاق واحد.

التثبيت

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

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

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

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

5. أدخل المفتاح السري للإنتاج ورمز webhook السري للإنتاج، والمفاتيح التجريبية لوضع الاختبار. فعّل Enable/Disable وانقر Save.

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting KOMOJU payment وKOMOJU payment on hold. يربط PrestaShop وحدة الدفع الجديدة فقط بالدول النشطة في تلك اللحظة: الدولة التي تفعّلها لاحقًا يجب تحديدها للوحدة في Payment > Preferences. وهناك يمكنك أيضًا تقييد العملات ومجموعات العملاء.

الإعدادات

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

الدفع عبر KOMOJU

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

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 المعروض في قسم 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). الافتراضي: معطّل. ما دام مفعّلًا يعرض إتمام الشراء Test mode فوق الوصف.

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

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

لا تُعرض المفاتيح والرموز المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

مسح الأسرار المحفوظة: ضع علامة على مفتاح أو رمز وانقر Save لإزالته. الحقل الفارغ يحتفظ بالقيمة المحفوظة.

عنوان Webhook

يُبلغ الـ webhook متجرك بالمدفوعات، بما في ذلك مدفوعات konbini والتحويل المصرفي المؤجلة. في لوحة KOMOJU تحت Settings > Webhooks، أضف العنوان المعروض في هذا القسم، لوضع الإنتاج ووضع الاختبار. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_komoju_payment/webhook، وربما مع رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات. ثم انسخ الرمز السري لكل webhook إلى Live Webhook Secret Token أو Sandbox Webhook Secret Token.

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

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

متقدم

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

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

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

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

إتمام الشراء

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

بعد الدفع يعود العميل إلى متجرك. تقرأ الوحدة جلسة الدفع من واجهة KOMOJU البرمجية باستخدام مفتاح وضع الدفعة. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده KOMOJU: إما عبر webhook الموقَّع أو عبر قراءة الجلسة عند عودة العميل. ثم يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة 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، وتطلب صفحة التأكيد من العميل إتمام الدفع وفق تعليمات KOMOJU (مثلًا في متجر صغير أو عبر تحويل مصرفي). يصبح الطلب Payment accepted حين يدفع العميل وترسل KOMOJU الـ webhook. وإذا انتهت صلاحية القسيمة أو فشل الدفع لاحقًا، تعرض صفحة التأكيد Your KOMOJU payment was not completed. Please contact us about this order.

إذا لم يكتمل الدفع، يعود العميل إلى إتمام الشراء مع الرسالة The payment was not completed. You can try again or choose another payment method. تُحفظ السلة. تعيد المحاولة الجديدة استخدام جلسة KOMOJU المفتوحة إذا لم يتغير الإجمالي. تُلغى الجلسة ذات الإجمالي القديم في KOMOJU، والجلسة التي دُفعت في الأثناء تُنشئ الطلب بدلًا من دفع جديد.

إذا تعذّر على 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. يُكتب السبب الفني في السجل.

إذا توقف قسيمة الخصم في السلة عن الصلاحية بين الدفع وتأكيده، يزيلها PrestaShop من الطلب. ينتقل الطلب عندئذ إلى KOMOJU payment on hold مع ملاحظة، لأن العميل دفع السعر بعد الخصم.

يعمل الـ webhook أثناء وضع الصيانة للمتجر، ولا يتأثر بقيد الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى KOMOJU ولم يدفع بعد، أو لم تؤكد KOMOJU الدفع بعد. لا توجد إلا السلة.

Payment accepted: أكدت KOMOJU الدفع. يُسجَّل الدفع برقم دفع KOMOJU كرقم معاملة، وتعرض ملاحظة رقم الدفع وطريقة الدفع وكيفية التأكيد (webhook أو عودة).

Awaiting KOMOJU payment: صدرت قسيمة konbini أو تحويل مصرفي وتنتظر الدفع، أو ينتظر دفع ما التحصيل في لوحة KOMOJU.

KOMOJU payment on hold: أبلغت KOMOJU عن مبلغ أو عملة مختلفين عن إجمالي الطلب (مثلًا تغيّرت السلة بعد بدء الدفع)، أو أُزيلت قسيمة خصم، أو حُصّل الدفع بعد إلغاء الطلب. تشرح الملاحظة ذلك. راجع الطلب ونفّذه أو استرد الدفع.

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

Payment error: فشل دفع لطلب موجود.

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

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

كتلة الدفع عبر KOMOJU

تعرض صفحة الطلب كتلة KOMOJU payment تضم رقم دفع KOMOJU (مرتبطًا بالدفعة في لوحة KOMOJU) وطريقة الدفع والجلسة ورقم الطلب لدى KOMOJU والحالة والمبلغ المدفوع والمبلغ المسترد، وشارة Test mode لمدفوعات الاختبار، وسجل الاستردادات وKOMOJU notes الخاصة بالطلب.

الاستردادات

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

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

لا تُنشئ الوحدة إشعارات دائن. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر KOMOJU.

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

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

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

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

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

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

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

تمت عملية الدفع لكن لم يُنشأ أي طلب: الـ 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 is busy, retry later. أو Temporary error, retry later.: كان الطلب يُحدَّث بطلب آخر، أو تعذّر إنشاء الطلب في تلك اللحظة (مثلًا الوحدة معطّلة)، أو تعذّر التحقق من الدفعة. تعيد KOMOJU إرسال الإشعار. السبب موجود في السجل.

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

الطلب في KOMOJU payment on hold أو Awaiting KOMOJU payment: اقرأ KOMOJU notes في كتلة الطلب. قسيمة تنتظر الدفع، أو دفعة تنتظر التحصيل في لوحة KOMOJU، أو المبلغ أو العملة لم يتطابقا، أو أُزيلت قسيمة خصم، أو وصلت الدفعة بعد إلغاء الطلب.

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

يمكن للمطورين تغيير قائمة العملات بالخطاف actionKomojuPSupportedCurrencies، وجلسة الدفع، مثل طرق الدفع، بالخطاف actionKomojuPSessionParams.

الإزالة

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

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