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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Razorpay Payment > Edit. تظهر الأقسام في القائمة على اليسار؛ يحفظ الزر Save أسفل القائمة الصفحة بأكملها. بدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

فوق الإعدادات، توضح الصفحة أن الطلب يحصل على حالة فقط بعد التحقق من الدفعة مع Razorpay، وتعرض إشعارات: مفاتيح الوضع الحالي مفقودة (وفي هذه الحالة لا يظهر Razorpay في الدفع)، أو أن Key ID لا يبدأ بـ rzp_test_ في وضع الاختبار أو بـ rzp_live_ في وضع الإنتاج، أو أن وضع الاختبار مفعّل، أو أن سرّ الـ webhook فارغ، أو أن العملة الافتراضية للمتجر ليست INR وتحتاج إلى International Payments في حساب Razorpay الخاص بك. تُحدَّث الإشعارات بعد كل حفظ.

عند الحفظ، يجب أن يتراوح طول Title بين 1 و128 حرفًا (Enter a title for the payment method (1 to 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (الأرقام السالبة مسموحة)، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن توجد المنطقة الجغرافية وكل حالة طلب. وإلا فلن يُحفظ شيء. تُحذف المسافات الملصقة مع Key IDs.

Razorpay

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

Title: اسم طريقة الدفع الذي يراه العميل في الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: UPI, Cards, NetBanking. مطلوب، حتى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order، أعلى زر التأكيد. الافتراضي: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

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

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

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يصل إليه الطلب قبل عرض Razorpay: رقم يساوي 0 أو أكبر. اتركه فارغًا لعرض Razorpay لأي إجمالي.

مفاتيح API

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

Test mode: يستخدم مفاتيح وضع الاختبار، لذلك لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لقبول المدفوعات الحقيقية. تستخدم المدفوعات والتحصيلات والاستردادات الخاصة بالطلب دائمًا مفاتيح الوضع الذي دُفع فيه الطلب، لذلك لا يؤثر تغيير الوضع لاحقًا في الطلبات الموجودة. وطالما هو مفعّل، يرى العملاء Razorpay Test mode: no real money will be charged. في خطوة Confirm Order وفي صفحة الدفع.

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

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

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

Live Key Secret: مفتاح السرّ من Razorpay Dashboard في وضع الإنتاج.

لا تُعرض الأسرار المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. لحذف قيمة محفوظة، ضع علامة على Clear the saved value on save أسفل الحقل وانقر على Save.

الدفع

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

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

Authorize Only: يُحجز المبلغ. يحصل الطلب على Authorized Status، وتحصّل الدفعة لاحقًا باستخدام Capture Razorpay payment في تبويب Razorpay في صفحة الطلب، أو في Razorpay Dashboard. يسترد Razorpay تلقائيًا الدفعات المُفوَّضة التي لا تُحصَّل في الوقت المناسب.

Webhook

يؤكد الـ webhook الدفعات حتى عندما يغلق العميل المتصفح مباشرة بعد الدفع، ويسجل المبالغ المستردة التي تُجرى في Razorpay Dashboard. في Razorpay Dashboard انتقل إلى Account & Settings > Webhooks وأضف webhook في وضع الاختبار وآخر في وضع الإنتاج. استخدم الرابط الظاهر في Webhook URL في هذا القسم. في OpenCart 3 يبدو هكذا https://your-store/index.php?route=extension/payment/wcp_razorpay_payment/webhook، وفي OpenCart 4 يبدو هكذا https://your-store/index.php?route=extension/wcp_razorpay_payment/payment/wcp_razorpay_payment.webhook. ويُنشأ من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. انسخه تمامًا كما تعرضه الإعدادات. أدخل في Razorpay سرًّا من اختيارك واختر هذه الأحداث (وهي مدرجة أيضًا في هذا القسم):

payment.authorized: تم تفويض دفعة.

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

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

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

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

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

الطلبات

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

Order Status After Payment: تم تحصيل الدفعة وتطابق المبلغ والعملة. الافتراضي: قيد المعالجة.

Authorized Status: Authorize Only: المبلغ محجوز، ولم يُحصَّل بعد. الافتراضي: قيد الانتظار.

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

Cancelled Status: لا تضبط الإضافة هذه الحالة أبدًا. وهي فقط تخبر الإضافة بالطلبات الملغاة: الدفعة التي تُحصَّل لاحقًا لمثل هذا الطلب تضعه في المراجعة بدلًا من إعادة فتحه؛ أما الدفعة المُفوَّضة فتضيف ملاحظة فقط. الافتراضي: ملغى.

Refunded Status: يُضبط بعد استرداد الدفعة بالكامل، من تبويب الطلب أو في Razorpay Dashboard. الافتراضي: مُسترد.

متقدم

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

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا UPI, Cards, NetBanking). في خطوة Confirm Order يرى العميل وصفك والملاحظة After "Confirm Order" the Razorpay Checkout window opens to pay securely (UPI, cards, NetBanking, wallets). ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال دون حالة. عندما ينقر العميل على Confirm Order، تنشئ الإضافة طلب Razorpay بالمبلغ والعملة الدقيقين للطلب، وتفتح صفحة Razorpay payment في متجرك. تُفتح نافذة Razorpay Checkout المنبثقة هناك تلقائيًا، مع تعبئة اسم العميل وبريده الإلكتروني ورقم هاتفه مسبقًا. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. تظهر الدفعة في Razorpay باسم Order # ورقم الطلب. إذا أُغلقت النافذة المنبثقة، يمكن للعميل النقر على Pay Now لفتحها مجددًا، أو على Choose another payment method للعودة إلى الدفع. تبقى السلة محفوظة.

بعد نجاح الدفع، يرى العميل Please wait while we process your payment... تتحقق الإضافة من توقيع Razorpay، وتجلب الدفعة من Razorpay API، وتقارن المبلغ والعملة بالطلب. لا يُعلَّم الطلب على أنه مدفوع إلا بعد أن يؤكد Razorpay ذلك. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. إذا كان التوقيع صالحًا لكن تعذّر جلب الدفعة في تلك اللحظة، يحصل الطلب على On Hold (Review) Status، ويؤكده الـ webhook لاحقًا.

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

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

Payment was cancelled. Please click "Pay Now" to try again.

Payment could not be completed. Please try again.

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. تم حظر نص النافذة المنبثقة؛ تطلب الرسالة التحقق من الاتصال وتعطيل مانعات المحتوى وإعادة تحميل الصفحة.

في OpenCart 4، إذا أغلق المتجر طلب الدفع أو كان مدفوعًا بالفعل لسلة مختلفة (مثلًا تغيّرت السلة منذ ذلك، بما في ذلك الكمية)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order.، ويدفع الزر Confirm Order التالي طلبًا جديدًا. وفي OpenCart 4 تظهر الرسائل التي تعيد العميل إلى صفحة الدفع، مثل هذه الرسالة، وPayment session not found. Please try again. وWe could not verify your payment.، فوق صفحة الدفع.

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

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

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

حالات الطلب

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

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

Authorized Status (الافتراضي قيد الانتظار): تم تفويض الدفعة فقط (Authorize Only). حصّلها لإكمال الطلب.

On Hold (Review) Status (الافتراضي قيد الانتظار): يُضبط في هذه الحالات، ولكل منها ملاحظة: لم يتطابق المبلغ المدفوع أو العملة مع الطلب، أو تم تحصيل الدفعة لطلب ملغى، أو تعذّر التحقق من الدفعة عبر Razorpay API في تلك اللحظة. تحقّق من الطلب ثم أتمّه أو استرد الدفعة.

Cancelled Status: لا تعيد الدفعة التي تصل لاحقًا لطلب ملغى فتح الطلب تلقائيًا: لا تُحصَّل الدفعة المُفوَّضة ولا تتلقى إلا ملاحظة، بينما تضع الدفعة المحصّلة الطلب في المراجعة. لا يغيّر الإشعار المتكرر للدفعة التي سدّدت الطلب أي شيء، حتى لو ألغيت الطلب لاحقًا.

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

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

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

تبويب VibeFox Razorpay Payment

في Sales > Orders افتح طلبًا مدفوعًا عبر Razorpay. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Razorpay Payment الـ Payment ID مع تسمية Test mode للدفعات التجريبية، وRazorpay order، وStatus الدفعة، وPaid / refunded (المبلغ الذي خصمه Razorpay والمبلغ المسترد)، وزر التحصيل، ونموذج الاسترداد، وسجل الاستردادات، وRazorpay notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة. يحتاج التحصيل والاسترداد إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups).

