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

المتطلبات

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

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

العملة: دولار تايواني جديد (TWD). تتقاضى ECPay المدفوعات بالدولار التايواني فقط، لذلك لا تظهر طريقة الدفع إلا عندما يُكمل العميل الشراء بالدولار التايواني. أضِف TWD بالرمز TWD من System > Localisation > Currencies إذا لم تكن موجودة في متجرك. تُرسل المبالغ بالدولار التايواني كأعداد صحيحة لأن ECPay لا تقبل الكسور العشرية: تُقرَّب إجماليات الطلبات إلى أقرب دولار. استخدم 0 خانة عشرية للدولار التايواني لتجنب التقريب.

حساب ECPay: للمدفوعات الفعلية تحتاج إلى MerchantID وHashKey وHashIV من حساب التاجر لديك في ECPay، وتجدها في لوحة تحكم التاجر لدى ECPay (vendor.ecpay.com.tw). لا يلزم حساب ECPay للاختبار.

الوصول إلى الموقع: يجب أن يكون متجرك متاحًا من الإنترنت عبر HTTP/HTTPS على المنفذ 80/443، حتى تتمكن ECPay من إرسال إشعارات الدفع. أي جدار ناري أو مصادقة أساسية أمام الموقع تمنع هذه الإشعارات.

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

التثبيت

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

OpenCart 3

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

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

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

4. فعّل Enable/Disable، واختر طرق الدفع، واترك Test Mode مفعّلًا في اختباراتك الأولى. انقر على Save.

5. للمدفوعات الفعلية أدخل Merchant ID وHash Key وHash IV (انظر الإعدادات)، وألغِ تفعيل Test Mode، ثم انقر على Save.

OpenCart 4

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

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

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

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

يبدأ التثبيت الجديد بطريقة الدفع معطلة ووضع الاختبار مفعّلًا. يُرسل عنوان URL للإشعارات مع كل عملية دفع، لذلك لا يلزم إعداد أي شيء في ECPay.

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox ECPay Payment Gateway > Edit. تُدرج الأقسام على اليسار؛ وزر Save أسفل القائمة يحفظ الصفحة كاملةً. وفوق الإعدادات تعرض الصفحة رسالة خطأ عندما لا تكون العملة الافتراضية لمتجرك هي TWD ولا توجد عملة TWD مفعّلة (عندئذٍ لا تظهر ECPay في الدفع)، أو تحذيرًا عندما تكون TWD عملة ثانية فقط (عندئذٍ تظهر ECPay فقط للعملاء الذين يدفعون بالدولار التايواني). وتعرض خطأً عندما يخلو وضع الإنتاج من MerchantID أو HashKey أو HashIV. وطالما كان وضع الاختبار مفعّلًا، تحذّر الصفحة من أن المدفوعات تُرسل إلى بيئة الاختبار (sandbox) الخاصة بـ ECPay مع التاجر العام للاختبار 3002607، وأنه لا يُحصَّل أي مال، وأن أي شخص يعرف مفاتيح sandbox العامة يمكنه تأكيد طلبات الاختبار؛ لذلك يجب إيقاف وضع الاختبار قبل قبول طلبات حقيقية. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

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

ECPay (綠界)

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

Title: اسم طريقة الدفع الذي يراه العملاء في الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: ECPay (綠界). مطلوب.

Description: النص الذي يُعرض للعميل في خطوة Confirm Order. الافتراضي: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

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

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

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

حساب ECPay

تجد MerchantID وHashKey وHashIV في لوحة تحكم التاجر لدى ECPay (vendor.ecpay.com.tw) ضمن System development management > System integration settings (系統開發管理 > 系統介接設定).

Test Mode: يرسل المدفوعات إلى بيئة sandbox الخاصة بـ ECPay (payment-stage.ecpay.com.tw) مع التاجر العام للاختبار 3002607. لا يُحصَّل أي مال حقيقي. تُستخدم بيانات الاعتماد أدناه فقط عندما يكون وضع الاختبار معطّلًا. الافتراضي: مفعّل. وطالما هو مفعّل يرى العملاء في خطوة Confirm Order الرسالة TEST MODE — ECPay sandbox, no real money is charged.

