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

المتطلبات

OpenCart: ‏3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 أو أحدث (تم الاختبار على 4.1.0.3).

PHP: ‏8.0 أو أحدث.

HTTPS: يُرسل Cashfree الـ webhooks إلى عناوين https:// فقط. بدون HTTPS تُؤكَّد المدفوعات عندما يعود العميل إلى المتجر، لكن فعّل HTTPS قبل الانتقال إلى البيئة الفعلية.

حساب Cashfree: تحتاج إلى App ID وSecret Key لحساب Cashfree الخاص بك، بشكل منفصل لبيئة الاختبار (sandbox) وبيئة الإنتاج، وإلى webhook في Merchant Dashboard الخاصة بـ Cashfree (راجع الإعدادات). يُستخدم Secret Key أيضًا للتحقق من الـ webhooks، لذلك لا يوجد سر منفصل للـ webhook. يجب تفعيل عملة الطلب في حساب Cashfree الخاص بك.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل Sandbox App ID وSandbox Secret Key، وأضف الـ webhook في Merchant Dashboard الخاصة بـ Cashfree (راجع الإعدادات)، وفعّل Enable/Disable، ثم انقر على Save وجرّب دفعة.

5. عند الجاهزية، أدخل App ID وSecret Key الفعليين، وعطّل Sandbox Mode، ثم انقر على Save.

OpenCart 4

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

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

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

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

يبدأ التثبيت الجديد بطريقة الدفع معطّلة ووضع sandbox مفعّلًا.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Cashfree Payments > Edit. تُعرض الأقسام في القائمة على اليسار؛ وزر Save الموجود أسفل القائمة يحفظ الصفحة بأكملها. وفوق الإعدادات توضح الصفحة أن الطلب لا يحصل على حالة إلا بعد أن يؤكد Cashfree الدفع. وعندما تكون طريقة الدفع مفعّلة، تحذّرك الصفحة إذا كانت مفاتيح API الخاصة بالوضع المحدد مفقودة (وفي هذه الحالة تكون طريقة الدفع مخفية في صفحة الدفع)، وتعرض Sandbox mode is on: customers see a test checkout and no real money is charged. طالما كان وضع sandbox مفعّلًا. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

Cashfree Payments

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Cashfree Payments. مطلوب.

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

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

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

Total: إجمالي صفحة الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض Cashfree. اتركه فارغًا لعرض Cashfree مهما كان الإجمالي. لا يُعرض أبدًا أي مبلغ أقل من الحد الأدنى لـ Cashfree لتلك العملة (وحدة واحدة؛ أو 0.01 أو 0.1 للعملات ذات ثلاث منازل عشرية).

الوضع ومفاتيح API

احصل على App ID وSecret Key من Merchant Dashboard الخاصة بـ Cashfree، ضمن Developers > API Keys (تتضمن الصفحة روابط إلى هناك). مفاتيح الاختبار ومفاتيح الإنتاج مختلفة.

Sandbox Mode: يستخدم sandbox الخاص بـ Cashfree للاختبار. لا يُخصم أي مبلغ حقيقي، وتعرض خطوة Confirm Order وصفحة الدفع SANDBOX MODE - no real payments will be processed. الافتراضي: مفعّل. عطّله للمدفوعات الفعلية.

Sandbox App ID: App ID لبيئة الاختبار الخاصة بك في Cashfree.

Sandbox Secret Key: Secret Key لبيئة الاختبار الخاصة بك في Cashfree.

App ID: App ID لبيئة الإنتاج الخاصة بك في Cashfree.

Secret Key: Secret Key لبيئة الإنتاج الخاصة بك في Cashfree.

لا تُعرض مفاتيح Secret Key المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض محفوظة — اتركه فارغًا للاحتفاظ بها. أدخل قيمة جديدة فقط إذا أردت تغييرها. لحذف مفتاح محفوظ، ضع علامة على Clear the saved value on save أسفل الحقل، ثم انقر على Save.

تحتفظ المدفوعات ببيئة إنشائها. يُتحقق من الـ webhooks الخاصة بها، وتُفحص حالتها، وتُرسل عمليات استردادها بمفاتيح تلك البيئة، لذلك أبقِ مفاتيح sandbox مملوءة حتى تُسوّى مدفوعات sandbox بعد التحويل إلى الإنتاج.

