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

المتطلبات

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

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

حساب Flutterwave: تحتاج إلى المفاتيح السرية لحساب Flutterwave الخاص بك، من لوحة تحكم Flutterwave تحت Settings وAPI keys: FLWSECK_TEST-… لوضع الاختبار وFLWSECK-… للوضع الحي. تُستخدم المفاتيح السرية فقط. المفاتيح العامة ومفاتيح التشفير غير مطلوبة. كما تُعدّ webhook مع secret hash من اختيارك (انظر Configuration).

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

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل مفاتيحك السرية، واضبط الـ webhook في لوحة تحكم Flutterwave، وأدخل secret hash نفسه في الإضافة (انظر Configuration).

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

OpenCart 4

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

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

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

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

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

الإعدادات

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

عند الحفظ يجب أن يكون Title بين 1 و128 حرفًا، ويجب أن يكون Sort Order فارغًا أو عددًا صحيحًا، ويجب أن يكون Total فارغًا أو رقمًا 0 أو أكبر، ويجب أن تكون منطقة Geo Zone وحالات الطلبات المختارة موجودة. وإلا فلن يُحفظ شيء وتعرض الصفحة ما يجب تصحيحه. مشكلات المفاتيح لا تمنع الحفظ.

Flutterwave

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

Title: عنوان طريقة الدفع الذي يراه العميل أثناء الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Flutterwave. مطلوب، حتى 128 حرفًا.

Description: وصف طريقة الدفع الذي يظهر في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

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

Geo Zone: اعرض Flutterwave فقط لعناوين الدفع الواقعة في منطقة Geo Zone المختارة. الافتراضي: All zones. تُضبط مناطق Geo Zone في System > Localisation > Geo Zones.

Total: إجمالي الشراء، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Flutterwave. اتركه فارغًا لعرض Flutterwave لأي إجمالي.

مفاتيح API

انسخ المفاتيح السرية من لوحة تحكم Flutterwave تحت Settings وAPI keys (يحتوي القسم على رابط). لوضع الاختبار ولوضع الحي مفاتيح مختلفة.

Live mode: يقبل المدفوعات الحقيقية. أوقفه للعودة إلى وضع الاختبار. يستخدم وضع الاختبار المفتاح السري للاختبار ولا يُخصم أي مبلغ حقيقي. ويستخدم الوضع الحي المفتاح السري الحي. الافتراضي: معطّل (وضع الاختبار). وأثناء تفعيل وضع الاختبار يرى العميل TEST MODE - no real payments will be processed. في خطوة Confirm Order.

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

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

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

Webhook

يؤكد الـ webhook المدفوعات حتى عندما لا يعود العميل إلى متجرك. في لوحة تحكم Flutterwave تحت Settings وWebhooks، أدخل الرابط المعروض في Webhook URL في هذا القسم وsecret hash من اختيارك، في وضع الاختبار وفي الوضع الحي. في OpenCart 3 يبدو الرابط هكذا: https://your-store/index.php?route=extension/payment/wcp_flutterwave_payment/webhook، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_flutterwave_payment/payment/wcp_flutterwave_payment.webhook. ويُبنى من عنوان متجرك. يجب أن يكون متاحًا من الإنترنت عبر HTTPS. انسخ الرابط تمامًا كما تعرضه الإعدادات. تتفاعل الإضافة مع هذا الحدث:

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

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

الدفع

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

Autocomplete Orders: تحصل الطلبات المدفوعة على Complete Order Status بدلًا من Paid Order Status. الافتراضي: معطّل.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). لا يحصل على حالة إلا بعد أن تؤكد Flutterwave الدفعة عبر الـ API. تعرض كل حقل أدناه حالات طلبات OpenCart لديك.

Paid Order Status: الحالة بعد تأكيد الدفعة. الافتراضي: Processing.

Complete Order Status: الحالة بعد تأكيد الدفعة عندما تكون Autocomplete Orders مفعّلة. الافتراضي: Complete.

Awaiting Payment Status: عاد العميل بينما الدفعة ما زالت معلّقة لدى Flutterwave (تحويل بنكي أو USSD أو mobile money). يحصل الطلب على هذه الحالة حتى يؤكدها الـ webhook. الافتراضي: Pending.

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

Failed Status: دفعة معلّقة لطلب في انتظار الدفع فشلت لدى Flutterwave. الافتراضي: Failed.

Refunded Status: تُضبط بعد استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: Refunded.

متقدم

Debug log: يسجّل أحداث واجهة Flutterwave البرمجية لأغراض التصحيح في flwv_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغ 5 ميغابايت يُنقل إلى flwv_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تُسجَّل المفاتيح وsecret hash وبيانات العملاء أبدًا. الافتراضي: معطّل.

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

