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

المتطلبات

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

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

حساب Razorpay: تحتاج إلى Key ID وKey Secret لحساب Razorpay الخاص بك في وضع الاختبار، ولوضع الإنتاج بعد تفعيل حسابك. يُوصى بشدة باستخدام webhook مع secret تختاره أنت (راجع الإعدادات). تتطلب المدفوعات بعملات غير INR تفعيل International Payments في حساب Razorpay الخاص بك.

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

التثبيت

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

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

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

4. أدخل Test Key ID وTest Key Secret، وأعدّ الـ webhook في Razorpay Dashboard، ثم أدخل الـ secret الخاص به (راجع الإعدادات).

5. فعّل Enable/Disable وانقر على Save. أجرِ دفعة تجريبية مع تفعيل Test mode. عندما تصبح جاهزًا، أدخل مفاتيح Live وأوقف Test mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Razorpay Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وتعرض الصفحة فوق الحقول تنبيهات: مفاتيح الوضع الحالي غير مكتملة (وعندئذٍ لا يظهر Razorpay في الدفع)، أو Key ID لا يبدأ بـ rzp_test_ في وضع الاختبار أو بـ rzp_live_ في وضع الإنتاج، أو وضع الاختبار مفعّل، أو secret الخاص بالـ webhook فارغ، أو عملة المتجر الافتراضية ليست INR وتتطلب تفعيل International Payments في حساب Razorpay الخاص بك. تُحذف المسافات الملصوقة مع Key ID عند الحفظ.

Razorpay

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

Title: اسم طريقة الدفع الذي يراه العملاء في الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: UPI, Cards, NetBanking. مطلوب: العنوان الفارغ يعطي الخطأ Enter a title for the payment method.

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

مفاتيح API

احصل على مفاتيحك من Razorpay Dashboard، ضمن Account & Settings > API Keys. بدّل Dashboard إلى وضع الاختبار لإنشاء مفاتيح الاختبار (rzp_test_...). تتوفر مفاتيح الإنتاج (rzp_live_...) بعد تفعيل حسابك.

Test mode: يستخدم مفاتيح وضع الاختبار، لذلك لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية. تستخدم مدفوعات الطلب وتحصيله واسترداده دائمًا مفاتيح الوضع الذي دُفع فيه الطلب، لذلك لا يؤثر تغيير الوضع لاحقًا في الطلبات الحالية.

Test Key ID: الـ Key ID من Razorpay Dashboard في وضع الاختبار. يبدأ بـ rzp_test_.

Test Key Secret: الـ Key Secret من Razorpay Dashboard في وضع الاختبار.

Live Key ID: الـ Key ID من Razorpay Dashboard في وضع الإنتاج. يبدأ بـ rzp_live_.

Live Key Secret: الـ Key Secret من Razorpay Dashboard في وضع الإنتاج.

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

مسح الـ secrets المحفوظة: ضع علامة على Test Key Secret أو Live Key Secret أو Webhook Secret، ثم انقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع

Payment Action: الوقت الذي يُخصم فيه المبلغ. الافتراضي: Authorize & Capture.

Authorize & Capture: يُخصم المبلغ من العميل فورًا. إذا أبلغت Razorpay عن دفعة مُصرَّح بها، تحصّلها الوحدة.

Authorize Only: يُحجز المبلغ. يُنشأ الطلب بحالة Razorpay payment authorized، وتحصّل الدفعة لاحقًا بـ Capture Razorpay payment في كتلة Razorpay في صفحة الطلب، أو في Razorpay Dashboard. تسترد Razorpay تلقائيًا الدفعات المُصرَّح بها التي لم تُحصَّل في الوقت المحدد.

Webhook

يؤكد الـ webhook المدفوعات حتى لو أغلق العميل المتصفح مباشرةً بعد الدفع، ويسجّل الاستردادات التي تُجرى في Razorpay Dashboard. في Razorpay Dashboard انتقل إلى Account & Settings > Webhooks وأضف webhook في وضع الاختبار وآخر في وضع الإنتاج. استخدم الرابط المعروض في Webhook URL في هذا القسم. عند تفعيل الروابط الودية يبدو الرابط هكذا: https://your-shop/module/wcp_razorpay_payment/webhook، وقد يتضمن رمز لغة مثل /en/. انسخه تمامًا كما تعرضه الإعدادات. أدخل في Razorpay secret تختاره، واختر هذه الأحداث (وهي مدرجة أيضًا في هذا القسم):

payment.authorized: تم التصريح بالدفعة.

payment.captured: تم تحصيل الدفعة، بما في ذلك عندما تحصّلها في Razorpay Dashboard.

payment.failed: فشلت محاولة دفع.

