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

المتطلبات

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

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

HTTPS: حقول البطاقة موجودة في صفحة الدفع الخاصة بمتجرك، لذلك يجب تقديم صفحة الدفع عبر HTTPS. ومع ذلك لا تصل بيانات البطاقة إلى خادمك أبدًا. ترسل Omise الـ webhooks إلى عناوين HTTPS فقط، ويجب أن تكون صفحة 3-D Secure الخاصة بالبنك عنوان HTTPS.

العملة: إحدى العملات التالية: THB وJPY وSGD وMYR وUSD وEUR وGBP وAUD وCAD وCHF وCNY وDKK وHKD. عندما يدفع العميل بأي عملة أخرى، تُخفى طريقة الدفع في صفحة الدفع.

حساب Omise: تحتاج إلى المفتاح العام والمفتاح السري لحساب Omise الخاص بك، للاختبار وللوضع الفعلي، من Settings > Keys في لوحة تحكم Omise، إلى نقطة نهاية webhook في Settings > Webhooks (انظر Configuration).

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل مفاتيح Omise الخاصة بالاختبار والإنتاج، وأضف عنوان webhook الظاهر في صفحة الإعدادات إلى لوحة تحكم Omise (انظر Configuration).

5. فعّل Enable/Disable وانقر على Save. اختبر دفعة في وضع الاختبار ببطاقة اختبار من Omise مثل 4242 4242 4242 4242، ثم أوقف تفعيل Test mode.

OpenCart 4

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

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

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

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

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

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Omise Payment > Edit. تظهر الأقسام في القائمة على اليسار؛ ويحفظ زر Save الموجود أسفل القائمة الصفحة بأكملها. وفوق الإعدادات، تعرض الصفحة Test mode is on — orders are charged with the test keys, no real money is moved. طالما أن وضع الاختبار مفعّل، وتحذّرك إذا كان المفتاح العام أو السري للوضع الحالي مفقودًا (وفي هذه الحالة تُخفى طريقة الدفع في صفحة الدفع)، وتحذّرك إذا لم تقبل Omise العملة الافتراضية لمتجرك. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

Omise

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit / Debit Card. حقل مطلوب، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر فوق نموذج البطاقة في خطوة Confirm Order. الافتراضي: Pay securely with your credit or debit card via Omise.

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

Geo Zone: اعرض نموذج البطاقة فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المختارة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones. في OpenCart 4، عندما لا يطلب المتجر عنوان دفع، يُستخدم عنوان الشحن.

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

مفاتيح API

تجد مفاتيحك في لوحة تحكم Omise تحت Settings > Keys (الصفحة تحتوي على رابط إليها). تبدأ مفاتيح الاختبار بـ pkey_test_ وskey_test_، وتبدأ مفاتيح الوضع الفعلي بـ pkey_ وskey_.

Test mode: يستخدم مفاتيح الاختبار، دون أي خصومات فعلية. ويبدّل المفتاحين معًا. وتستخدم عمليات التحصيل والاسترداد وفحص حالة الطلب دائمًا مفاتيح الوضع الذي دُفع فيه الطلب. الافتراضي: on.

Test public key: المفتاح العام لوضع الاختبار، pkey_test_...، الذي يستخدمه Omise.js في المتصفح.

Test secret key: المفتاح السري لوضع الاختبار، skey_test_...

Live public key: المفتاح العام للوضع الفعلي، pkey_...، الذي يستخدمه Omise.js في المتصفح.

Live secret key: المفتاح السري للوضع الفعلي، skey_...

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

الدفع وwebhook

Webhook URL: عنوان الـ webhook الخاص بمتجرك. في OpenCart 3 يبدو بالشكل https://your-store/index.php?route=extension/payment/wcp_omise_payment/webhook، وفي OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_omise_payment/payment/wcp_omise_payment.webhook، ويُبنى من عنوان واجهة المتجر لتثبيت OpenCart الخاص بك. انسخه تمامًا كما تعرضه الإعدادات، وأضفه في لوحة تحكم Omise تحت Settings > Webhooks (HTTPS فقط). تتعامل الإضافة مع هذه الأحداث (وهي مدرجة في هذا القسم أيضًا):

