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

المتطلبات

WordPress: 5.8 أو أحدث.

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

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

حساب Flutterwave: تحتاج إلى المفاتيح السرية لحسابك لدى Flutterwave، من لوحة تحكم Flutterwave ضمن Settings، ثم API keys: ‏FLWSECK_TEST-… لوضع الاختبار وFLWSECK-… لوضع الإنتاج. لا تُستخدم إلا المفاتيح السرية. لا حاجة إلى المفاتيح العامة أو مفاتيح التشفير. وعليك أيضًا إعداد webhook بقيمة تجزئة سرية تختارها (انظر «الإعداد»).

العملات: يُحصَّل مبلغ الطلب دائمًا بعملة الطلب. لا تقيّد الإضافة البلدان أو العملات؛ وتعرض Flutterwave خطأ إذا كان حسابك لا يدعم العملة.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل مفاتيحك السرية، وأعدّ webhook في لوحة تحكم Flutterwave، وأدخل قيمة التجزئة السرية نفسها في الإضافة (انظر «الإعداد»).

6. شغّل Enable/Disable، واختبر دفعة في وضع الاختبار، ثم حدّد Live mode.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Flutterwave. تعرض الصفحة فوق الحقول Live mode: real payments are accepted. أو Test mode: no real money is charged. وتحذّرك إذا كان المفتاح السري للوضع الحالي فارغًا، أو احتوى حقل مفتاح الإنتاج على مفتاح اختبار (FLWSECK_TEST-…) في وضع الإنتاج، أو احتوى حقل مفتاح الاختبار على مفتاح إنتاج (FLWSECK-…) في وضع الاختبار؛ وتُخفى طريقة الدفع عند إتمام الشراء حتى تُصحَّح المشكلة. وتحذّرك أيضًا عند عدم تعيين قيمة تجزئة سرية لـ webhook: تُرفض webhooks حينئذ، ولا تُؤكَّد المدفوعات إلا عند عودة العميل إلى متجرك. في قائمة طرق الدفع، تُعلَّم Flutterwave بأنها تحتاج إلى إعداد حتى يتوفر مفتاح سري للوضع الحالي، وتعرض شارة وضع الاختبار في ذلك الوضع.

عام

Enable/Disable: يشغّل Enable Flutterwave Payment طريقة الدفع أو يوقفها. الافتراضي: off.

Title: عنوان طريقة الدفع الذي يراه العملاء عند إتمام الشراء. الافتراضي: Flutterwave.

Description: النص الذي يراه العملاء عند إتمام الشراء. الافتراضي: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

مفاتيح API

انسخ المفاتيح السرية من لوحة تحكم Flutterwave ضمن Settings، ثم API keys. يختلف مفتاح وضع الاختبار عن مفتاح وضع الإنتاج.

Live mode: Accept real payments (uncheck for test mode). يستخدم وضع الاختبار المفتاح السري للاختبار، ولا تُخصم أموال حقيقية. ويستخدم وضع الإنتاج المفتاح السري للإنتاج. الافتراضي: off (وضع الاختبار).

Test Secret Key: المفتاح السري للاختبار في Flutterwave ‏(FLWSECK_TEST-...).

Live Secret Key: المفتاح السري للإنتاج في Flutterwave ‏(FLWSECK-...).

webhook

يؤكد webhook المدفوعات حتى إذا لم يعد العميل إلى متجرك. في لوحة تحكم Flutterwave ضمن Settings، ثم Webhooks، أدخل Webhook URL المعروض في هذا القسم وقيمة تجزئة سرية تختارها، في وضع الاختبار ووضع الإنتاج. يكون عنوان URL بالشكل https://your-site/wc-api/flw_p_webhook/. تستجيب الإضافة لهذا الحدث:

تُتجاهل الأحداث الأخرى.

Secret Hash: قيمة التجزئة السرية لـ webhook. يجب أن تطابق القيمة الموجودة في إعدادات webhook بلوحة تحكم Flutterwave. ترسلها Flutterwave مع كل webhook. وتُرفض webhooks التي لا تحمل قيمة تجزئة سرية صالحة. دون webhook، لا يُؤكَّد الدفع إلا عند عودة العميل إلى متجرك.