Merchant ID: معرّف التاجر لدى ECPay (وضع الإنتاج). يُتجاهل في وضع الاختبار.

Hash Key: مفتاح Hash لدى ECPay (وضع الإنتاج). يُتجاهل في وضع الاختبار.

Hash IV: متجه Hash لدى ECPay (وضع الإنتاج). يُتجاهل في وضع الاختبار.

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

خيارات الدفع

Enabled Payment Methods: طرق الدفع المعروضة على العملاء. عند وجود أكثر من واحدة يختار العميل في خطوة Confirm Order. تبقى طلبات ATM وCVS وBarcode في حالة الانتظار حتى يدفع العميل. يجب اختيار طريقة واحدة على الأقل؛ وإذا لم تُختر أي طريقة، فستُفعَّل Credit Card وتخبرك الصفحة بذلك. الافتراضي: Credit Card.

Default Payment Method: الطريقة المحددة مسبقًا. يجب أن تكون إحدى الطرق المفعّلة، وإلا فستُستخدم أول طريقة مفعّلة. الافتراضي: Credit Card.

Order Prefix: بادئة رقم المعاملة لدى ECPay (MerchantTradeNo)، حتى 5 أحرف أو أرقام. تُحذف الرموز الأخرى عند الحفظ مع رسالة. مفيدة عندما تتشارك عدة متاجر حسابًا واحدًا في ECPay: امنح كل متجر بادئته الخاصة. الافتراضي: EC.

إشعارات الدفع

ترسل ECPay نتائج المدفوعات وتفاصيل ATM وCVS والباركود إلى متجرك. يعرض هذا القسم Notification URL. وهو بالشكل التالي في OpenCart 3: https://your-store/index.php?route=extension/payment/wcp_ecpay_payment_gateway/notify، وفي OpenCart 4: https://your-store/index.php?route=extension/wcp_ecpay_payment_gateway/payment/wcp_ecpay_payment_gateway.notify. يُرسل هذا العنوان مع كل دفعة، لذلك لا يلزم إعداد شيء في ECPay، لكن يجب أن يكون متاحًا من الإنترنت على المنفذ 80/443 دون جدار ناري أو مصادقة أساسية أمامه. ولا يمنعه وضع الصيانة.

يُتحقق من كل إشعار بتوقيع CheckMacValue باستخدام مفاتيح البيئة (الاختبار أو الإنتاج) التي بدأت فيها عملية الدفع، وبمعرّف التاجر MerchantID لتلك العملية. تُرفض الإشعارات التي لا تحمل توقيعًا صحيحًا، وتعيد ECPay إرسالها. وبدون الإشعار لا يحصل الطلب على أي حالة؛ تحقّق من الدفعة في لوحة تحكم التاجر لدى ECPay.

الطلبات

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

Payment accepted: الحالة عندما تؤكد ECPay الدفع بالمبلغ المتوقع. الافتراضي: Processing.

Awaiting ECPay payment: الحالة عندما يستلم العميل حسابًا افتراضيًا لـ ATM أو رمز دفع CVS أو باركودات ويدفع لاحقًا عند الصراف الآلي أو في المتجر. الافتراضي: Pending.

ECPay payment on hold: الحالة عندما تُبلغ ECPay عن مبلغ أو عملة مختلفة، أو عندما تصل دفعة من بيئة sandbox في وضع الإنتاج، أو عندما تصل الدفعة بعد تغيير حالة الطلب (مثل إلغائه). تشرح ملاحظة الطلب السبب. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة من System > Localisation > Order Statuses واختيارها هنا.

Payment error: الحالة عندما يفشل آخر دفع عبر ATM أو CVS أو الباركود لطلب في الانتظار. الافتراضي: Failed.

