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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل Enable/Disable وأجرِ دفعة اختبار مع تفعيل Test mode. وعندما تكون جاهزًا، أدخل مفاتيح Live وألغِ تحديد Test mode.

الإعدادات

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

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: UPI, Cards, NetBanking.

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: Use the Test mode keys (no real money is charged). الافتراضي: مفعّل. ألغِ التحديد لقبول مدفوعات حقيقية. تستخدم مدفوعات الطلب وتحصيله واستردادته دائمًا مفاتيح الوضع الذي دُفع فيه الطلب، لذلك لا يؤثر تغيير الوضع لاحقًا في الطلبات الحالية.

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

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

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

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

الدفع

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

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

Authorize Only: يُحجز المبلغ. يُنقل الطلب إلى حالة «في الانتظار»، وتحصّل الدفعة لاحقًا بإجراء الطلب Capture Razorpay payment أو من Razorpay Dashboard. ويسترد Razorpay تلقائيًا الدفعات المُصرَّح بها التي لم تُحصَّل في الوقت المناسب.

Webhook

يؤكد webhook المدفوعات حتى لو أغلق العميل المتصفح مباشرةً بعد الدفع، ويسجّل الاستردادات التي تُجرى في Razorpay Dashboard. في Razorpay Dashboard، انتقل إلى Account & Settings > Webhooks، وأضف webhook لوضع الاختبار وآخر لوضع الإنتاج. استخدم الرابط المعروض في هذا القسم من الإعدادات. وهو بالشكل https://your-site/wc-api/razorpay_p_webhook/. انسخه تمامًا كما تعرضه الإعدادات. أدخل في Razorpay سرًّا من اختيارك واختر هذه الأحداث:

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

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

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

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

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

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

متقدم

Enable Logging: Save debug logs. يوجد السجل في WooCommerce > Status > Logs، والمصدر wcp_razorpay_payment. تُسجَّل الأخطاء والتحذيرات دائمًا؛ يضيف هذا الخيار تفاصيل التصحيح. ولا تُسجَّل المفاتيح والتوقيعات وبيانات الاتصال بالعميل أبدًا. الافتراضي: معطّل.

Delete Data on Uninstall: Remove the plugin settings and logs when the plugin is deleted (orders are never touched). الافتراضي: معطّل.

الدفع

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

بعد نجاح الدفع، تتحقق الإضافة من توقيع Razorpay، وتسترجع الدفعة من واجهة برمجة تطبيقات Razorpay، وتقارن المبلغ والعملة بالطلب. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Razorpay. ثم يرى العميل صفحة استلام الطلب. وإذا كان التوقيع صالحًا لكن تعذّر استرجاع الدفعة في تلك اللحظة، يُنقل الطلب إلى حالة «في الانتظار» ويؤكده webhook لاحقًا.

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

الرسائل التي يمكن أن يراها العميل:

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

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

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

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

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

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

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

Order statuses

Pending payment: أُنشئ طلب Razorpay ولم يدفع العميل بعد. تُضاف كل طلبات Razorpay إلى ملاحظات الطلب مع مبلغها ووضعها.

Processing or Completed: تم تحصيل الدفعة وتأكيدها، وهي الحالة الافتراضية لـ WooCommerce بعد الدفع. تعرض ملاحظة الطلب معرّف دفعة Razorpay والمبلغ وطريقة التأكيد (استدعاء مرتد أو webhook أو فحص عند العودة). ومعرّف المعاملة هو معرّف دفعة Razorpay (pay_...).

On hold: يُعيَّن في الحالات التالية، ولكل منها ملاحظة طلب: صُرِّح بالدفعة فقط (Authorize Only)، أو لم يتطابق المبلغ أو العملة المدفوعان مع الطلب، أو حُصِّلت الدفعة لطلب ملغى، أو تعذّر التحقق من الدفعة عبر واجهة Razorpay في تلك اللحظة. ويتلقى الطلب الذي هو في حالة «في الانتظار» بالفعل الملاحظة أيضًا.

Failed: وصل webhook من نوع payment.failed لطلب قيد الانتظار. تعرض الملاحظة خطأ Razorpay. ولا يزال بإمكان العميل الدفع مرة أخرى؛ ولا يتغيّر الطلب الذي فيه دفعة مُصرَّح بها أو محصّلة بالفعل.

Cancelled: نقر العميل على Cancel order، أو أُلغي الطلب من قبلك، أو بسبب انتهاء مهلة حجز المخزون في WooCommerce. ولا تعيد الدفعة التي تصل لاحقًا فتح الطلب تلقائيًا: فالدفعة المُصرَّح بها لا تُحصَّل، والدفعة المحصّلة تنقل الطلب إلى حالة «في الانتظار» لمراجعتك.

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

التحصيل (Authorize Only)

افتح الطلب في حالة «في الانتظار»، واختر Capture Razorpay payment في Order actions، ثم انقر على زر التحديث. تُحصَّل الدفعة في الوضع الذي صُرِّح بها فيه، ويصبح الطلب مدفوعًا. وإذا رفض Razorpay، تعرض ملاحظة الطلب Razorpay capture failed: مع السبب. ويُكمل التحصيل الذي يُجرى من Razorpay Dashboard الطلب عبر webhook.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via متبوعًا بعنوان طريقة الدفع. تُدعم الاستردادات الكاملة والجزئية. ويُرسَل الاسترداد بمفاتيح الوضع الذي تمّت به الدفعة. وإذا لم يقبل Razorpay الاسترداد، تعرض WooCommerce Razorpay refund failed: مع السبب، ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف استرداد Razorpay والمبلغ والحالة.

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

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

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

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

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

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

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

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

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

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

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

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

الطلب في حالة On hold: اقرأ ملاحظة الطلب. صُرِّح بالدفعة فقط (استخدم Capture Razorpay payment)، أو لم يتطابق المبلغ أو العملة مع الطلب، أو وصلت الدفعة لطلب ملغى، أو تعذّر التحقق منها عبر واجهة Razorpay في تلك اللحظة وهي تنتظر webhook.

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

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

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

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

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

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

Razorpay علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ Razorpay ولا معتمدة من قبلها.