Webhook

يخبر الـ webhook متجرك بأن دفعة قد تمت أو فشلت أو استُردت. في Merchant Dashboard الخاصة بـ Cashfree انتقل إلى Developers > Webhooks وأضف العنوان المعروض في Webhook URL في هذا القسم، مع حدثي Payment وRefund. يبدو على OpenCart 3 هكذا: https://your-store/index.php?route=extension/payment/wcp_cashfree_payment/webhook، وعلى OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_cashfree_payment/payment/wcp_cashfree_payment.webhook. ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك. انسخ العنوان تمامًا كما تعرضه الإعدادات. في متجر يستخدم HTTPS تمرّر الإضافة هذا العنوان أيضًا إلى Cashfree مع كل دفعة. إذا كان متجرك لا يستخدم HTTPS، يعرض هذا القسم تحذيرًا.

تتعامل الإضافة مع هذه الأحداث (وهي مدرجة أيضًا في هذا القسم):

يوقّع Cashfree كل webhook بمفتاح Secret Key الخاص بك. تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. يجب توقيع الـ webhook بمفتاح Secret Key للبيئة التي تمت فيها الدفعة، لذلك لا يؤكد مفتاح sandbox أبدًا دفعة فعلية. تُقرّ الـ webhooks الموقّعة للمدفوعات التي لم يبدأها هذا المتجر (مثل متجر آخر على الحساب نفسه في Cashfree) وتُتجاهل. بدون الـ webhook لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع. وإذا أغلق العميل المتصفح بعد الدفع، فلن يتمكن إلا الـ webhook (أو محاولة الدفع التالية للسلة نفسها) من تأكيد الطلب.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تؤكد Cashfree الدفع. تترك الدفعة الفاشلة أو المهجورة الطلب بدون حالة، وتُحفظ السلة. تعرض كل خانة أدناه حالات طلبات OpenCart الخاصة بك.

Order Status After Payment: الحالة التي تُعيَّن بعد تأكيد الدفع وتطابق المبلغ والعملة. الافتراضي: قيد المعالجة.

On Hold (Review) Status: أبلغت Cashfree عن مبلغ أو عملة مدفوعين يختلفان عن إجمالي الطلب. تعرض ملاحظة المبلغ المتوقع والمبلغ المستلم. الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة معلّق. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Refunded Status: تُعيَّن بعد استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: تم الاسترداد.

متقدم

API Version: إصدار Cashfree API المراد استخدامه.

Order ID prefix: تُبنى معرّفات طلبات Cashfree على النحو التالي: بادئة + معرّف طلب OpenCart؛ تحصل محاولة جديدة للطلب نفسه على رقم في النهاية (مثل 123-2). اتركه فارغًا لاستخدام البادئة التلقائية لهذا المتجر، والمعروضة في وصف الحقل (OC، أربعة أحرف مشتقة من عنوان المتجر وشرطة). استخدم بادئة مختلفة لكل متجر متصل بحساب Cashfree نفسه. الحروف والأرقام و"_" و"-" فقط، حتى 20 حرفًا. تُحذف الأحرف الأخرى عند الحفظ مع تحذير.