Delete data on uninstall: يحذف إعدادات الإضافة وسجلاتها عند إلغاء تثبيت الإضافة. بيانات الدفع المحفوظة على الطلبات تبقى دائمًا. الافتراضي: معطّل.

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Flutterwave). في خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the Flutterwave checkout page. ينشئ OpenCart الطلب في هذه الخطوة، ما زال بدون حالة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، ثم يضغط Confirm Order في أسفل صفحة الدفع. عندما يضغط العميل Confirm Order، تُنشئ الإضافة دفعة Flutterwave بإجمالي الطلب بعملة الطلب، مع بريد العميل، والهاتف والاسم من عنوان الدفع، واسم متجرك وشعاره، والعبارة Payment for order مع رقم الطلب، وترسل العميل إلى صفحة الدفع في Flutterwave. يُشترط بريد إلكتروني صالح. هناك يدفع العميل بإحدى الطرق المفعّلة في حسابك (أو المذكورة في Payment Options).

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

إذا تعذّر الوصول إلى Flutterwave عند عودة العميل، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by Flutterwave. Your order will be confirmed as soon as Flutterwave confirms it — please do not pay again. مع الزرين Check again وBack to checkout. يضبط الـ webhook حالة الطلب فور وصوله.

إذا رُفضت الدفعة، يعود العميل إلى صفحة الدفع مع 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. وإذا تعذّر التحقق من الدفعة، فالرسالة Payment verification failed. Please contact support. يبقى الطلب بلا حالة وتُحفظ السلة، فيستطيع العميل الدفع مرة أخرى. في OpenCart 4 تُعرض هذه الرسائل فوق صفحة الدفع.

ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order؛ أما OpenCart 4 فيحدّث الطلب الحالي في الدفع، فتدفع المحاولة الجديدة الطلب نفسه. ولكل محاولة مرجعها الخاص. قبل أي دفعة جديدة تُفحص مع Flutterwave الدفعات المفتوحة والمعلّقة لهذا الطلب ولطلبات أخرى من السلة نفسها خلال آخر 24 ساعة. إذا تبيّن أن إحداها مدفوعة، تؤكد طلبها ويُنقل العميل إلى صفحة النجاح دون أن يدفع مرة أخرى. وإذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل عبر Flutterwave، لا تُبدأ دفعة جديدة أيضًا. ويُقبل رابط دفع أقدم إذا دُفع لاحقًا. وإذا دُفعت السلة نفسها مرتين، مثلًا من تبويبين مفتوحين في المتصفح، فلا تُعطي إلا الدفعة الأولى طلبها حالة: يبقى الطلب الآخر بلا حالة، ويحصل الطلب المدفوع على ملاحظة تطلب منك استرداد الدفعة الثانية من لوحة تحكم Flutterwave.

يحتفظ OpenCart 4 بالطلب في الدفع حتى تُعرض صفحة النجاح. إذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا فشلت دفعته المعلّقة أو ألغيته)، يُعاد العميل إلى صفحة الدفع مع رسالة الدفعة المرفوضة، ويدفع Confirm Order التالي طلبًا جديدًا من السلة. إذا أغلقت الطلب بعد دفعه، تكون الرسالة This order can no longer be paid (it was closed by the store). Please confirm your order again. وإذا كان ذلك الطلب مدفوعًا بالفعل لكن السلة تغيّرت منذ ذلك، بما في ذلك كمية جديدة، فالرسالة Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. لا يُعرض الطلب المدفوع أبدًا على أنه مدفوع لسلة مختلفة.

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

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

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

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

حالات الطلب

No status (missing order): أُرسل العميل إلى Flutterwave ولم يدفع، أو رُفضت الدفعة أو أُلغيت، أو لم تؤكد Flutterwave الدفعة بعد. في Sales > Orders تظهر هذه الطلبات فقط عند ضبط الفلتر Order Status على Missing Orders.

Paid Order Status (default Processing) or Complete Order Status (default Complete): تم تأكيد الدفعة. تُستخدم Complete Order Status عندما تكون Autocomplete Orders مفعّلة. تعرض الملاحظة المبلغ وطريقة الدفع ومرجع Flutterwave والمعاملة والوضع.

Awaiting Payment Status (default Pending): عاد العميل بينما الدفعة ما زالت معلّقة لدى Flutterwave. ينتقل الطلب إلى حالة الدفع عندما تؤكد Flutterwave الدفعة.

