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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 6.0 أو أحدث، مثبت ومفعّل. ترفض الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث، مع امتداد OpenSSL (يُستخدم لتشفير الطلب وفك تشفير الرد).

حساب CCAvenue: تحتاج إلى حساب تاجر لدى CCAvenue مع Merchant ID وAccess Code وWorking Key. تُصدر Access Code وWorking Key لنطاق موقع، لذا أنشئهما لنطاق هذا المتجر. تستخدم CCAvenue بيانات الاعتماد نفسها لبيئة الاختبار، ويجب أن تفعّل CCAvenue وصول الاختبار لحسابك. وتستخدم الإضافة نقاط الوصول الهندية لـ CCAvenue.

العملة: تُرسل عملة الطلب إلى CCAvenue كما هي. تقبل حسابات CCAvenue الروبية الهندية (INR) افتراضيًا، أما العملات الأخرى فتتطلب تفعيل المعالجة متعددة العملات في حسابك لدى CCAvenue.

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

التثبيت

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

2. انقر Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > CCAvenue > Manage، أو انقر Settings تحت اسم الإضافة في صفحة Plugins.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، وانقر Activate.

5. أدخل Merchant ID وAccess Code وWorking Key من لوحة تحكم CCAvenue، وفعّل Enable/Disable.

6. أبقِ Test mode مفعّلًا أثناء الاختبار، ثم ألغِ تحديده لاستقبال مدفوعات حقيقية.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > CCAvenue. تحذّرك الصفحة فوق الحقول عندما تكون CCAvenue مفعّلة لكن Merchant ID أو Access Code أو Working Key ناقص (فتبقى طريقة الدفع مخفية عند الدفع حتى تُضبط الثلاثة)، وتعرض CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken. ما دام وضع الاختبار مفعّلًا، وتذكّرك بالمعالجة متعددة العملات عندما لا تكون عملة المتجر INR.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: CCAvenue.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

بيانات اعتماد API

سجّل الدخول إلى لوحة تحكم CCAvenue للتجار (M.A.R.S.) وافتح Settings > API Keys. أنشئ Access Code وWorking Key لنطاق هذا المتجر. تُحذف المسافات من بيانات الاعتماد عند الحفظ.

Merchant ID: رقم Merchant ID الرقمي الخاص بك في CCAvenue. وإذا احتوى على غير الأرقام، تظهر رسالة خطأ عند الحفظ ويُحتفظ بالقيمة المحفوظة سابقًا.

Access Code: Access Code الخاص بهذا الموقع.

Working Key: Working Key (مفتاح التشفير) الخاص بهذا الموقع. يُشفّر طلب الدفع، وهو الوسيلة الوحيدة للتحقق من رد CCAvenue، فأبقِه سريًا.

Test mode: Send customers to the CCAvenue test environment (test.ccavenue.com). تستخدم CCAvenue Merchant ID وAccess Code وWorking Key نفسها للاختبار والإنتاج، ويجب أن تفعّل CCAvenue وصول الاختبار لحسابك. وفي وضع الاختبار تعرض صفحة الدفع TEST MODE: no real transactions will be processed. الافتراضي: مفعّل. ألغِ تحديده للمدفوعات الحقيقية.

عنوان العودة

تُعيد CCAvenue العميل إلى العنوان الظاهر في هذا القسم. ويبدو بالشكل https://your-site/wc-api/ccavenue_p_callback/. تُرسل الإضافة هذا العنوان مع كل دفعة، فلا يلزم أي إعداد في CCAvenue. ويجب أن ينتمي إلى النطاق المسجل لدى CCAvenue.

متقدم

Debug log: Log CCAvenue events يكتب معرّفات الطلبات ومراجع CCAvenue والحالات إلى WooCommerce > Status > Logs، والمصدر wcp_ccavenue_payment. ولا تُسجَّل المفاتيح وبيانات البطاقة والعناوين. الافتراضي: إيقاف.

Delete data on uninstall: Remove the plugin settings, logs and CCAvenue order references when the plugin is deleted. إلغاء تفعيل الإضافة لا يحذف أي شيء أبدًا. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا CCAvenue) ويقدّم الطلب. تعرض صفحة Pay for order الرسالة Thank you for your order. You are being redirected to CCAvenue to complete the payment. وتنقل العميل إلى صفحة الدفع في CCAvenue. وبدون JavaScript ينقر العميل Pay via CCAvenue أو Cancel order. تحصل كل محاولة على رقم مرجع جديد في CCAvenue. وتُرسل إجمالي الطلب وعملته، وتفاصيل الفوترة والتوصيل، ومفتاح الطلب ضمن الطلب المشفّر. وتُنظَّف الأسماء والعناوين لتتوافق مع الأحرف والأطوال التي تقبلها CCAvenue؛ وتُرسل الدولة والولاية بأسمائها، والهاتف أرقامًا فقط.

بعد الدفع تُعيد CCAvenue العميل برد مشفّر. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده CCAvenue: يجب أن يُفكّ الرد تشفيره بالـ Working Key الخاص بك، وأن ينتمي إلى هذا الطلب، وأن يحمل المبلغ والعملة نفسيهما للطلب. عندها ينتقل العميل إلى صفحة استلام الطلب.

إذا فشل الدفع، يعود العميل إلى صفحة الدفع مع Payment was not completed. Please try again or choose a different payment method. وإذا ألغى العميل في صفحة CCAvenue، فالرسالة Payment was cancelled. You may try again. وإذا تعذّر التحقق من الرد، فالرسالة We could not confirm the payment result. If your account was charged, please contact us before paying again. ويمكن للعميل دفع طلب غير مدفوع مرة أخرى، مثلًا من صفحة Pay for order. وإذا بدأ الدفع من صفحة Pay for order وكانت السلة فارغة، تعرض WooCommerce الرسالة في صفحة السلة؛ ويمكن دفع الطلب الفاشل مجددًا من My account > Orders.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS). والنصوص الموجهة للعملاء مترجمة إلى الهندية.