Debug log: تُسجَّل الأخطاء دائمًا. عند التفعيل، تُكتب استدعاءات Cashfree API والـ webhooks أيضًا في cashfree_p_debug.log.php في مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُدوَّر. لا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: معطّل.

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Cashfree Payments). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة سيتم تحويلك إلى صفحة الدفع في Cashfree للدفع بأمان (البطاقات وUPI والخدمات المصرفية عبر الإنترنت والمحافظ الإلكترونية). ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. عندما ينقر العميل على Confirm Order، تنشئ الإضافة طلب Cashfree بإجمالي الطلب بعملة الطلب، وتفتح صفحة Cashfree payment تعرض جارٍ التحويل إلى Cashfree للدفع... وتحمّل صفحة الدفع في Cashfree. إذا لم تُفتح الصفحة تلقائيًا، يمكن للعميل النقر على Pay Now. في صفحة الدفع في Cashfree يدفع العميل بأي طريقة مفعّلة في حساب Cashfree الخاص بك، مثل البطاقة أو UPI أو الخدمات المصرفية عبر الإنترنت أو المحفظة الإلكترونية. يُمرَّر البريد الإلكتروني ورقم هاتف العميل إلى Cashfree. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose الموجود في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. ولا يطلب OpenCart 4 رقم هاتف افتراضيًا: إذا لم يكن للطلب رقم، تعرض كتلة التأكيد حقل Phone اختياريًا (اختياري: رقم هاتف الدافع لـ Cashfree (UPI, OTP).). وتعرض الصيغة الخاطئة يرجى إدخال رقم هاتف صالح (10 أرقام، أو + ورمز الدولة) أو ترك الحقل فارغًا. ويُحفظ الرقم للمحاولة التالية.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Cashfree الدفع: عبر الـ webhook الموقّع، أو عبر طلب من الخادم إلى Cashfree عندما يعود العميل. بعد ذلك يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. ويعمل الرجوع أيضًا في متصفح آخر، على سبيل المثال عندما يعود العميل من تطبيق UPI. وإذا لم يؤكد البنك الدفعة بعد، تعرض صفحة Payment confirmation الرسالة Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. وزر Check again؛ ويضبط الـ webhook حالة الطلب فور تأكيد البنك للدفعة. وفي OpenCart 4 لا يرسل المتصفح جلسة المتجر عندما يعيد Cashfree العميل، لذلك تعرض الإضافة أولًا صفحة قصيرة تفتح عنوان العودة نفسه مرة أخرى من متجرك، فيحتفظ العميل بسلته وبتسجيل دخوله.

إذا فشل الدفع أو غادر العميل صفحة Cashfree دون أن يدفع، يعود العميل إلى صفحة الدفع مع لم يكتمل الدفع عبر Cashfree. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وفي OpenCart 4 تُعرض رسائل الدفع فوق صفحة الدفع. يبقى الطلب بدون حالة وتُحفظ السلة. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيحتفظ بطلب واحد للصفحة ويحدّثه، فيدفع العميل الطلب نفسه مرة أخرى. يُعاد استخدام دفعة Cashfree المفتوحة للطلب نفسه عندما لا يتغير المبلغ ويبقى أكثر من خمس دقائق؛ وإلا يُغلق طلب Cashfree القديم وينشأ طلب جديد. تُغلق أيضًا دفعات Cashfree المفتوحة للطلبات السابقة من السلة نفسها، حتى لا يمكن دفع السلة مرتين. وإذا كانت السلة مدفوعة بالفعل في Cashfree لكنها لم تُسجَّل، تؤكد المحاولة التالية تلك الدفعة بدلًا من الخصم مرة أخرى. لا يُخصم مرة أخرى من سلة دُفع ثمنها بالفعل بطلب آخر: ينتقل العميل إلى صفحة النجاح. وإذا دُفعت السلة نفسها مرتين مع ذلك (مثلًا في تبويبين من المتصفح في الوقت نفسه)، يبقى الطلب الثاني بدون حالة، ويحصل الطلب المدفوع على ملاحظة بأن العميل ربما خُصم منه مرتين، حتى تتمكن من استرداد المبلغ في لوحة Cashfree.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب في هذه الأثناء (مثلًا لأنك ألغيته) ولم يحتفظ Cashfree بأي مبلغ له، يُعاد العميل إلى صفحة الدفع مع لم يكتمل الدفع عبر Cashfree. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.، وتؤدي النقرة التالية على Confirm Order إلى دفع طلب جديد للسلة. وإذا كان للطلب حالة بالفعل وتغيرت السلة بعده (منتجات أو كميات أخرى)، يُعاد العميل إلى صفحة الدفع مع تم تقديم طلبك السابق بالفعل. يرجى تأكيد الطلب مرة أخرى: ستُدفع السلة الحالية بطلب جديد..

إذا تعذّر على Cashfree بدء الدفع، يبقى العميل في خطوة Confirm Order مع تعذّر بدء الدفع عبر Cashfree. يرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. فوق الزر. يُكتب السبب التقني في السجل. ولا يمكن دفع طلب بإجمالي أقل من الحد الأدنى لـ Cashfree (وحدة واحدة من العملة؛ و0.01 للعملات ذات ثلاث منازل عشرية مثل KWD، و0.1 لـ TND) عبر Cashfree، ولا تُعرض طريقة الدفع لذلك الطلب.

