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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، ومثبَّت وفعَّال.

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. اضغط Activate. يجب أن تكون WooCommerce فعَّالة.

3. افتح الإعدادات: WooCommerce > Settings > Payments > ECPay (綠界) > Manage، أو اضغط Settings تحت اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص في أعلى الصفحة واضغط Activate.

5. فعِّل Enable/Disable، واختر وسائل الدفع، واترك Test Mode مفعَّلًا لاختباراتك الأولى. في بيئة الاختبار يمكنك الدفع ببطاقة اختبار ECPay 4311-9522-2222-2222 (أي تاريخ انتهاء مستقبلي، ورمز CVV 222، ورمز 3-D Secure من صفحة بيئة الاختبار).

6. للمدفوعات الحقيقية أدخل MerchantID وHashKey وHashIV (انظر الإعدادات) وأزل التفعيل عن Test Mode.

الإعدادات

تقع جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > ECPay (綠界). تعرض الصفحة أعلى الحقول خطأً عندما لا تكون عملة المتجر TWD (ولا تظهر ECPay عندئذ عند الدفع)، وعندما لا يتضمن الوضع الحقيقي MerchantID وHashKey وHashIV. وما دام وضع الاختبار مفعَّلًا، تحذِّر الصفحة من أن المدفوعات تذهب إلى بيئة اختبار ECPay مع التاجر العام للاختبار 3002607، وأنه لا يُحصَّل أي مال، وأن أي شخص يعرف مفاتيح بيئة الاختبار العامة يمكنه تأكيد طلبات اختبار، لذا يجب تعطيل وضع الاختبار قبل قبول الطلبات الحقيقية.

عام

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: يُرسل Enable sandbox/test mode المدفوعات إلى بيئة اختبار ECPay (payment-stage.ecpay.com.tw) مع التاجر العام للاختبار من ECPay رقم 3002607. لا مال حقيقي. تُستخدم بيانات الاعتماد أدناه فقط عندما يكون وضع الاختبار معطَّلًا. الافتراضي: مفعَّل.

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

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

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

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

خيارات الدفع

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

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

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

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

تُرسل ECPay نتائج الدفع إلى متجرك. يعرض هذا القسم رابط الإشعار. يبدو هكذا: https://your-site/wc-api/ecpay_p_callback/. يُرسَل هذا الرابط مع كل عملية دفع، فلا حاجة لتهيئة شيء في ECPay، لكن يجب أن يكون قابلًا للوصول من الإنترنت على المنفذ 80/443 دون وضع صيانة أو جدار حماية أو مصادقة أساسية أمامه.

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

متقدم

Enable Logging: يكتب Log payment events and API calls معرِّفات الطلبات وأرقام المعاملات والمبالغ ورموز الإرجاع من ECPay إلى WooCommerce > Status > Logs، المصدر wcp_ecpay_payment_gateway. لا تُسجَّل أي مفاتيح أو بيانات عميل. الافتراضي: معطَّل.

Delete Data on Uninstall: Delete all plugin data when uninstalling. يزيل جميع إعدادات هذه الإضافة وسجلاتها وبيانات التعريف الخاصة بالطلبات. الافتراضي: معطَّل.

الدفع

يختار العميل وسيلة الدفع (الافتراضي هو ECPay (綠界)). ومع تفعيل عدة وسائل، يختار العميل أيضًا Credit Card أو ATM (Virtual Account) أو CVS (Convenience Store) أو Barcode. وما دام وضع الاختبار مفعَّلًا، تعرض وسيلة الدفع TEST MODE — ECPay sandbox, no real money is charged.

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

لا يُعلَّم الطلب كمدفوع إلا عندما تؤكده ECPay بإشعار خادم موقَّع. وإذا رجع العميل إلى صفحة استلام الطلب قبل وصول التأكيد، تعرض الصفحة We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: مع زر Pay.

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

تُنشئ كل زيارة لصفحة الدفع رقم معاملة جديدًا من ECPay، لأن ECPay ترفض الأرقام المعاد استخدامها. وهكذا تعمل صفحة Pay for order وإعادة المحاولة بعد فشل الدفع، وتُطابَق الإشعارات الخاصة بأي من هذه الأرقام مع الطلب. ويمكن أن يصل الطلب إلى 30 محاولة دفع كحد أقصى.

تُفحَص حدود المبالغ الخاصة بـ ECPay لكل وسيلة، مثل مدفوعات المتاجر القريبة، في صفحة ECPay، لا عند الدفع.

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

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

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى ECPay ولم يدفع بعد، أو لم يصل الإشعار بعد.

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

Processing: تأكَّد الدفع (الحالة الافتراضية في WooCommerce؛ وتصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط «مكتملة»). تعرض ملاحظة الطلب TradeNo من ECPay، ونوع الدفع، والمبلغ، ورقم المعاملة. ومعرِّف المعاملة هو TradeNo من ECPay.

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

Failed: أفادت ECPay بأن آخر محاولة دفع فشلت. تعرض الملاحظة رمز الإرجاع من ECPay ورسالته. ويمكن للعميل المحاولة مرة أخرى.

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

الاستردادات

الاستردادات من WooCommerce غير متاحة. استرد الدفع في لوحة تحكم ECPay، ثم سجِّل الاسترداد يدويًا في WooCommerce.

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

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

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

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

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

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

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

تم الدفع، لكن الطلب يبقى في حالة «في انتظار الدفع»: لم يصل إشعار 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 خاصًا به.

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

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

الطلب في حالة «قيد الانتظار» بعد دفع من بيئة الاختبار: تم الدفع في وضع الاختبار، لكن المتجر الآن في الوضع الحقيقي. لم يُحصَّل مال حقيقي. تحقق من الطلب يدويًا.

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

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

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

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

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