متقدم

Enable Logging: يكتب أرقام الطلبات وأرقام المعاملات والمبالغ وأكواد الرد من ECPay في الملف ecpay_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى ecpay_p_debug.old.log.php. لا تُسجَّل أي مفاتيح أو بيانات عملاء. تُسجَّل الأخطاء دائمًا حتى عندما يكون هذا المفتاح معطّلًا. الافتراضي: معطّل.

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

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

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

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

Import: الصق ملف JSON المُصدَّر سابقًا وانقر على Import لاستعادة الإعدادات. يُحتفظ بقيم Hash Key وHash IV المحفوظة.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا ECPay (綠界)). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the ECPay payment page to complete the payment. وعند تفعيل عدة طرق يختار العميل أيضًا Credit Card أو ATM (Virtual Account) أو CVS (Convenience Store) أو Barcode ضمن Payment Method. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع؛ ويظهر اختيار طريقة ECPay فوق هذا الزر.

عندما ينقر العميل على Confirm Order تعرض الصفحة Redirecting to ECPay for payment. Please wait... وتنقل العميل إلى صفحة دفع ECPay. يُرسل إجمالي الطلب بالدولار التايواني كأعداد صحيحة مع أسماء المنتجات وكمياتها. تُفتح صفحة ECPay بالصينية التقليدية للغتين التايوانية والهونغ كونغية، وبالصينية المبسطة أو الكورية أو اليابانية لتلك اللغات، وبالإنجليزية لجميع اللغات الأخرى، وذلك بحسب لغة متجر العميل.

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد ECPay الدفع بإشعار موقَّع من الخادم. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون. وعندما ينقر العميل على رابط العودة إلى المتجر في صفحة ECPay، وكان للطلب حالة بالفعل، تفتح صفحة نجاح الطلب في OpenCart. تعرض Your ECPay payment has been received. للطلب المدفوع، وYour ECPay payment was received and is being reviewed by the store. للطلب المعلّق، وتعليمات الدفع للطلب المنتظر عبر ATM أو CVS أو Barcode. وإذا لم يصل الإشعار بعد، تعرض صفحة Payment confirmation الرسالة We have not received a payment confirmation from ECPay for this order yet. Your order will be confirmed as soon as ECPay confirms the payment. مع الزرين Check again وBack to checkout. وإذا أبلغت ECPay بفشل الدفع، يعود العميل إلى صفحة الدفع مع الرسالة The payment was not completed. You can try again or choose another payment method. ويبقى السلة محفوظة. وفي OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع.

بالنسبة إلى ATM وCVS وBarcode يستلم العميل تفاصيل الدفع أولًا. يحصل الطلب على الحالة Awaiting ECPay payment، وتُعرض رمز البنك والحساب الافتراضي، أو رمز الدفع في المتجر المريح، أو الباركودات، والمبلغ وتاريخ Pay before ضمن ECPay payment instructions في صفحة نجاح الطلب، وبالنسبة إلى العميل المسجَّل دخوله تظهر أيضًا في معلومات الطلب ضمن حسابه. وعندما يدفع العميل ترسل ECPay إشعارًا آخر ويُعلَّم الطلب كمدفوع. لا تُضاف تعليمات الدفع إلى رسائل OpenCart الإلكترونية.

