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

المتطلبات

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

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

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

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

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

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

التثبيت

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

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox ECPay Payment Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت، تنشئ الوحدة حالتين للطلب: Awaiting ECPay payment وECPay payment on hold. يوفّر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences، ويجب أن تبقى TWD مسموحة للوحدة.

الإعدادات

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

ECPay (綠界)

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

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

Description: النص الذي يظهر أسفل وسيلة الدفع في صفحة الدفع. الافتراضي: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

حساب ECPay

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

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

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

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

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

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

Clear saved secrets: لإزالة Hash Key أو Hash IV، حدّد المربع الخاص به ثم انقر على Save. الحقل الفارغ يُبقي القيمة المحفوظة.

خيارات الدفع

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

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

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

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

ترسل ECPay نتائج المدفوعات إلى متجرك. يعرض هذا القسم Notification URL. مع الروابط الصديقة يبدو هكذا: https://your-shop/module/wcp_ecpay_payment_gateway/notify، وقد يتضمن رمز لغة مثل /en/. يُرسل الرابط مع كل دفعة، لذلك لا يلزم ضبط أي شيء في ECPay، لكن يجب أن يكون متاحًا من الإنترنت على المنفذ 80/443 دون جدار حماية أو مصادقة أساسية أمامه. ولا يمنعه وضع الصيانة في متجرك ولا قيود الدول.

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

متقدم

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

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

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

صفحة الدفع

في خطوة الدفع يختار العميل وسيلة الدفع (افتراضيًا ECPay (綠界)). وعند تفعيل عدة وسائل، يختار العميل أيضًا Credit Card أو ATM (Virtual Account) أو CVS (Convenience Store) أو Barcode ضمن Payment Method.

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

لا يُنشأ الطلب إلا بعد أن تؤكده ECPay بإشعار خادم موقَّع. عندما ينقر العميل على رابط العودة إلى المتجر في صفحة ECPay ويكون الطلب موجودًا، تُفتح صفحة تأكيد الطلب القياسية. وتعرض Your ECPay payment has been received. للطلب المدفوع، وYour ECPay payment was received and is being reviewed by the store. للطلب المعلَّق، وتعليمات الدفع لطلب ATM أو CVS أو الرمز الشريطي بانتظار الدفع. إذا لم يصل الإشعار بعد، تعرض صفحة Payment confirmation النص We have not received a payment confirmation from ECPay for this order yet. Your order will be created 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. وتبقى السلة محفوظة.

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

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

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

تقبل الوحدة المدفوعات لمرة واحدة فقط في صفحة ECPay. لا تتضمن استردادًا من PrestaShop، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات دورية أو مدفوعات مجدولة (定期定額)، ولا دفعًا بالتقسيط، ولا Apple Pay وTWQR وWeChat Pay وBNPL وWebATM والفواتير الإلكترونية والخدمات اللوجستية، ولا استعلامًا عن الحالة من جانب الخادم: إذا لم يتمكن متجرك من استلام الإشعار، تحقق من الدفع في لوحة تحكم ECPay.

الطلبات

حالات الطلب

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

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

Payment accepted: تم تأكيد الدفع. يُسجَّل الدفع مع رقم TradeNo الخاص بـ ECPay كمعرّف للمعاملة، وتعرض ملاحظة رقم TradeNo ونوع الدفع والمبلغ ورقم المعاملة (مع علامة وضع الاختبار للمدفوعات التجريبية).

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

Payment error: أبلغت ECPay بفشل آخر دفعة ATM أو CVS أو رمز شريطي لطلب بانتظار الدفع. تعرض الملاحظة رمز الإرجاع ورسالة ECPay.

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

كتلة الدفع في ECPay

تعرض صفحة الطلب كتلة ECPay payment تتضمن كل محاولات الدفع الخاصة بالطلب: رقم MerchantTradeNo مع شارة Test mode لمحاولات بيئة الاختبار، ووسيلة الدفع، والمبلغ بالدولار التايواني، والحالة، ورقم TradeNo في ECPay، ونوع الدفع والتاريخ، ورمز الإرجاع من ECPay. وتحتها ECPay notes الخاصة بالطلب. وبالنسبة إلى طلب في ECPay payment on hold، تذكّرك الكتلة بمقارنته مع لوحة تحكم ECPay.

الاستردادات

الاستردادات من PrestaShop غير متاحة. استرد الدفع في لوحة تحكم ECPay، ثم حدّث الطلب يدويًا في PrestaShop. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر ECPay.

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

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

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

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

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

لا يظهر ECPay في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن سلة العميل بالدولار التايواني، وأن Merchant ID وHash Key وHash IV مضبوطة في الوضع الحقيقي. تعرض صفحة الإعدادات رسالة في كل حالة من هذه الحالات. وفي Payment > Preferences تحقق من أن الوحدة مسموحة لـ TWD ولدولة العميل ولمجموعة العميل.

تم الدفع ولم يُنشأ أي طلب: لم يصل إشعار 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 لترى السبب.

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

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

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

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

للمطورين: يتيح الخطاف actionEcpayPRequestParams لوحدة أخرى تغيير المعاملات المرسلة إلى ECPay؛ ولا يمكن تغيير التاجر ورقم المعاملة والمبلغ عبره.

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

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

ECPay علامة تجارية مسجّلة لمالكها. هذه الوحدة غير تابعة لـ ECPay ولا معتمدة من قبلها.