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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل Sandbox App ID وSandbox Secret Key، وأضف الـ webhook في لوحة التاجر لدى Cashfree (راجع قسم الإعدادات)، وفعّل Enable/Disable، وجرّب دفعة.

6. عند الجاهزية، أدخل App ID وSecret Key الخاصين بالإنتاج، وألغِ تحديد Sandbox Mode.

الإعدادات

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

عام

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

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

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

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

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

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

بيانات اعتماد بيئة الاختبار

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

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

بيانات اعتماد الإنتاج

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

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

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

Webhook

يُخبر الـ webhook متجرك بأن الدفعة تمت أو فشلت أو استُردت. في لوحة التاجر لدى Cashfree انتقل إلى Developers > Webhooks، وأضف العنوان الظاهر في هذا القسم مع حدثي الدفع والاسترداد. ويبدو بالشكل https://your-site/wc-api/cashfree_p/?action=webhook. وعلى موقع HTTPS تمرّر الإضافة هذا العنوان إلى Cashfree مع كل طلب. وإذا لم يكن موقعك يستخدم HTTPS، يعرض هذا القسم تحذيرًا.

تتعامل الإضافة مع هذه الأحداث:

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

متقدم

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

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

Debug log: Log Cashfree API events for debugging. تُسجَّل الأخطاء دائمًا. وعند التفعيل تُكتب استدعاءات API والـ webhooks أيضًا في WooCommerce > Status > Logs، والمصدر wcp_cashfree_payment. ولا تُسجَّل المفاتيح وبيانات العميل أبدًا. الافتراضي: إيقاف.

Delete Data on Uninstall: Delete all plugin data when uninstalling. عند التفعيل، يؤدي حذف الإضافة إلى إزالة إعدادات Cashfree وسجلات الإضافة ومراجع Cashfree المحفوظة في الطلبات. أما الطلبات نفسها فتبقى. الافتراضي: إيقاف.

صفحة الدفع

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

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

إذا فشل الدفع، أو ترك العميل صفحة Cashfree دون أن يدفع، يعود إلى صفحة Pay for order مع 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 لـ BHD وJOD وKWD وOMR، و0.1 لـ TND) عبر Cashfree.

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Cashfree ولم يدفع بعد، أو ما زالت الدفعة معلقة لدى البنك. وعندما يعود العميل ومعه دفعة معلقة، تُظهر ملاحظة أن الإضافة تنتظر الـ webhook من Cashfree.

Processing: تم تأكيد الدفع (تصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط «مكتمل»، وهذا هو الإعداد الافتراضي في WooCommerce). تعرض ملاحظة الطلب معرّف معاملة Cashfree وفئة طريقة الدفع. ومعرّف معاملة الطلب هو معرّف الدفعة (payment ID) في Cashfree. وتُسجَّل الدفعة التي تصل بعد إلغاء الطلب أيضًا، لأن المبلغ قد خُصم بالفعل.

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

Failed: فشلت الدفعة أو أُلغيت لدى Cashfree. تعرض الملاحظة حالة Cashfree وسببها. وتُضاف ملاحظة واحدة لكل محاولة فاشلة إضافية.

لا يُعاد الطلب المدفوع إلى حالة أخرى بأي webhook أو عودة لاحقة.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Cashfree Payments (يعرض الزر عنوان طريقة الدفع). يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد إلى طلب Cashfree الذي دُفع، في البيئة (بيئة الاختبار أو الإنتاج) التي دُفع فيها، لذا يجب ضبط مفاتيح تلك البيئة. وإذا لم تقبل Cashfree الاسترداد، أو أبلغت عنه بأنه ملغى أو مرفوض، تعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. وتُضاف عملية الاسترداد التي بدأت إلى ملاحظات الطلب مع رقم الاسترداد والمبلغ والحالة. وتصل الحالة النهائية عبر webhook الاسترداد كملاحظة أخرى في الطلب.

تُضاف الـ webhooks الخاصة بحالة الاسترداد إلى الملاحظات فقط، ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce.

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

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

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

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

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

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

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

تم الدفع لكن الطلب ما زال Pending payment: الـ webhook لا يعمل. تحقق من أن موقعك يستخدم HTTPS، وأن العنوان في Developers > Webhooks مطابق تمامًا للعنوان الظاهر في الإعدادات، وأن أحداث الدفع مُحدَّدة. وتحقق من أن المفتاح السري في الإعدادات يخص البيئة التي دُفع فيها الطلب. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع، وعند المحاولة التالية للدفع.

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

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

يرد الـ webhook برسالة Busy, retry later: كان الطلب يُعالَج في الوقت نفسه بطلب آخر. تُعيد Cashfree إرسال الـ webhook.

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

يرى العميل الرسالة We could not start the Cashfree payment: فعّل Debug log وراجع WooCommerce > Status > Logs، والمصدر wcp_cashfree_payment. ومن الأسباب الشائعة مفاتيح خاطئة للوضع المختار، أو عملة غير مفعّلة في حسابك لدى Cashfree.

يرى العميل الرسالة The minimum amount for a Cashfree payment is …: إجمالي الطلب أقل من الحد الأدنى لـ Cashfree لتلك العملة.

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

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

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

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

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

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

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