كل محاولة تُنشئ رقم معاملة جديدًا لدى ECPay، لأنها ترفض الأرقام المعاد استخدامها. لذلك تعمل إعادة المحاولة بعد فشل الدفع، وإذا عاد العميل إلى الخلف في المتصفح ونقر على Confirm Order مرة أخرى بدأت محاولة جديدة. يمكن أن تحتوي السلة على 30 محاولة دفع كحد أقصى. وينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، بينما يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، فتكون المحاولة الجديدة برقم معاملة جديد للطلب نفسه؛ وعندما يكون طلب آخر من السلة نفسها مدفوعًا بالفعل أو ينتظر دفع ATM أو CVS، ينتقل العميل إلى صفحة النجاح، ولا تبدأ أي عملية دفع جديدة.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا فشلت دفعة ATM أو CVS الخاصة به أو ألغيته)، فإن العميل يُعاد إلى صفحة الدفع مع الرسالة Your previous order was cancelled or its payment failed. Please confirm the order again.، وتؤدي النقرة التالية على Confirm Order إلى دفع طلب جديد للسلة. وإذا كان الطلب مدفوعًا بالفعل (أو ينتظر دفع ATM أو المتجر المريح)، لكن السلة تغيّرت منذ ذلك (بما في ذلك كمية جديدة)، فالرسالة هي Your previous order is already paid (or awaits its ATM / convenience store payment). Please confirm the order again: the cart will be paid with a new order. ولا يظهر الطلب المدفوع أبدًا كمدفوع لسلة مختلفة.

إذا تعذر بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل The order total is too small for ECPay. عندما يكون الإجمالي أقل من 1 TWD بعد التقريب. تُتحقق حدود المبالغ الخاصة بـ ECPay لكل طريقة في صفحة ECPay، لا عند الدفع.

تُقبل إشعارات المدفوعات التي بدأت بالفعل حتى إذا عطّلت طريقة الدفع، ويستمر العميل في رؤية تعليمات الدفع للطلبات التي قدّمها.

تقبل الإضافة المدفوعات لمرة واحدة فقط في صفحة ECPay. ولا توجد استردادات من OpenCart، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات دورية (定期定額)، ولا تقسيط، ولا Apple Pay، ولا فواتير إلكترونية أو خدمات لوجستية، ولا استعلام عن الحالة من جهة الخادم: إذا لم يتمكن متجرك من استلام الإشعار، فتحقّق من الدفعة في لوحة تحكم التاجر لدى ECPay.

الطلبات

حالات الطلب

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

Awaiting ECPay payment (default Pending): اختار العميل ATM أو CVS أو Barcode واستلم تفاصيل الدفع. تعرض الملاحظة رمز البنك والحساب الافتراضي، ورمز الدفع أو الباركودات، والمهلة النهائية.

Payment accepted (default Processing): تم تأكيد الدفع. تعرض ملاحظة رقم ECPay TradeNo ونوع الدفع والمبلغ ورقم المعاملة (مع علامة وضع الاختبار لمدفوعات sandbox).

ECPay payment on hold (default Pending): أبلغت ECPay عن مبلغ أو عملة تختلف عن الطلب (على سبيل المثال، عُدِّلت السلة في علامة تبويب أخرى بعد بدء الدفع)، أو وصلت دفعة sandbox بعد تحويلك إلى وضع الإنتاج (لم يُحصَّل أي مال حقيقي)، أو وصلت الدفعة بعد أن غيّرت حالة الطلب، مثل إلغائه. تشرح الملاحظة ذلك. قارِن مع لوحة تحكم ECPay، ثم أكمل الطلب أو استرد الدفعة هناك.

Payment error (default Failed): أبلغت ECPay أن آخر دفعة عبر ATM أو CVS أو الباركود لطلب في الانتظار قد فشلت. تعرض الملاحظة رمز الرد ورسالة ECPay.

تُتجاهل الإشعارات المكررة. لا يُعاد فتح الطلب المدفوع بسبب فشل متأخر. تُسجَّل الدفعة الثانية لطلب مدفوع بالفعل، مثلًا من علامتي تبويب في المتصفح، ملاحظةً واحدة فقط، حتى تتمكن من استردادها في لوحة تحكم ECPay. والمدفوعات التجريبية التي تُبدأ من لوحة تحكم ECPay تُدوَّن كملاحظات فقط ولا تُعلِّم الطلب أبدًا كمدفوع، لأن ECPay لا تحصّل أي مال عنها.

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

تبويب VibeFox ECPay Payment Gateway