لا توقّع Omise على الـ webhooks، لذلك لا يُوثق بمحتوى الـ webhook أبدًا: يجب أن يكون الخصم قد أنشأه هذا المتجر لذلك الطلب، ويُعاد قراءة حالته من واجهة Omise البرمجية باستخدام المفتاح السري لوضع الدفع. ومن دون الـ webhook، لا يُحدَّث الطلب الذي يغلق فيه العميل المتصفح أثناء 3-D Secure تلقائيًا، ولا تُرصد عمليات التحصيل التي تتم من لوحة تحكم Omise حتى تنقر على Sync payment status.

Payment action: ما الذي يحدث لمبلغ البطاقة.

Per-charge webhook: يرسل عنوان الـ webhook مع كل خصم. مفيد عندما تشترك عدة متاجر في حساب Omise واحد. يعمل فقط عندما يستخدم المتجر HTTPS؛ وإلا يُستخدم الـ webhook المضبوط في لوحة التحكم. الافتراضي: off.

الطلبات

يُنشأ الطلب في خطوة Confirm Order دون حالة (طلب مفقود)، ولا يحصل على حالة إلا بعد أن ترد Omise بشأن البطاقة. لا تملك OpenCart حالة On hold: افتراضيًا تكون حالات المعتمد والمراجعة والانتظار كلها Pending، وتميّز علامة تبويب الطلب والملاحظات بينها. يمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Order Status After Payment: خُصمت قيمة البطاقة (Capture immediately، أو تحصيل لاحق). الافتراضي: Processing.

Authorized Status: Authorize only: المبلغ محجوز، ولم يُحصَّل بعد. الافتراضي: Pending.

On Hold (Review) Status: المبلغ المخصوم أو العملة يختلفان عن الطلب. الافتراضي: Pending.

Awaiting Payment Status: أنهى العميل الخطوات، لكن Omise لم تؤكد الخصم بعد. الافتراضي: Pending.

Failed Status: فشل لاحقًا خصم معلّق لطلب يحمل حالة ما. الافتراضي: Failed.

Canceled Status: انتهت صلاحية الخصم أو أُلغي التفويض، ولم يُسحب أي مبلغ. الافتراضي: Canceled.

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

متقدم

Debug log: يكتب طلبات API وأحداث الدفع في الملف omise_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى omise_p_debug.old.log.php. لا تُسجَّل المفاتيح والرموز وبيانات البطاقة أبدًا. الافتراضي: off. وطالما هذا المفتاح متوقف، لا يُكتب أي شيء، بما في ذلك الأخطاء، لذلك فعّله عندما تبحث عن مشكلة.

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

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

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

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

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

صفحة الدفع

في خطوة Payment Method، يختار العميل طريقة الدفع (افتراضيًا Credit / Debit Card). وفي خطوة Confirm Order، يرى العميل وصفك ونموذج البطاقة: Name on card وCard number وExpiry month (MM) وExpiry year (YYYY) وSecurity code (CVV). وفي وضع الاختبار يعرض النموذج TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال دون حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طرق الدفع، في النافذة Payment method options؛ ويوجد نموذج البطاقة في قسم التأكيد أسفل صفحة الدفع، فوق Confirm Order. وعندما ينقر العميل على Confirm Order، يحوّل Omise.js البطاقة إلى رمز لمرة واحدة في المتصفح، مستخدمًا عنوان الدفع الخاص بالطلب (وفي OpenCart 4، عندما لا يطلب المتجر عنوان دفع، يُستخدم عنوان الشحن). ولا تُرسل حقول البطاقة إلى متجرك أبدًا. وتظهر الحقول الناقصة أو غير الصالحة فوق النموذج، مثل Please enter a valid card number.

ثم ينشئ متجرك الخصم باستخدام المفتاح السري بمبلغ إجمالي الطلب وبعملة الطلب. ويكون وصف الخصم اسم المتجر ورقم الطلب، ويُحفظ معرّف الطلب في البيانات الوصفية للخصم. وإذا طلب البنك التحقق عبر 3-D Secure، يُنقل العميل إلى صفحة البنك ثم يعود إلى متجرك، وتُعاد قراءة النتيجة من واجهة Omise البرمجية.

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Omise ذلك: يجب أن يكون الخصم محصّلًا، ويجب أن يطابق مبلغه وعملته الطلب. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلبات وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع العبارة Your card payment has been received. وعند استخدام Authorize only تقول الصفحة Your card payment has been authorized. The amount will be charged when your order is processed. وإذا ما زالت Omise تُبلغ عن الدفع بأنه قيد الانتظار، يحصل الطلب على Awaiting Payment Status، وتقول الصفحة Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. وعندما تؤكد Omise الدفع أو ترفضه لاحقًا (عبر الـ webhook أو عودة العميل)، تُرسل الحالة الجديدة للطلب مع إشعار للعميل، فيرسلها OpenCart إليه بالبريد الإلكتروني. وإذا تعذّر تأكيد الدفع مباشرة بعد 3-D Secure، تعرض صفحة Payment confirmation الرسالة We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. مع زر Check again.