يعمل الـ webhook أيضًا أثناء وجود المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة في OpenCart 4 إجراء بدء التشغيل الذي يسمح بمرور الـ webhook وعودة العميل.

تقبل الإضافة مدفوعات لمرة واحدة فقط في صفحة الدفع في Cashfree. ليس فيها بطاقات محفوظة أو اشتراكات أو مدفوعات متكررة، ولا تفويض وتحصيل منفصلان، ولا عنصر عروض Cashfree، ولا الدفع عند الاستلام عبر Cashfree أو روابط الدفع، ولا تحويل للعملات: يُخصم الطلب بعملة الطلب.

الطلبات وعمليات الاسترداد

حالات الطلب

بدون حالة (طلب مفقود): أُرسل العميل إلى Cashfree ولم يدفع، أو فشلت الدفعة، أو لا تزال الدفعة معلّقة لدى البنك. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Order Status After Payment (الافتراضي قيد المعالجة): تم تأكيد الدفعة. تعرض ملاحظة معرّف معاملة Cashfree ومجموعة طريقة الدفع (مثل upi أو credit_card).

On Hold (Review) Status (الافتراضي قيد الانتظار): أبلغت Cashfree عن مبلغ أو عملة مدفوعين يختلفان عن إجمالي الطلب. تعرض الملاحظة المبلغ المتوقع والمبلغ المستلم، إضافة إلى معرّف المعاملة. تحقق من الدفعة في لوحة Cashfree، ثم أتمّ الطلب أو استرد الدفعة.

Refunded Status (الافتراضي تم الاسترداد): تم استرداد الدفعة بالكامل عبر الإضافة.

تُسجَّل الدفعة التي تصل بعد أن تكون قد أعطيت الطلب المعلّق حالة يدويًا (مثل ملغى)، ويصبح الطلب مدفوعًا، لأن المبلغ قد خُصم؛ ويُبلغ OpenCart العميل بهذا التغيير. لا يعود الطلب المدفوع إلى الوراء بسبب دفعة فاشلة لاحقة، ولا تغيّره دفعة ثانية لطلب مدفوع بالفعل.

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

تبويب VibeFox Cashfree Payments

في Sales > Orders افتح طلبًا دُفع عبر Cashfree. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Cashfree Payments Transaction ID مع تسمية Sandbox لمدفوعات sandbox، وCashfree order، وStatus الدفعة، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد مع حالة كل عملية، وCashfree notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

عمليات الاسترداد

في التبويب أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via Cashfree. أكّد السؤال Refund this amount through Cashfree? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). تُنفَّذ عمليات الاسترداد بالمبلغ والعملة اللذين خصمهما Cashfree، لذلك بعد اختلاف المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب. يُرسل الاسترداد إلى طلب Cashfree المدفوع، في البيئة (sandbox أو الإنتاج) التي دُفع فيها، لذلك يجب ضبط مفاتيح تلك البيئة. إذا لم يقبل Cashfree الاسترداد، أو أبلغ عنه بأنه ملغى أو مرفوض، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد المبدوء إلى سجل الاسترداد والملاحظات مع معرّفه ومبلغه وحالته. يضبط الاسترداد الكامل الطلب على Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا مثل تغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. تصبح عمليات الاسترداد متاحة بعد أن تؤكد Cashfree الدفع.

تصل الحالة النهائية للاسترداد عبر الـ webhook الخاص بالاسترداد وتُضاف إلى الملاحظات. لا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر Cashfree.

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

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

بدون مفتاح فعّال لا يُعرض Cashfree للعملاء في صفحة الدفع. وإذا بدأ الدفع مع ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ما زال مستخدم الإدارة المسجل الدخول إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع علامة (غير مرخّصة — مرئية للمسؤولين فقط)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. في OpenCart 4 لا تتوفر هذه المعاينة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تبقى طريقة الدفع مخفية عن الجميع دون مفتاح فعّال. بعد فتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاص بلوحة الإدارة. أغلقه بـ × لإخفائه لمدة 7 أيام. لا تتأثر الطلبات الموجودة: تظل الدفعات التي بدأت مؤكدة، وتعمل عمليات الاسترداد.

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

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