الدفع

Payment Options: طرق الدفع التي تُعرض في صفحة Flutterwave، مفصولة بفواصل، مثل card, banktransfer, ussd, mobilemoney. اترك الحقل فارغًا لعرض جميع الطرق المفعّلة في حسابك. تُنقَّح القائمة عند الحفظ.

Autocomplete Orders: Automatically mark orders as completed after successful payment. إذا فُعّل، تُضبط الطلبات بعد الدفع على «مكتمل» بدلًا من «قيد التنفيذ»، بتغيير واحد للحالة. الافتراضي: off.

متقدم

Debug log: يُسجِّل Log Flutterwave API events for debugging في WooCommerce > Status > Logs، بالمصدر wcp_flutterwave_payment. تُسجَّل الأخطاء دائمًا. ولا تُسجَّل المفاتيح أو بيانات العملاء أبدًا. الافتراضي: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. لا يؤدي تعطيل الإضافة إلى حذف أي شيء. وتُحفظ دائمًا بيانات الدفع المسجَّلة في الطلبات. الافتراضي: off.

إتمام الشراء

يختار العميل طريقة الدفع (افتراضيًا Flutterwave) ويقدّم الطلب. في وضع الاختبار، تعرض صفحة الدفع TEST MODE - no real payments will be processed. يلزم بريد إلكتروني صالح للفوترة. تنشئ الإضافة دفعة Flutterwave بإجمالي الطلب وبعملة الطلب، مع بريد العميل الإلكتروني وهاتفه واسمه واسم موقعك وشعاره، وترسل العميل إلى صفحة الدفع لدى Flutterwave. وهناك يدفع بإحدى الطرق المفعّلة في حسابك (أو المدرجة في Payment Options).

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Flutterwave: عبر webhook أو فحص من جهة الخادم عند عودة العميل. إذا لم يُؤكَّد الدفع بعد، مثل تحويل مصرفي أو دفعة USSD أو أموال عبر الهاتف المحمول ما زالت معلّقة، تعرض صفحة استلام الطلب Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. وإذا وصلت الأموال لكن الإضافة وضعت الطلب «قيد الانتظار» للمراجعة، مثلًا لأن المبلغ المدفوع لا يطابق الطلب، تعرض الصفحة Your payment was received and your order is being reviewed. We will contact you if anything is needed.

إذا رُفض الدفع، يعود العميل إلى صفحة الدفع (أو صفحة Pay for order) مع Your payment was declined. You can try again or choose another payment method. وإذا ألغى العميل في صفحة Flutterwave، يُلغى الطلب الذي قُدّم عند إتمام الشراء، ويبقى الطلب المنشأ يدويًا غير مدفوع، وتكون الرسالة Payment was cancelled. You can try again or choose another payment method. وإذا لم يكتمل الدفع، تكون الرسالة The payment was not completed. You can try again or choose another payment method.

يمكن للعميل إعادة محاولة دفع طلب غير مدفوع. لكل محاولة مرجع خاص بها، ويُقبل رابط دفع قديم دُفع لاحقًا. إذا تعذّر على Flutterwave بدء الدفع، يرى العميل رسالة قصيرة، مثل Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

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

تقبل الإضافة المدفوعات لمرة واحدة فقط. ولا تتضمن دفعًا مضمّنًا أو في نافذة منبثقة داخل موقعك، ولا بطاقات محفوظة أو اشتراكات أو مدفوعات مقسّمة أو خطط دفع. لا يمكن إلغاء روابط الدفع المستضافة عبر Flutterwave API، ولذلك يمكن دفع رابط قديم لطلب.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Flutterwave ولم يدفع بعد، أو لا يزال الدفع معلّقًا لدى Flutterwave.

Processing or Completed: تأكد الدفع. تُستخدم حالة «مكتمل» عند تشغيل Autocomplete Orders (وتصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط «مكتمل» أيضًا، وهو السلوك الافتراضي في WooCommerce). تعرض ملاحظة الطلب المبلغ وطريقة الدفع ومرجع Flutterwave والمعاملة والوضع. معرّف معاملة الطلب هو مرجع Flutterwave.