order.paid: تم دفع طلب Razorpay الخاص بالدفعة.

refund.created: تم استرداد دفعة، على سبيل المثال في Razorpay Dashboard.

Webhook Secret: الـ secret الذي أدخلته عند إنشاء الـ webhook. استخدم الـ secret نفسه لـ webhook الاختبار وwebhook الإنتاج، لأن الوحدة تملك حقلًا واحدًا لهما. تُرفض webhooks التي لا تحمل توقيعًا صالحًا. من دون الـ webhook، لا تُؤكَّد الدفعة إلا عندما يعود العميل من النافذة المنبثقة، أو عندما يبدأ العميل الدفع للسلة نفسها لاحقًا.

متقدم

Enable Logging: يُكتب السجل في logs/razorpay_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا؛ هذا الخيار يضيف تفاصيل التصحيح. لا تُسجَّل المفاتيح والتواقيع وبيانات اتصال العميل أبدًا. الافتراضي: معطّل.

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا UPI, Cards, NetBanking) ويؤكد. تنشئ الوحدة طلب Razorpay بالمبلغ الإجمالي الدقيق للسلة وعملتها، وتفتح صفحة Razorpay payment في متجرك. تُفتح نافذة Razorpay Checkout المنبثقة في تلك الصفحة تلقائيًا، مع تعبئة اسم العميل وبريده الإلكتروني وهاتفه مسبقًا. تظهر الدفعة في Razorpay باسم Cart ورقم السلة. لا يوجد طلب PrestaShop في هذه المرحلة. إذا أُغلقت النافذة، يستطيع العميل النقر على Pay Now لإعادة فتحها، أو على Choose another payment method للعودة إلى الدفع. تبقى السلة محفوظة. في وضع الاختبار تعرض الصفحة Razorpay Test mode: no real money will be charged.

بعد نجاح الدفع يرى العميل Please wait while we process your payment... تتحقق الوحدة من توقيع Razorpay، وتسترجع الدفعة من واجهة برمجة تطبيقات Razorpay، وتقارن المبلغ والعملة بالسلة. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Razorpay. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة. إذا كان التوقيع صالحًا لكن تعذّر استرجاع الدفعة في تلك اللحظة، يُنشأ الطلب بحالة Razorpay payment on hold، ويؤكده الـ webhook لاحقًا.

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

الرسائل التي قد يراها العميل:

Your session has expired. Please click "Pay Now" to try again.

We could not verify your payment. تضيف الرسالة أن الطلب سيُحدَّث تلقائيًا بمجرد أن تؤكد Razorpay الدفعة، إذا كان المبلغ قد خُصم.

This payment method is not available right now. Please choose another payment method. المفاتيح مفقودة أو غير صحيحة.

Razorpay is temporarily unavailable. Please try again in a few minutes.

Razorpay could not accept this payment: يليه السبب الذي تذكره Razorpay.

The order amount is too small to be paid with Razorpay.

Razorpay Checkout could not be loaded. نص النافذة المنبثقة محظور؛ وتطلب الرسالة التحقق من الاتصال، وتعطيل حاجبات المحتوى، وإعادة تحميل الصفحة.

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

تقبل الوحدة المدفوعات لمرة واحدة فقط. لا تتضمن الاشتراكات أو المدفوعات المتكررة، ولا البطاقات المحفوظة، ولا Razorpay Magic Checkout، ولا Payment Links أو Route (المدفوعات المقسّمة)، ولا أدوات العروض أو القدرة على تحمّل التكلفة.

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

حالات الطلب

No order yet: لم يدفع العميل، أو لم تؤكد Razorpay الدفعة بعد. لا توجد إلا السلة. لا تُنشئ محاولة الدفع الفاشلة طلبًا؛ ويستطيع العميل الدفع مرة أخرى.

Payment accepted: تم تحصيل الدفعة وتأكيدها. تُسجَّل الدفعة بمعرّف دفعة Razorpay (pay_...) كمعرّف للمعاملة، وتعرض ملاحظة معرّف الدفعة والمبلغ وطريقة التأكيد (callback أو webhook أو sync أو admin).

Razorpay payment authorized: الدفعة مُصرَّح بها فقط (Authorize Only). حصّلها لإكمال الطلب.

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

Cancelled: الدفعة التي تصل لاحقًا لطلب ملغى لا تعيد فتح الطلب تلقائيًا: الدفعة المُصرَّح بها لا تُحصَّل وتتلقى ملاحظة فقط، والدفعة المحصّلة تنقل الطلب إلى Razorpay payment on hold. الإشعار المتكرر بالدفعة التي دفعت الطلب بالفعل لا يغيّر شيئًا، حتى لو ألغيت الطلب بعد ذلك.