إذا رُفضت البطاقة، يبقى الطلب دون حالة. ويبقى العميل في خطوة Confirm Order مع Payment failed: وسبب، مثل عدم كفاية الرصيد، أو رمز أمان غير صحيح، أو رفض من مُصدِر البطاقة، ويمكنه المحاولة مجددًا بالسلة نفسها. وإذا فشل 3-D Secure، يعود العميل إلى صفحة الدفع مع السبب؛ وإذا انتهت صلاحية الخصم أو أُلغي في الأثناء، تكون الرسالة The payment was not completed. Please try again. وفي OpenCart 4 تظهر هذه الرسائل بعد 3-D Secure فوق صفحة الدفع.

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

يُبقي OpenCart 4 الطلب في الدفع حتى تُعرض صفحة النجاح. وإذا أُغلق ذلك الطلب في الأثناء (مثلًا لأن خصمه فشل أو انتهت صلاحيته، أو لأنك ألغيته أو استرددته)، يُعاد العميل إلى صفحة الدفع مع Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order.، ويدفع الطلب الجديد عند Confirm Order التالي. وإذا كان ذلك الطلب مدفوعًا بالفعل وصارت السلة تحتوي على منتجات أو كميات أخرى، يُعاد العميل إلى صفحة الدفع أيضًا، وتحصل السلة الجديدة على طلب جديد.

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

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

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

حالات الطلب

بدون حالة (طلب مفقود): العميل في خطوة 3-D Secure، أو رُفضت البطاقة. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

في OpenCart 4 قد يحصل طلب غير مدفوع في الدفع على الحالة Voided، وهي حالة يضبطها OpenCart 4 عندما يعود العميل إلى خطوة Confirm Order. وتتعامل الإضافة مع هذا الطلب كطلب بلا حالة، ولا يزال الدفع اللاحق يؤكده.

Order Status After Payment (الافتراضي Processing): تم تأكيد الدفع. وتعرض ملاحظة المبلغ وخصم Omise (chrg_...) وكيفية تأكيده (الدفع، أو العودة من 3-D Secure، أو webhook، أو إعادة محاولة الدفع، أو التحصيل اليدوي، أو المزامنة اليدوية).

Authorized Status (الافتراضي Pending): فُوضت البطاقة باستخدام Authorize only. استخدم Capture payment أو Void authorization.

Awaiting Payment Status (الافتراضي Pending): لم تؤكد Omise الدفع بعد. ويحدّث الـ webhook أو Sync payment status الطلب.

On Hold (Review) Status (الافتراضي Pending): يختلف مبلغ الخصم أو عملته عن الطلب، مثلًا لأن الطلب تغيّر أثناء 3-D Secure. وتعرض الملاحظة القيمتين. تحقق من الطلب ونفّذه أو استرد الدفعة.

Failed Status (الافتراضي Failed): فشل دفع معلّق لاحقًا. ولا يُخفَّض الطلب المدفوع أبدًا بسبب حدث فشل لاحق.

Canceled Status (الافتراضي Canceled): انتهت صلاحية الخصم أو أُلغي التفويض.

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

إذا وصل خصم مدفوع أو مفوَّض لطلب في حالة الإلغاء أو الاسترداد بالفعل، فلن يُعاد فتح الطلب. وتطلب منك ملاحظة واحدة التحقق من لوحة تحكم Omise واسترداد المبلغ أو إعادة فتح الطلب يدويًا.

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

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

في Sales > Orders، افتح طلبًا دُفع عبر Omise. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Omise Payment معرّف الخصم مع التسمية Test لمدفوعات الاختبار، وإجراء الدفع، وحالة الخصم، وعلامة البطاقة وآخر أرقامها، والمبالغ Charged / order / refunded، والأزرار، ونموذج الاسترداد، وسجل الاستردادات، وOmise notes الخاصة بالطلب. وتظهر علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة. وتتطلب الأزرار صلاحية تعديل الإضافة (وتُضبط في System > Users > User Groups) والمفتاح السري للوضع الذي تمت فيه عملية الدفع. وتظهر نتيجة كل إجراء في علامة التبويب.

