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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

4. أدخل مفاتيحك السرية، واضبط webhook في لوحة Flutterwave، وأدخل قيمة التجزئة السرية نفسها في الوحدة (راجع الإعدادات).

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

عند التثبيت تنشئ الوحدة حالتين للطلب: Awaiting Flutterwave payment وFlutterwave payment on hold. يعرض PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

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

Flutterwave

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

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

Description: النص الذي يراه العملاء أسفل طريقة الدفع أثناء إتمام الطلب. الافتراضي: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

مفاتيح API

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

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

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

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

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

Webhook

يؤكد webhook الدفعات حتى عندما لا يعود العميل إلى متجرك. في لوحة Flutterwave ضمن Settings, Webhooks، أدخل العنوان المعروض في Webhook URL في هذا القسم، وقيمة تجزئة سرية من اختيارك، سواء لوضع الاختبار أو لوضع الإنتاج. مع الروابط الودية يكون العنوان بالشكل https://your-shop/module/wcp_flutterwave_payment/webhook، وقد يتضمن رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات. تستجيب الوحدة لهذا الحدث:

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

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

Clear saved secrets: حدّد Test Secret Key أو Live Secret Key أو Secret Hash، ثم انقر Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة كما هي.

الدفع

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

Autocomplete Orders: تحصل الطلبات المدفوعة على الحالة Delivered بدلًا من Payment accepted، بتغيير واحد للحالة. الافتراضي: معطّل.

متقدم

Debug log: يسجّل أحداث واجهة Flutterwave البرمجية لأغراض تصحيح الأخطاء في logs/flwv_debug.log.php داخل مجلد الوحدة. لا يمكن فتح هذا الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا. ولا تُسجَّل المفاتيح أو التجزئة السرية أو بيانات العملاء أبدًا. الافتراضي: معطّل.

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

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

إتمام الطلب

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Flutterwave) ويؤكد. يُشترط عنوان بريد إلكتروني صالح. تُنشئ الوحدة دفعة Flutterwave بإجمالي السلة وبعملة السلة، مع البريد الإلكتروني للعميل، والهاتف واسم عنوان الفوترة، واسم متجرك وشعاره، ثم تُرسل العميل إلى صفحة الدفع الخاصة بـ Flutterwave. هناك يدفع العميل بإحدى الطرق المفعّلة في حسابك (أو المدرجة في Payment Options). لا يوجد طلب في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Flutterwave الدفع: إما عبر webhook أو عبر فحص من جهة الخادم عند عودة العميل. عندئذٍ يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية. إذا كان الدفع ما زال معلّقًا، مثل التحويل المصرفي أو دفعة USSD أو الأموال عبر الهاتف المحمول، يُنشأ الطلب بحالة Awaiting Flutterwave payment، وتعرض الصفحة 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. وإذا فشل الدفع المعلّق لاحقًا وأعاد العميل فتح صفحة التأكيد، تعرض 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 created as soon as it is confirmed — 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. تبقى السلة محفوظة، ويمكن للعميل الدفع مرة أخرى. لكل محاولة مرجعها الخاص، ويظل رابط الدفع القديم الذي يُدفع لاحقًا مقبولًا.

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

إذا تغيّرت السلة بين الدفع وتأكيده، مثلًا في تبويب آخر من المتصفح، فلن تتطابق المبالغ، وينتقل الطلب إلى Flutterwave payment on hold مع ملاحظة.

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

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

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Flutterwave ولم يدفع بعد، أو لم تؤكد Flutterwave الدفع بعد. لا توجد إلا السلة.

Payment accepted or Delivered: تم تأكيد الدفع. تُستخدم Delivered عندما يكون Autocomplete Orders مفعّلًا. يُسجَّل الدفع بمرجع Flutterwave (flw_ref) كمعرّف للمعاملة، وتعرض ملاحظة المبلغ وطريقة الدفع والمرجع والمعاملة والوضع.

Awaiting Flutterwave payment: عاد العميل بينما كان الدفع ما زال معلّقًا لدى Flutterwave. ينتقل الطلب إلى حالة الدفع المكتمل عندما تؤكد Flutterwave الدفع.

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

Payment error: أبلغت Flutterwave أن آخر محاولة دفع لطلب بانتظار الدفع فشلت أو أُلغيت. وتعرض الملاحظة السبب.

Canceled: يضبطها صاحب المتجر. إذا أبلغت Flutterwave لاحقًا عن دفع لطلب ملغى، ينتقل الطلب إلى Flutterwave payment on hold (راجع أعلاه).

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

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

كتلة Flutterwave payment

تعرض صفحة الطلب كتلة Flutterwave payment تتضمن المرجع (tx_ref)، ومعرّف المعاملة ومرجع Flutterwave، والوضع، والحالة وطريقة الدفع، والمبلغ المدفوع والمسترد، وشارة Test mode لدفعات الاختبار، وسجل الاستردادات، وFlutterwave notes الخاصة بالطلب.

الاستردادات

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

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

لا تُزامَن الاستردادات التي تُجرى في لوحة Flutterwave مع PrestaShop. حدّث حالة الطلب يدويًا عند الحاجة.

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

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

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

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

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

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

تم الدفع لكن لم يُنشأ أي طلب: webhook لا يعمل. في لوحة Flutterwave تحقّق من أن عنوان webhook مطابق تمامًا للعنوان المعروض في Webhook URL، في الوضع الذي تستخدمه (اختبار أو إنتاج)، وأن قيمة التجزئة السرية له مطابقة لـ Secret Hash في الوحدة. تبقى التحويلات المصرفية ودفعات USSD والأموال عبر الهاتف المحمول المعلّقة معلّقة حتى تؤكدها Flutterwave. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع. فعّل Debug log وراجع الحقل Log في صفحة الوحدة.

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

يردّ webhook بالرسالة Verification failed أو Busy, retry later أو Order could not be created, retry later: تعذّر الوصول إلى Flutterwave للتحقق من الدفع، أو أن المعاملة غير مرئية بعد، أو أن السلة كانت قيد المعالجة بطلب آخر، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد Flutterwave محاولة webhook. ويعرض السجل السبب.

يعرض عنوان webhook الرسالة Empty body في المتصفح: هذا طبيعي. يقبل العنوان webhooks الصادرة من Flutterwave فقط.

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

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

تعرض Flutterwave خطأً في صفحتها، أو يرى العميل الرسالة Flutterwave could not start the payment: قد لا يدعم حساب Flutterwave الخاص بك عملة السلة أو خيارات الدفع المحددة.

الطلب في حالة Flutterwave payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Flutterwave payment (راجع حالات الطلب)، ثم نفّذ الطلب أو استرد الدفع.

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

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

للمطوّرين: يسرد ملف README الخاص بالوحدة الخطافين actionWcpFlutterwavePaymentRequest (البيانات المرسلة إلى Flutterwave) وactionWcpFlutterwaveCurrencyDecimals (دقة العملة).

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

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

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