تُؤخذ النتيجة فقط من عودة العميل من CCAvenue: لا توجد إشعارات من خادم إلى خادم ولا طلبات حالة. وإذا أغلق العميل المتصفح قبل العودة، يبقى الطلب «بانتظار الدفع». ولا تتضمن الإضافة استردادات من WooCommerce، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا نموذج بطاقة داخل الموقع أو iframe، ولا دعم لـ CCAvenue UAE أو المنصات الإقليمية الأخرى.

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى CCAvenue ولم يعد بعد. تحقق من الدفعة في لوحة تحكم CCAvenue إذا لم يعد العميل.

Processing: تم تأكيد الدفع (تصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط «مكتمل»، وهذا هو الإعداد الافتراضي في WooCommerce). تعرض ملاحظة الطلب المرجع البنكي، ومعرّف تتبع CCAvenue، ووضع الدفع. ومعرّف معاملة الطلب هو معرّف تتبع CCAvenue.

On hold, amount/currency mismatch: أكدت CCAvenue دفعة يختلف مبلغها أو عملتها عن الطلب، مثلًا إذا عُدِّل الطلب بعد أن بدأ العميل الدفع أو طُبّق عرض خصم من CCAvenue. تعرض الملاحظة المبلغ المستلم والمتوقع. تحقق من الدفعة في لوحة تحكم CCAvenue، ثم أكمل الطلب أو استرده.

On hold, awaiting bank confirmation: أبلغت CCAvenue عن الدفعة بالحالة Awaited. لا يُعلَّم الطلب كفاشل أبدًا ما دام المبلغ قد يُحصَّل. تحقق منها في لوحة تحكم CCAvenue قبل التنفيذ، وغيّر الحالة يدويًا. ويُطبَّق أي رد لاحق برقم التتبع نفسه.

On hold, payment for a cancelled order: دفع العميل بعد إلغاء الطلب. تحقق من المخزون، ثم نفّذ الطلب أو استرده.

Cancelled: ألغى العميل الدفع في صفحة CCAvenue.

Failed: فشلت الدفعة، أو أعادت CCAvenue الحالة Invalid أو Timeout أو حالة غير ناجحة أخرى. تعرض الملاحظة رسالة CCAvenue. ولا يغيّر الفشل المتأخر أي طلب مدفوع أبدًا.

إذا وصلت دفعة ناجحة ثانية لطلب مدفوع بالفعل (مثلًا من تبويبين في المتصفح)، فلا يتغير الطلب مرة أخرى. وتطلب منك ملاحظة استرداد المكرر من لوحة تحكم CCAvenue.

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

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

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

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

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

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

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

CCAvenue لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن البيانات الثلاث مضبوطة: Merchant ID وAccess Code وWorking Key. تعرض صفحة الإعدادات تحذيرًا عند نقص أحدها.

تم الدفع لكن الطلب ما زال Pending payment: لم يعد العميل من CCAvenue إلى متجرك، مثلًا لأنه أغلق المتصفح. ولا توجد إشعارات من خادم إلى خادم في الإضافة. تحقق من الدفعة في لوحة تحكم CCAvenue وحدّث الطلب يدويًا.

تنتهي كل دفعة بالرسالة We could not confirm the payment result: لا يمكن فكّ تشفير الرد. الـ Working Key خاطئ، أو يخص نطاقًا آخر، أو نُسخ مع أحرف زائدة. أنشئ المفاتيح لنطاق هذا المتجر، والصقها من جديد. فعّل Debug log وراجع WooCommerce > Status > Logs، والمصدر wcp_ccavenue_payment.

تعرض CCAvenue خطأً قبل صفحة الدفع: تحقق من أن Access Code وWorking Key أُنشئا لهذا النطاق، وأن عنوان العودة ينتمي إلى النطاق المسجل لدى CCAvenue، وفي وضع الاختبار أن CCAvenue فعّلت وصول الاختبار لحسابك. وبالنسبة إلى عملة غير INR يجب تفعيل المعالجة متعددة العملات في حسابك لدى CCAvenue.

يرى العميل الرسالة This payment method is temporarily unavailable: إحدى بيانات الاعتماد ناقصة.

يرى العميل الرسالة Payment gateway error: encryption failed: تعذّر تشفير الطلب. تحقق من تثبيت امتداد OpenSSL في PHP.

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. كان المبلغ المدفوع أو عملته مختلفًا عن الطلب، أو الدفعة بانتظار تأكيد البنك، أو كان الطلب ملغى. تحقق من الدفعة في لوحة تحكم CCAvenue، ثم نفّذ الطلب أو استرد الدفعة.

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

للمطورين: يذكر ملف readme الفلتر ccavenue_p_request_params (لتغيير البيانات المرسلة إلى CCAvenue، مثل merchant_param2 إلى merchant_param5 أو promo_code؛ ولا تغيّر amount أو currency أو order_id أو merchant_param1)، والفلتر ccavenue_p_icon لأيقونة صفحة الدفع.

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

إلغاء تفعيل الإضافة يُبقي جميع البيانات. للإزالة، ألغِ التفعيل ثم احذفها من صفحة Plugins. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالته. أما إعدادات البوابة والسجلات ومراجع CCAvenue المحفوظة في الطلبات فتُحذف فقط إذا كان Delete data on uninstall مفعّلًا، وإلا فتبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات معاملاتها.

CCAvenue علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ CCAvenue ولا تحظى بمصادقتها.