Capture payment: يحصّل المبلغ المفوَّض بالكامل ويضبط الطلب على Order Status After Payment. ولا يظهر إلا للطلبات المفوَّضة.

Void authorization: يلغي التفويض؛ فلا يُحصَّل أي مبلغ ويُضبط الطلب على Canceled Status. ولا يظهر إلا للطلبات المفوَّضة.

Sync payment status: يعيد قراءة الخصم من Omise، مثلًا بعد تحصيل أو استرداد من لوحة تحكم Omise، ويحدّث الطلب ويضيف ملاحظة تتضمن حالة الخصم والإجمالي المسترد لدى Omise.

لا تُخطر تغييرات الحالة التي تُجرى من علامة التبويب العميل، ولا تحرّك المخزون، شأنها شأن تغيير الحالة اليدوي.

الاسترداد

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

لا تعيد المرتجعات في Sales > Returns الأموال عبر Omise. ولا تُسجَّل في OpenCart عمليات الاسترداد التي تتم من لوحة تحكم Omise؛ وSync payment status يعرض الإجمالي المسترد.

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

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

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

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

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

لا يظهر Omise في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاحين العام والسري للوضع الحالي مُدخلان (مفاتيح الاختبار في وضع الاختبار، والمفاتيح الفعلية في الحالات الأخرى)، وأن العميل يدفع بإحدى العملات المدعومة. وتعرض صفحة الإعدادات تحذيرًا عند غياب المفاتيح. وتحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت عملية الدفع لكن الطلب يبقى دون حالة أو في Awaiting Payment Status: الـ webhook لا يعمل. في لوحة تحكم Omise، تحقق من أن عنوان الـ webhook مطابق تمامًا للعنوان الظاهر في Webhook URL وأنه يستخدم HTTPS. وفي طلب موجود، انقر على Sync payment status. فعّل Debug log لرؤية ردود الـ webhook.

يرد الـ webhook بالرسالة Charge ID does not match order أو Order not found: الخصم الوارد في الحدث لم يُنشأ بواسطة هذا المتجر لذلك الطلب. لا يُغيَّر شيء.

يرد الـ webhook بالرسالة Order is being processed, retry later أو Failed to verify charge: السلة مقفلة من طلب آخر في اللحظة نفسها، أو لم يمكن الوصول إلى واجهة Omise البرمجية، أو المفتاح السري لوضع الدفع مفقود. وتعيد Omise محاولة الـ webhook.

يرد الـ webhook بالرسالة The order status could not be set, retry later: لم يمكن ضبط حالة الطلب في تلك اللحظة. وتعيد Omise محاولة الـ webhook. فعّل Debug log لمعرفة السبب.

يعرض عنوان الـ webhook الرسالة Method not allowed في المتصفح: هذا طبيعي. فالعنوان يقبل الطلبات الصادرة من Omise فقط.

تحذير عند الحفظ: key must start with ... أو must be a live key: لُصق مفتاح في الحقل الخطأ ولم يُحفظ. تبدأ مفاتيح الاختبار بـ pkey_test_ / skey_test_، وتبدأ المفاتيح الفعلية بـ pkey_ / skey_.

يرى العميل الرسالة Card payments are temporarily unavailable: المفاتيح غير صحيحة، أو أن رمز البطاقة ينتمي إلى الوضع الآخر (رمز اختبار في الوضع الفعلي أو العكس). تحقق من المفاتيح ومن Test mode.

يرى العميل الرسالة We could not reach the payment provider: لم يصل أي رد صالح من Omise عند إنشاء الخصم. ربما يكون الخصم قد أُنشئ مع ذلك؛ تحقق من لوحة تحكم Omise قبل أن يدفع العميل مرة أخرى.

يرى العميل الرسالة This order is already being paid: أُرسل الدفع مرتين في الوقت نفسه. ينتظر العميل لحظة ويراجع بريده الإلكتروني قبل المحاولة مجددًا.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في علامة التبويب VibeFox Omise Payment (انظر Order statuses)، ثم نفّذ الطلب أو استرد الدفعة.

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

يفشل الاسترداد الجزئي لطلب مفوَّض: الدفع مفوَّض فقط. حصّله أولًا، أو استرد المبلغ كاملًا لإلغائه.

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

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

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

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