Refunded: تم استرداد الدفعة بالكامل.

إذا وصلت دفعة إضافية لطلب مدفوع بالفعل، لا يتغير الطلب. تطلب منك ملاحظة استردادها في Razorpay Dashboard إذا لم تكن مقصودة. أما payment.failed المتأخر لطلب مدفوع فيضيف ملاحظة فقط.

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

تعرض صفحة الطلب كتلة Razorpay payment تتضمن معرّف دفعة Razorpay، وطلب Razorpay، وحالة الدفعة، وPaid / refunded (المبلغ الذي خصمته Razorpay والمبلغ المسترد)، وشارة Test mode للدفعات التجريبية، وسجل الاستردادات، وRazorpay notes الخاصة بالطلب. يتطلب التحصيل والاسترداد صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى إعدادات الوحدة.

التحصيل (Authorize Only)

افتح الطلب بحالة Razorpay payment authorized، وانقر على Capture Razorpay payment في كتلة Razorpay، ثم أكّد. تُحصَّل الدفعة في الوضع الذي صُرِّح بها فيه، ويصبح الطلب Payment accepted. إذا رفضت Razorpay، تعرض الكتلة والملاحظات Razorpay capture failed: مع السبب. التحصيل الذي يُجرى في Razorpay Dashboard يُكمل الطلب عبر الـ webhook.

الاستردادات

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

لا تنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترد الأموال عبر Razorpay.

تصل الاستردادات التي تُجرى في Razorpay Dashboard عبر الـ webhook، وتُسجَّل مرة واحدة في سجل الاستردادات والملاحظات. عند استرداد الطلب بالكامل تصبح حالته Refunded. الاسترداد من Dashboard بعملة أخرى أو بمبلغ أكبر من المبلغ القابل للاسترداد لا يُسجَّل تلقائيًا؛ وتطلب ملاحظة تسجيله يدويًا.

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

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

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

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

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

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

تم الدفع لكن لم يُنشأ أي طلب: الـ webhook لا يعمل. في Razorpay Dashboard تحقق من أن الـ webhook موجود في الوضع الذي تستخدمه (Test أو Live)، وأن رابطه مطابق تمامًا للرابط المعروض في Webhook URL، وأن الأحداث الخمسة محددة. تحقق من أن Webhook Secret هو نفس الـ secret الموجود في Razorpay. يُنشأ الطلب أيضًا عندما يعود العميل من النافذة المنبثقة، أو يبدأ الدفع للسلة نفسها مرة أخرى.

يرد الـ webhook بالرسالة Webhook secret not configured: Webhook Secret فارغ. أدخل الـ secret الخاص بـ webhook في Razorpay. سترسل Razorpay الحدث مرة أخرى لاحقًا.

يرد الـ webhook بالرسالة Invalid signature أو Missing signature: الـ secret في الإعدادات يختلف عن الـ secret الخاص بـ webhook في Razorpay. أدخل الـ secret نفسه في المكانين، لـ webhook الاختبار وwebhook الإنتاج.

يرد الـ webhook بالرسالة Retry later: تعذّر على الوحدة تأكيد التحصيل عبر واجهة برمجة تطبيقات Razorpay، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة)، أو كانت السلة تُحدَّث بطلب آخر في الوقت نفسه. سترسل Razorpay الحدث تلقائيًا مرة أخرى. السبب موجود في Log.

يعرض رابط الـ webhook الرسالة Method not allowed في المتصفح: هذا طبيعي. يقبل الرابط الطلبات الصادرة من Razorpay فقط.

الطلب بحالة Razorpay payment on hold: اقرأ الملاحظات في كتلة Razorpay. لم يتطابق المبلغ أو العملة مع السلة، أو وصلت الدفعة لطلب ملغى، أو تعذّر التحقق منها عبر واجهة برمجة تطبيقات Razorpay في تلك اللحظة، وهي تنتظر الـ webhook.

يرى العميل خطأ عند الدفع: انظر إلى حقل Log في صفحة الوحدة. تُسجَّل الأخطاء حتى مع إيقاف Enable Logging. المفاتيح الخاطئة تعطي رسالة بأن طريقة الدفع غير متاحة حاليًا. أسباب Razorpay الأخرى تظهر بعد Razorpay could not accept this payment:.

لا تفتح النافذة المنبثقة: تم حظر نص Razorpay Checkout بسبب حاجب محتوى أو بسبب الاتصال. يرى العميل رسالة ويستطيع إعادة تحميل الصفحة.

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

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

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

Razorpay علامة تجارية تعود إلى مالكها. هذه الوحدة غير مرتبطة بـ Razorpay ولا تحظى بتأييد منها.