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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

5. عند الجاهزية أدخل App ID وSecret Key الخاصين بالإنتاج، وأوقف Sandbox Mode، وانقر Save.

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

الإعدادات

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

Cashfree Payments

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

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

Description: النص الذي يظهر أسفل طريقة الدفع في الدفع. الافتراضي: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

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

Sandbox Mode: يستخدم بيئة الاختبار (sandbox) لدى Cashfree. لا يُخصم أي مبلغ حقيقي، ويظهر في الدفع أسفل طريقة الدفع النص SANDBOX MODE - no real payments will be processed. الافتراضي: on. أوقفه للمدفوعات الحقيقية.

Sandbox App ID: معرّف App ID لبيئة الاختبار لديك في Cashfree.

Sandbox Secret Key: المفتاح السري لبيئة الاختبار لديك في Cashfree.

App ID: معرّف App ID لبيئة الإنتاج لديك في Cashfree.

Secret Key: المفتاح السري لبيئة الإنتاج لديك في Cashfree.

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها.

Clear saved secrets: ضع علامة على Secret Key ثم انقر Save لحذفه. ويُبقي الحقل الفارغ القيمة المحفوظة.

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

Webhook

يُخبر الـ webhook متجرك بأن دفعة تمت أو فشلت أو استُردّت. في Cashfree Merchant Dashboard انتقل إلى Developers > Webhooks وأضف العنوان المعروض في Webhook URL في هذا القسم، مع حدثي Payment وRefund. وباستخدام عناوين URL الودية يكون شكله: https://your-shop/module/wcp_cashfree_payment/webhook. انسخ العنوان تمامًا كما تعرضه الإعدادات. وفي المتجر الذي يعمل بـ HTTPS تمرّر الوحدة هذا العنوان إلى Cashfree مع كل دفعة. وإذا كان متجرك لا يستخدم HTTPS فسيعرض هذا القسم تحذيرًا.

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

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

Advanced

API Version: إصدار واجهة Cashfree البرمجية المراد استخدامه.

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

Debug log: تُسجَّل الأخطاء دائمًا. وعند التفعيل تُكتب أيضًا استدعاءات Cashfree API والـ webhooks في logs/cashfree_p_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. ولا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: off.

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Cashfree Payments) ويؤكد. تنشئ الوحدة طلب Cashfree بإجمالي السلة وبعملتها، وتفتح صفحة دفع تعرض Redirecting to Cashfree for payment... وتحمّل صفحة الدفع في Cashfree. وإذا لم تُفتح تلقائيًا يمكن للعميل النقر على Pay Now. وفي صفحة الدفع في Cashfree يدفع العميل بأي طريقة مفعّلة في حسابك لدى Cashfree، مثل البطاقة أو UPI أو الخدمات المصرفية عبر الإنترنت أو المحفظة الإلكترونية. ويُرسل البريد الإلكتروني ورقم هاتف الفوترة الخاصان بالعميل إلى Cashfree. وفي هذه المرحلة لا يوجد أي طلب بعد.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Cashfree الدفعة: إما بالـ webhook الموقَّع، أو بطلب من الخادم إلى Cashfree عند عودة العميل. عندئذ يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة. وتعمل العودة أيضًا في متصفح آخر، مثلًا عندما يعود العميل من تطبيق 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 الطلب فور تأكيد البنك للدفعة.

إذا فشلت الدفعة أو غادر العميل صفحة Cashfree دون الدفع، يعود إلى الدفع ويرى The Cashfree payment was not completed. Please try again or choose another payment method. وتبقى السلة محفوظة. وتُعاد استخدام عملية دفع مفتوحة في Cashfree عندما يحاول العميل مجددًا. وإذا تغيّر إجمالي السلة أو كانت الجلسة على وشك الانتهاء، يُغلق طلب Cashfree القديم وينشأ طلب جديد، حتى لا يمكن دفع السلة مرتين. وإذا دُفعت السلة لدى Cashfree دون تسجيلها، فإن المحاولة التالية تُنشئ الطلب بدلًا من خصم المبلغ مرة أخرى.

إذا تعذّر على Cashfree بدء الدفع، يبقى العميل في الدفع ويرى We could not start the Cashfree payment. Please try again or choose another payment method. ويُكتب السبب التقني في السجل. ولا يمكن دفع إجمالي سلة أقل من الحد الأدنى لدى Cashfree (وحدة واحدة من العملة؛ و0.01 للدينار البحريني والدينار الأردني والدينار الكويتي والريال العماني، و0.1 للدينار التونسي) عبر Cashfree، ولا تُعرض طريقة الدفع لتلك السلة.

يعمل الـ webhook أثناء وضع الصيانة في المتجر، ولا يتأثر بقيود الدول المفروضة على متجرك.

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

الطلبات والاستردادات

Order statuses

No order yet: أُرسل العميل إلى Cashfree ولم يدفع، أو فشلت الدفعة، أو لا تزال الدفعة قيد الانتظار لدى البنك. لا توجد سوى السلة.

Payment accepted: تم تأكيد الدفعة. تُسجَّل الدفعة بمعرّف دفع Cashfree كمعرّف للمعاملة، وتعرض ملاحظة معرّف المعاملة ومجموعة طريقة الدفع (مثل upi أو credit_card).

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

Refunded: استُرد المبلغ بالكامل عبر الوحدة.

تُسجَّل الدفعة التي تصل بعد إلغاء الطلب، ويعود الطلب إلى حالة المدفوع لأن المبلغ قد خُصم. ولا يعود الطلب المدفوع إلى حالة غير المدفوع بسبب دفعة لاحقة فاشلة.

Cashfree payment block

تعرض صفحة الطلب كتلة Cashfree payment تتضمن معرّف المعاملة، وطلب Cashfree، وحالة الدفع، والمبلغ المدفوع والمسترد، وشارة Sandbox لمدفوعات الاختبار، وسجل الاستردادات، وCashfree notes الخاصة بالطلب.

Refunds

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

تصل الحالة النهائية للاسترداد عبر الـ webhook الخاص بالاسترداد وتُضاف إلى الملاحظات. ولا تُنشئ الوحدة إشعارات دائنة. وأزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Cashfree.

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

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

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

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

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

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

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

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

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

يرد الـ webhook بـ Busy, retry later: كان الطلب يُنشأ في الوقت نفسه بواسطة طلب آخر، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة). ستعيد Cashfree إرسال الـ webhook. فعّل Debug log لمعرفة السبب.

يرى العميل The Cashfree payment page could not be loaded: تعذّر تحميل نص Cashfree البرمجي في المتصفح، مثلًا بسبب أداة حجب. يمكن للعميل النقر مجددًا على Pay Now أو على Choose another payment method.

يرى العميل We could not start the Cashfree payment: انظر إلى حقل Log في صفحة الوحدة. ومن الأسباب الشائعة مفاتيح خاطئة للوضع المختار، أو عملة غير مفعّلة في حسابك لدى Cashfree.

يرى العميل We could not verify the payment: لم يتطابق رابط العودة مع السلة. وإذا خُصم المبلغ، فإن الـ webhook ينشئ الطلب على أي حال. تحقّق من الدفعة في لوحة Cashfree قبل أن يدفع العميل مرة أخرى.

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

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

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

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

Cashfree علامة تجارية تخص مالكها. هذه الوحدة غير تابعة لـ Cashfree ولا تحظى بتأييدها.