التحصيل (Authorize Only)

افتح الطلب في Authorized Status، وانقر على Capture Razorpay payment في التبويب، ثم أكّد Capture the authorized Razorpay payment? يُحصَّل المبلغ في الوضع الذي فُوِّض فيه، ويُضبط الطلب على Order Status After Payment، دون إشعار العميل ودون تغيير المخزون، كما في تغيير الحالة يدويًا. إذا رفض Razorpay، يعرض التبويب والملاحظات Razorpay capture failed: مع السبب. يُكمل التحصيل الذي يُجرى في Razorpay Dashboard الطلب عبر الـ webhook.

الاسترداد

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

لا ترد مرتجعات المنتجات في Sales > Returns الأموال عبر Razorpay.

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

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

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

بدون مفتاح نشط، لا يظهر Razorpay للعملاء في الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. يظل مستخدم المشرف المسجّل الدخول إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع وسم (unlicensed — visible to admins only)، لتتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. في OpenCart 4 هذه المعاينة غير متاحة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تكون طريقة الدفع مخفية عن الجميع بدون مفتاح نشط. بعد فتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاص بالمشرف. أغلقه بالزر × لإخفائه مدة 7 أيام. لا تتأثر الطلبات الموجودة: تستمر الدفعات التي بدأت في التأكيد، وتعمل التحصيلات والاستردادات.

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

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

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

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

يرد الـ webhook بـ Webhook secret not configured: حقل Webhook Secret فارغ. أدخل سرّ webhook في Razorpay. سيعيد Razorpay إرسال الحدث لاحقًا.

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

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

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

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

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

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

لا يوجد نموذج تحصيل أو استرداد في التبويب: يوضح التبويب السبب: لم تُحصَّل الدفعة بعد، أو أُسترد المبلغ بالكامل، أو لا تملك مجموعة المستخدمين الخاصة بك صلاحية تعديل الإضافة، أو لم تُضبط مفاتيح الوضع الذي تمّت فيه الدفعة (The payment was made in Test mode, but the Test Key ID / Key Secret are not configured. أو الرسالة نفسها لوضع الإنتاج). أدخل مفاتيح ذلك الوضع وأعد المحاولة.

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

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

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

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