في Sales > Orders افتح طلبًا دُفع عبر ECPay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox ECPay Payment Gateway كل محاولة دفع للطلب: رقم MerchantTradeNo مع تسمية Test mode لمحاولات sandbox، وطريقة الدفع، والمبلغ بالدولار التايواني، والحالة، ورقم TradeNo لدى ECPay، ونوع الدفعة وتاريخها، وكود الرد من ECPay، وتاريخ البدء. وتحتها ECPay notes الخاصة بالطلب. وبالنسبة إلى طلب في حالة التعليق، يذكّرك التبويب بمطابقته مع لوحة تحكم ECPay. التبويب للقراءة فقط ويظهر للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

لا تتوفر الاستردادات من OpenCart. استرد الدفعة في لوحة تحكم ECPay، ثم حدّث حالة الطلب في OpenCart يدويًا. ولا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر ECPay.

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

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

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

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

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

لا تظهر ECPay في الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن العميل يدفع بالدولار التايواني، وأنه في وضع الإنتاج تكون Merchant ID وHash Key وHash IV مضبوطة. تعرض صفحة الإعدادات رسالة تتعلق بالعملة وبيانات اعتماد الإنتاج. وتحقّق أيضًا من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمت عملية الدفع لكن الطلب بقي بدون حالة: لم يصل إشعار ECPay إلى متجرك (الموقع متوقف، أو جدار ناري، أو مصادقة أساسية). تعيد ECPay المحاولة عدة مرات. ويمكنك أيضًا التحقق من المعاملة في لوحة تحكم ECPay. فعّل Enable Logging لرؤية الإشعارات التي استلمتها الإضافة؛ وتُسجَّل الإشعارات المرفوضة كأخطاء في كل الأحوال.

يرد الإشعار بـ 0|CheckMacValue verification failed: إما أن Hash Key أو Hash IV لا يطابق حسابك في ECPay، أو أن الدفع بدأ في البيئة الأخرى. انسخهما مجددًا من لوحة تحكم ECPay.

يرد الإشعار بـ 0|MerchantID mismatch: الإشعار يخص تاجرًا آخر لدى ECPay غير التاجر الذي بدأ به الدفع.

يرد الإشعار بـ 0|Order not found: رقم المعاملة لم تُصدره هذه المتجر، مثلًا عندما تتشارك عدة متاجر حسابًا واحدًا في ECPay. امنح كل متجر Order Prefix خاصًا به.

يرد الإشعار بـ 0|Retry: كان الطلب يُعالج بإشعار آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. ستعيد ECPay إرسال الإشعار. فعّل Enable Logging لرؤية السبب.

يعرض عنوان URL للإشعار 0|Method not allowed in the browser: هذا طبيعي. لا يقبل العنوان إلا الطلبات الصادرة من ECPay.

يرى العميل This payment method is not available. Please reload the checkout page.: جلسة الدفع لم تعد تطابق الطلب، أو عُطّلت طريقة الدفع في الأثناء. على العميل إعادة تحميل صفحة الدفع.

يرى العميل The order total is too small for ECPay.: إجمالي الطلب أقل من 1 TWD بعد التقريب، ولا يمكن دفعه عبر ECPay.

يرى العميل Too many payment attempts for this order: بلغت السلة 30 محاولة دفع. اطلب من العميل بدء سلة جديدة.

الطلب في حالة التعليق: اقرأ الملاحظات في تبويب VibeFox ECPay Payment Gateway (انظر حالات الطلب)، وقارنها بلوحة تحكم ECPay، ثم أكمل الطلب أو استرد الدفعة هناك.

للمطورين: قبل إرسال نموذج الدفع إلى ECPay، تُطلق الإضافة حدث OpenCart باسم ecpay_p_request_params مع المعاملات والطلب؛ ولا يمكن تغيير التاجر ورقم المعاملة والمبلغ من خلاله.

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

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

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

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