On hold after payment: لم يطابق المبلغ أو العملة اللذان جرى التحقق منهما الطلب، أو وصل الدفع بعد إلغاء الطلب. تشرح الملاحظة السبب. نفّذ الطلب أو أعد المبلغ. ولا يُعيد webhook مُرسَل مجددًا فتح طلب مسترد أو ملغى.

Failed: أبلغت Flutterwave بأن أحدث محاولة دفع لطلب معلّق قد فشلت أو أُلغيت. تعرض الملاحظة السبب.

Cancelled: ألغى العميل في صفحة Flutterwave بعد تقديم الطلب عند إتمام الشراء، أو أُلغي الطلب بواسطتك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce.

إذا وردت دفعة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد الدفعة المكررة في لوحة تحكم Flutterwave.

الاستردادات

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

لا تُزامَن الاستردادات التي تُجرى في لوحة تحكم Flutterwave مع WooCommerce. عند الحاجة، أنشئ استردادًا يدويًا في WooCommerce دون Refund via Flutterwave.

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

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

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

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

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

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

لا تظهر Flutterwave عند إتمام الشراء: تحقق من أن الترخيص نشط، وأن Enable/Disable مشغّل، وأن المفتاح السري للوضع الحالي مُدخل ويطابق الوضع: مفتاح اختبار (FLWSECK_TEST-…) في وضع الاختبار، ومفتاح إنتاج (FLWSECK-…) في وضع الإنتاج. وإلا فستعرض صفحة الإعدادات تحذيرًا.

تم الدفع، لكن الطلب يظل Pending payment: لا يعمل webhook. في لوحة تحكم Flutterwave، تحقق من أن عنوان URL الخاص بـ webhook يطابق تمامًا المعروض في الإعدادات، في الوضع الذي تستخدمه (اختبار أو إنتاج)، وأن قيمة التجزئة السرية تطابق Secret Hash في الإضافة. تظل التحويلات المصرفية وUSSD والأموال عبر الهاتف المحمول معلّقة حتى تؤكدها Flutterwave. شغّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_flutterwave_payment.

يرد webhook بالرسالة Invalid hash أو Secret hash not configured: تختلف قيمة التجزئة السرية في لوحة تحكم Flutterwave عن القيمة في الإضافة، أو لا توجد قيمة في الإضافة. أدخل القيمة نفسها في الموضعين.

يرد webhook بالرسالة Verification failed أو Busy, retry later: تعذّر الاتصال بـ Flutterwave للتحقق من الدفع، أو لم تظهر المعاملة بعد، أو كان طلب آخر يحدّث الطلب. تعيد Flutterwave محاولة إرسال webhook.

يرى العميل Payment gateway is not properly configured: المفتاح السري للوضع الحالي مفقود أو يخص الوضع الآخر.

يرى العميل We could not match this payment to an order: يحمل رابط العودة مرجعًا لم ينشئه هذا المتجر. إذا خُصم المبلغ من العميل، فابحث عن الدفع في لوحة تحكم Flutterwave.

تعرض Flutterwave خطأ في صفحتها: قد لا يدعم حسابك في Flutterwave عملة الطلب أو خيارات الدفع المحددة.

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. لم يطابق المبلغ أو العملة اللذان جرى التحقق منهما الطلب، أو وصل الدفع بعد إلغاء الطلب. نفّذ الطلب أو أعد المبلغ.

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

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

للمطورين، تسرد وثائق الإضافة المرشحات flw_p_payment_request (البيانات المرسلة إلى Flutterwave)، وflw_p_currency_decimals (دقة العملة)، وflw_p_icon (أيقونة الدفع).

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

يؤدي تعطيل الإضافة إلى الاحتفاظ بجميع البيانات. لإزالتها، عطّلها واحذفها في صفحة Plugins. يُزال دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. ولا تُزال إعدادات بوابة الدفع والسجلات إلا إذا كان Delete data on uninstall مشغّلًا. وإلا فتبقى لإعادة التثبيت لاحقًا. تُحفظ دائمًا بيانات Flutterwave المسجَّلة في الطلبات. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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