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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

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

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting CCAvenue payment وCCAvenue payment on hold. وتفعّل PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء. ويمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox CCAvenue Payment > Configure. لكل قسم زر Save الخاص به، ويحفظ الصفحة كاملة. وفوق الحقول تنبهك الصفحة عندما تكون 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.

CCAvenue

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. إذا احتوى على أي شيء غير الأرقام، تظهر عند الحفظ رسالة CCAvenue: the Merchant ID must contain digits only — the previous value was kept.، ويبقى القيمة المحفوظة سابقًا كما هي، وتُحفظ بقية الإعدادات.

Access Code: Access Code لهذا الموقع (Settings > API Keys).

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

Clear saved Working Key: حدّد المربع وانقر على Save لحذف Working Key المحفوظ. الحقل الفارغ يُبقي القيمة المحفوظة.

Test mode: يرسل العملاء إلى بيئة اختبار CCAvenue (test.ccavenue.com). تستخدم CCAvenue Merchant ID وAccess Code وWorking Key نفسها للاختبار والإنتاج؛ ويجب أن تفعّل CCAvenue وصول الاختبار لحسابك. وفي وضع الاختبار تعرض صفحة الدفع أسفل طريقة الدفع TEST MODE: no real transactions will be processed. الافتراضي: مفعّل. أوقفه للمدفوعات الحقيقية.

Return URL

تعيد CCAvenue العميل إلى العنوان المعروض في هذا القسم. وعند استخدام روابط صديقة لمحركات البحث يكون شكله https://your-shop/module/wcp_ccavenue_payment/return، وقد يتضمن رمز لغة مثل /en/. ترسل الوحدة هذا الرابط مع كل دفعة (كرابط إعادة توجيه وإلغاء)، فلا يلزم إعداد أي شيء في CCAvenue. ويجب أن ينتمي إلى النطاق المسجّل لدى CCAvenue.

متقدم

Debug log: يكتب أحداث CCAvenue في الملف logs/ccavenue_p_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح هذا الملف من الويب. لا يُسجَّل إلا مراجع الطلبات وأرقام التتبع والحالات؛ ولا تُسجَّل المفاتيح وبيانات البطاقة وعناوين البريد الإلكتروني والعناوين. الافتراضي: إيقاف. وطالما هو متوقف لا يُكتب أي شيء، بما في ذلك الأخطاء.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات الوحدة والسجل ومراجع طلبات CCAvenue. أما الطلبات وحالات الطلب الخاصة بالوحدة فتبقى. الافتراضي: إيقاف.

صفحة الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا CCAvenue) ويؤكد. تعرض الصفحة Thank you for your order. You are being redirected to CCAvenue to complete the payment. وترسل العميل إلى صفحة الدفع في CCAvenue. وبدون JavaScript ينقر العميل على Pay via CCAvenue أو Back to checkout. ولا يوجد طلب في هذه المرحلة.

تحصل كل محاولة على رقم مرجع طلب CCAvenue جديد يتكوّن من رقم السلة والوقت. ويُرسل إجمالي السلة وعملتها، وبيانات الفوترة، وعنوان التوصيل (عندما يختلف عن عنوان الفوترة)، ورمز سري للمحاولة، ضمن الطلب المشفّر. وتُنظَّف الأسماء والعناوين لتتوافق مع الأحرف والأطوال التي تقبلها CCAvenue؛ ويُرسل البلد والولاية بالأسماء، والهاتف بالأرقام فقط. ويختار العميل البطاقة أو Net Banking أو UPI أو المحفظة أو EMI في صفحة CCAvenue.

بعد الدفع تعيد CCAvenue العميل برد مشفّر. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده CCAvenue: يجب أن يُفكّ تشفير الرد بالمفتاح Working Key الخاص بك، وأن ينتمي إلى محاولة من هذا المتجر، وأن يحمل المبلغ والعملة نفسيهما المُرسلين وإجمالي السلة. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your CCAvenue payment has been received. وفي دفعة Awaited تعرض الصفحة Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. وبعد عدم تطابق المبلغ أو العملة تعرض Your payment was received and is being reviewed by the shop. وإذا أُلغي طلب معلّق لاحقًا أو فشل دون دفع، تعرض صفحة التأكيد Your CCAvenue payment was not completed. Please contact us about this order.

إذا فشل الدفع يعود العميل إلى صفحة الدفع مع الرسالة 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. وفي هذه الحالات لا يُنشأ أي طلب وتُحفظ السلة، فيستطيع العميل الدفع مجددًا. وإذا كان للسلة طلب موجود، تنتقل المحاولة الجديدة مباشرة إلى صفحة تأكيد ذلك الطلب بدلًا من دفعة ثانية.

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

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى CCAvenue ولم يعد، أو فشل الدفع أو أُلغي. لا توجد إلا السلة. تحقّق من الدفعة في لوحة تحكم CCAvenue إذا لم يعد العميل.

Payment accepted: تم تأكيد الدفع. تُسجَّل الدفعة برقم التتبع لدى CCAvenue كرقم للمعاملة، وتعرض ملاحظة المرجع المصرفي ورقم التتبع وطريقة الدفع.

Awaiting CCAvenue payment: أبلغت CCAvenue أن الدفعة بالحالة Awaited (لم يؤكدها البنك بعد). ولا يُعلَّم الطلب أبدًا كفاشل طالما أن المبلغ قد يُحصَّل. تحقّق منه في لوحة تحكم CCAvenue قبل تنفيذ الطلب. ولا يزال الرد اللاحق برقم التتبع نفسه يُطبَّق: تعيّن Success الحالة Payment accepted، وتعيّن Failure الحالة Payment error، وتعيّن Aborted الحالة Canceled.

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

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

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

تعرض صفحة الطلب كتلة CCAvenue payment تتضمن رقم طلب CCAvenue ورقم التتبع والحالة والمرجع المصرفي وطريقة الدفع واسم البطاقة والمبلغ المُرسل والمبلغ المُستلم والتاريخ ورسالة CCAvenue، كما تعرض شارة Test mode لدفعات الاختبار. وملاحظات CCAvenue رسائل خاصة بالطلب، ولا تظهر إلا في لوحة الإدارة.

الاسترداد

لا يُدعم الاسترداد من PrestaShop. استرد الدفعة من لوحة تحكم CCAvenue، ثم سجّل الاسترداد يدويًا في PrestaShop.

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

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

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

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

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

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

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

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

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

يرى العميل الرسالة This payment method is temporarily unavailable: أحد بيانات الاعتماد مفقود، أو إجمالي السلة صفر. يعرض Debug log السبب.

يرى العميل الرسالة This payment method is not available: الوحدة متوقفة، أو غير مسموح بها لعملة السلة أو البلد أو مجموعة العميل في Payment > Preferences.

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

لا يتغيّر Merchant ID عند الحفظ: القيمة تحتوي على شيء غير الأرقام. أدخل أرقام Merchant ID فقط.

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

للمطوّرين، تتضمن الوحدة الخطاف actionCcavenueRequestParams (لتغيير البيانات المرسلة إلى CCAvenue قبل التشفير، مثل merchant_param2 إلى merchant_param5؛ ويجب ألا تحتوي القيم على &؛ ولا تغيّر amount أو currency أو order_id أو merchant_param1).

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

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

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