لا يظهر Cashfree في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفاتيحه: Sandbox App ID وSandbox Secret Key في وضع sandbox، وApp ID وSecret Key في الوضع الفعلي. تعرض صفحة الإعدادات تحذيرًا عند غياب المفاتيح. وتُخفى طريقة الدفع أيضًا عندما يكون إجمالي الطلب أقل من الحد الأدنى لـ Cashfree. وتحقق أيضًا من وجود عنوان الدفع ضمن Geo Zone المحددة، ومن أن الطلب يبلغ Total المضبوط في الإعدادات.

تم الدفع، لكن الطلب بقي بدون حالة: الـ webhook لا يعمل. تحقق من أن متجرك يستخدم HTTPS، وأن العنوان في Developers > Webhooks هو بالضبط العنوان المعروض في Webhook URL، وأن أحداث الدفع محددة. تحقق من أن مفتاح Secret Key في الإعدادات يتبع البيئة التي تمت فيها الدفعة. تعرض لوحة Cashfree رد متجرك على كل webhook. ويحصل الطلب على حالته أيضًا عندما يعود العميل إلى المتجر بعد الدفع، وعند محاولة الدفع التالية للسلة نفسها.

يرد الـ webhook بـ Missing signature أو Invalid signature: لم يحمل الاستدعاء توقيع Cashfree صالحًا، أو أن مفتاح Secret Key في الإعدادات لا يطابق البيئة التي تمت فيها الدفعة. تحقق من أن مفاتيح sandbox والمفاتيح الفعلية لم تُبدَّل.

يرد الـ webhook بـ Ignored: الـ webhook موقّع بشكل صحيح، لكنه يخص دفعة لم يبدأها هذا المتجر، مثل متجر آخر على حساب Cashfree نفسه. امنح كل متجر Order ID prefix خاصًا به.

يرد الـ webhook بـ Busy, retry later: كان الطلب يُؤكَّد من طلب آخر في اللحظة نفسها، أو تعذر ضبط حالة الطلب. تعيد Cashfree محاولة الـ webhook. فعّل Debug log لمعرفة السبب.

يرى العميل «تعذّر تحميل صفحة الدفع في Cashfree. يرجى المحاولة مرة أخرى.»: لم يتمكن المتصفح من تحميل برنامج Cashfree النصي، مثلًا بسبب أداة حجب. يمكن للعميل النقر على Pay Now مرة أخرى أو على Choose another payment method.

يرى العميل «تعذّر بدء الدفع عبر Cashfree»: انظر إلى الحقل Log في صفحة الإضافة. من الأسباب الشائعة مفاتيح خاطئة للوضع المحدد، أو عملة غير مفعّلة في حساب Cashfree الخاص بك.

يرى العميل «طريقة الدفع هذه غير متاحة.» بعد Confirm Order: جلسة الدفع لم تعد تطابق الطلب، أو أُوقفت طريقة الدفع في هذه الأثناء. يعيد العميل تحميل صفحة الدفع.

يرى العميل «لم يتم العثور على جلسة الدفع. يرجى المحاولة مرة أخرى.»: رابط صفحة الدفع لا يخص دفعة من هذا المتجر، أو انتهت جلسة Cashfree. يعيد العميل تأكيد الطلب.

يرى العميل «تعذّر التحقق من الدفعة»: رابط العودة لم يطابق الدفعة. إذا خُصم المبلغ، ما زال الـ webhook يؤكد الطلب. تحقق من الدفعة في لوحة Cashfree قبل أن يدفع العميل مرة أخرى.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Cashfree Payments (راجع حالات الطلب)، ثم أتمّ الطلب أو استرد الدفعة.

لا يوجد نموذج استرداد في التبويب: يذكر التبويب السبب: الدفعة غير مؤكدة بعد، أو مستردة بالكامل، أو مجموعة المستخدمين الخاصة بك لا تملك صلاحية تعديل الإضافة، أو مفاتيح API لبيئة الدفعة غير مضبوطة.

يفشل الاسترداد برسالة متعلقة بوضع sandbox أو الوضع الفعلي: تمت الدفعة في تلك البيئة، ومفاتيح API الخاصة بها غير مضبوطة. أدخلها وحاول مرة أخرى.

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

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

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

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