On Hold (Review) Status (default Pending): المبلغ أو العملة المتحقَّق منهما لا يطابقان الطلب، أو وصلت الدفعة بعد أن أُعطي الطلب حالة بدون دفع، مثل Canceled. يُسجَّل المبلغ والعملة المدفوعان فعليًا وتشرح الملاحظة السبب. أكمل الطلب أو استرد الدفعة. وإذا كان للطلب حالة معالجة أخرى من قبل، تُضاف ملاحظة فقط.

Failed Status (default Failed): أبلغت Flutterwave بفشل أو إلغاء آخر محاولة دفع لطلب في انتظار الدفع. تعرض الملاحظة السبب. لا تتغير المحاولات الأقدم ولا الطلبات المدفوعة.

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

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

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

تبويب VibeFox Flutterwave Payment

في Sales > Orders افتح طلبًا مدفوعًا عبر Flutterwave. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Flutterwave Payment Transaction reference وMode (Test أو Live) وحالة الدفع Status وTransaction ID وFlutterwave reference وPayment type والمبالغ Paid / refunded ونموذج الاسترداد وسجل الاستردادات وFlutterwave notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

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

لا ترسل مرتجعات المنتجات في Sales > Returns أي أموال عبر Flutterwave. الاستردادات التي تتم في لوحة تحكم Flutterwave لا تُزامَن مع OpenCart. حدّث حالة الطلب يدويًا عند الحاجة.

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

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

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

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

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

Flutterwave does not appear at checkout: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن المفتاح السري للوضع الحالي مُدخل ويطابق الوضع: مفتاح اختبار (FLWSECK_TEST-…) في وضع الاختبار، ومفتاح حي (FLWSECK-…) في الوضع الحي. تعرض صفحة الإعدادات تحذيرًا في حال خلاف ذلك. وتأكد أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

The payment went through, but the order stays without a status: الـ webhook لا يعمل. في لوحة تحكم Flutterwave تحقق من أن رابط الـ webhook هو تمامًا الرابط المعروض في Webhook URL، في الوضع الذي تستخدمه (اختبار أو حي)، وأن secret hash فيه مطابق لـ Secret Hash في الإضافة. تبقى التحويلات البنكية وUSSD وmobile money معلّقة حتى تؤكدها Flutterwave. يحصل الطلب على حالته أيضًا عندما يعود العميل إلى المتجر بعد الدفع. فعّل Debug log وانظر إلى حقل Log في صفحة الإضافة.

Webhook answers Invalid hash or Secret hash not configured: secret hash في لوحة تحكم Flutterwave يختلف عن الذي في الإضافة، أو لا يوجد أي secret hash في الإضافة. أدخل القيمة نفسها في الموضعين.

Webhook answers Verification failed, Busy, retry later or Order could not be updated, retry later: تعذّر الوصول إلى Flutterwave للتحقق من الدفعة، أو المعاملة غير ظاهرة بعد، أو كان الطلب قيد المعالجة بطلب آخر في اللحظة نفسها، أو تعذّر ضبط حالته. تعيد Flutterwave إرسال الـ webhook. يوضح السجل السبب.

The webhook URL shows Empty body in the browser: هذا طبيعي. يقبل الرابط الـ webhooks الواردة من Flutterwave فقط.

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

The customer sees This payment method is not available: جلسة الدفع لم تعد تطابق الطلب، أو تم إيقاف طريقة الدفع في هذه الأثناء. يعيد العميل تحميل صفحة الدفع.

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

Flutterwave shows an error on its page, or the customer sees Flutterwave could not start the payment: قد لا يدعم حساب Flutterwave عملة الطلب أو خيارات الدفع المختارة.

Order is in the on hold status after payment: اقرأ الملاحظات في تبويب VibeFox Flutterwave Payment (انظر حالات الطلب)، ثم أكمل الطلب أو استرد الدفعة.

No refund form in the tab: يوضح التبويب السبب: الدفعة غير مؤكدة بعد، أو مستردة بالكامل، أو مجموعة مستخدمك ليس لديها صلاحية تعديل الإضافة، أو المفتاح السري لوضع الدفعة غير مضبوط.

Refund fails with a message about the mode: تمت الدفعة في وضع الاختبار أو الوضع الحي، والمفتاح السري لذلك الوضع غير مضبوط. أدخله وأعد المحاولة.

Refund answers Another operation on this payment is running: كان استرداد آخر لهذا الطلب يُرسَل في تلك اللحظة. انتظر قليلًا، وتحقق من سجل الاستردادات، وأعد المحاولة عند الحاجة.

للمطوّرين: تطلق الإضافة أحداث OpenCart التالية flwv_payment_request (البيانات المرسلة إلى Flutterwave) وflwv_currency_decimals (دقة العملة).

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

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

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

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