VibeFox Windcave for PrestaShop — المساعدة
المتطلبات
PrestaShop: من 8.0 إلى 9.x.
PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.
حساب Windcave: تحتاج إلى حساب تاجر لدى Windcave ببيانات اعتماد REST API: اسم مستخدم API ومفتاح API. تصدر Windcave هذه البيانات بشكل منفصل لبيئة الاختبار UAT (uat.windcave.com) ولبيئة الإنتاج (sec.windcave.com). اطلبها من دعم Windcave أو من مدير حسابك. لا تعمل مفاتيح PxPay مع هذه الوحدة. يجب تفعيل طرق الدفع التي ترغب في عرضها (البطاقات والمحافظ الإلكترونية وغيرها) في حسابك لدى Windcave.
الإشعار: يجب أن يكون متجرك متاحًا من الإنترنت حتى تتمكن Windcave من إرسال إشعار الدفع. لا يلزم إعداد أي شيء في Windcave لذلك.
مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد فقط.
التثبيت
1. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.
2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Windcave Payment Gateway في قائمة الوحدات وانقر على Configure.
3. أدخل مفتاح ترخيص VibeFox في حقل License key ضمن كتلة الترخيص أعلى صفحة Configure، ثم انقر على Activate (انظر مفتاح الترخيص).
4. أدخل اسم مستخدم REST API ومفتاحه: بيانات اعتماد UAT لوضع الاختبار، وبيانات اعتماد الإنتاج للمدفوعات الفعلية (راجع الإعدادات).
5. اختر نوع المعاملة وطرق الدفع، ثم فعّل Enable/Disable وانقر على Save. أجرِ دفعة تجريبية مع تفعيل Test mode، ثم أوقف Test mode لقبول المدفوعات الحقيقية.
عند التثبيت تنشئ الوحدة حالة الطلب Windcave payment on hold. تتيح PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.
الإعدادات
جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. وبينما يكون وضع الاختبار مفعّلًا، تعرض الصفحة الرسالة وضع الاختبار مفعّل: تذهب المدفوعات إلى بيئة Windcave UAT ولا يُخصم أي مبلغ حقيقي. وإذا كانت الوحدة مفعّلة لكن الوضع الحالي لا يحتوي على اسم مستخدم أو مفتاح API، تحذّر الصفحة من أن طريقة الدفع مخفية في الدفع، على سبيل المثال: Windcave مفعّلة لكن اسم مستخدم / مفتاح UAT API فارغان — طريقة الدفع مخفية في الدفع. لا يمكن ترك Title فارغًا: عندها تعرض الصفحة الرسالة أدخل عنوانًا لطريقة الدفع. ولا يُحفظ أي شيء.
Windcave
Enable/Disable: Enable Windcave payments يفعّل طريقة الدفع أو يوقفها. الافتراضي: معطّل.
Title: اسم طريقة الدفع الذي يراه العميل عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit/Debit Card (Windcave). حقل إلزامي.
Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: You will be redirected to the secure Windcave payment page to complete your payment.
Windcave REST API
أدخل بيانات اعتماد REST API الصادرة عن Windcave (اسم المستخدم ومفتاح API، وليس مفاتيح PxPay). يمكن حفظ بيانات الإنتاج وبيانات UAT جنبًا إلى جنب. يستخدم وضع الاختبار بيانات UAT فقط، ويستخدم الوضع الفعلي بيانات الإنتاج فقط. يحتوي القسم على رابط لوثائق Windcave REST API.
Test mode: يستخدم بيئة الاختبار UAT من Windcave (uat.windcave.com). لا يُخصم أي مبلغ حقيقي. تستخدم المدفوعات الجديدة بيانات UAT. تُرسل الاستردادات والتحصيلات دائمًا إلى البيئة التي دُفع فيها الطلب. الافتراضي: معطّل.
Production API username: اسم مستخدم REST API الخاص بـ sec.windcave.com.
Production API key: مفتاح REST API الخاص بـ sec.windcave.com.
UAT API username: اسم مستخدم REST API الخاص بـ uat.windcave.com (وضع الاختبار).
UAT API key: مفتاح REST API الخاص بـ uat.windcave.com (وضع الاختبار).
لا تُعرض مفاتيح API المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها.
Clear saved keys: حدّد Production API key أو UAT API key ثم انقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.
Notification URL: يعرض العنوان الذي ترسل إليه Windcave إشعار الدفع (Fail-Proof Result Notification). مع الروابط الودّية يظهر بالشكل التالي: https://your-shop/module/wcp_windcave_payment_gateway/notification. لا يوجد ما يُضبط في Windcave: ترسل الوحدة عناوين العودة وعنوان الإشعار هذا مع كل جلسة دفع. يجب أن يكون العنوان متاحًا من الإنترنت، وإلا فلن تُؤكَّد الطلبات إلا عندما يعود العميل من Windcave. لا توقّع Windcave عودة العميل ولا الإشعار، لذلك لا تثق الوحدة بهما وحدهما أبدًا: فهي تقرأ دائمًا نتيجة الجلسة من Windcave REST API باستخدام بيانات اعتماد البيئة التي أُنشئت فيها الجلسة.
Payment
Transaction type: طريقة تحصيل الدفعة. الافتراضي: Purchase.
Payment methods: الطرق التي تظهر في صفحة دفع Windcave: Cards وAccount2Account (تحويل بنكي من نيوزيلندا) وApple Pay وGoogle Pay وPayPal وAlipay وWeChat Pay وUnionPay وInterac وhumm. لتحديد أكثر من طريقة، استخدم Ctrl أو Cmd مع النقر. يجب تفعيل الطرق في حسابك لدى Windcave. اترك الحقل فارغًا لعرض كل الطرق المفعّلة في الحساب. الافتراضي: Cards.
Advanced
Debug log: يسجّل طلبات API وأحداث الدفع في logs/windcave_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. وما دام هذا الخيار معطّلًا، تُسجَّل الأخطاء والتحذيرات فقط. لا تُسجَّل مفاتيح API ولا بيانات البطاقات ولا البيانات الشخصية للعملاء أبدًا. الافتراضي: معطّل.
Log: يعرض حجم السجل وآخر إدخالاته. انقر على Clear log لإفراغه.
Clean uninstall: يحذف إعدادات الوحدة وسجلاتها عند إلغاء تثبيتها. بيانات الدفع المحفوظة مع الطلبات (معرّفات معاملات Windcave اللازمة للاستردادات) تبقى محفوظة دائمًا. الافتراضي: معطّل.
يظهر رقم إصدار الوحدة أسفل الصفحة.
الدفع
في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (Windcave)) مع وصفها. وفي وضع الاختبار يرى العميل أيضًا Test mode: تذهب المدفوعات إلى بيئة Windcave UAT ولا يُخصم أي مبلغ حقيقي. بعد التأكيد تُنشئ الوحدة جلسة دفع Windcave لإجمالي السلة بعملة السلة، وتوجّه العميل إلى Windcave Hosted Payment Page. يُرسل رقم السلة بوصفه مرجع التاجر، مع لغة المتجر واسم العميل وبريده الإلكتروني وهاتفه وعنوان الفوترة (وعنوان التوصيل عندما تحتاج السلة إلى شحن). لا يوجد طلب بعد في هذه المرحلة.
بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب مدفوعًا إلا بعد أن تؤكد Windcave ذلك: تطلب الوحدة من Windcave REST API نتيجة الجلسة، سواء عند عودة العميل أو عند وصول إشعار Windcave. يضمن القفل لكل سلة أن يُطبَّق الدفع مرة واحدة فقط. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة مع الرسالة Your Windcave payment has been received. أما الطلب المعلّق (تفويض أو دفعة لا تطابق السلة) فتعرض الصفحة Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.
إذا عاد العميل بعد دفعة معتمدة لكن النتيجة ما زالت غير معروفة، تعرض صفحة Payment confirmation الرسالة We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. وزر Check again. وينشئ الإشعار الطلب بمجرد أن تؤكد Windcave الدفعة.
إذا عاد العميل دون إتمام الدفع، تعرض صفحة الدفع إحدى هذه الرسائل. تُحفظ السلة.
يمكن للعميل إعادة المحاولة بالسلة نفسها. تتحقق المحاولة الجديدة أولًا من الجلسة السابقة: إذا كانت مدفوعة بالفعل أُنشئ الطلب ولم تبدأ دفعة ثانية؛ وإذا لم يستخدم العميل صفحة الدفع أبدًا ولم تتغير السلة، يُعاد توجيهه إلى الصفحة نفسها. وإذا كانت الدفعة السابقة قيد التأكيد في تلك اللحظة، يرى العميل الرسالة Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.
إذا تعذّر على Windcave بدء الدفع، يبقى العميل في الدفع مع رسالة قصيرة: أن Windcave لم تتمكن من بدء الدفع بتفاصيل هذا الطلب، أو أن خدمة الدفع غير متاحة مؤقتًا. يُكتب السبب في السجل. وإذا لم تكن لدى الوضع الحالي بيانات اعتماد، يرى العميل الرسالة This payment method is not available at the moment. Please choose another payment method or contact us.
يعمل الإشعار أثناء وضع الصيانة في المتجر، ولا يتأثر بقيد الدول في متجرك.
لا تتضمن الوحدة اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة، ولا نموذج بطاقة مضمّنًا في موقعك (يدفع العميل دائمًا في صفحة Windcave)، ولا دعم لواجهة PxPay 2.0، ولا تضيف أي رسوم إضافية. إذا أضافت Windcave رسومًا، فيُطابق الطلب مع المعاملة الرئيسية.
الطلبات والاستردادات
Order statuses
No order yet: أُرسل العميل إلى Windcave ولم يدفع، أو لم تؤكد Windcave الدفعة بعد، أو رُفضت الدفعة أو أُلغيت أو انتهت صلاحيتها. لا توجد سوى السلة.
Payment accepted: أُكّدت دفعة Purchase وتطابق السلة. تُسجَّل الدفعة بمعرّف معاملة Windcave، وتعرض ملاحظة المبلغ ومعرّف المعاملة ورمز التفويض ونوع البطاقة مع رقم البطاقة المقنّع والبيئة (UAT أو الإنتاج).
Windcave payment on hold (authorised): اعتُمدت دفعة Auth لكنها لم تُحصَّل بعد. لا تُسجَّل أي دفعة على الطلب قبل تحصيلها. تشرح الملاحظة كيفية التحصيل أو التحرير.
Windcave payment on hold (does not match): أبلغت Windcave عن مبلغ أو عملة أو مرجع تاجر أو نوع معاملة يختلف عن السلة (مثلًا، عُدّلت السلة في تبويب آخر بعد بدء الدفع). تسرد الملاحظة الفروقات. وبالنسبة إلى دفعة Purchase بعملة السلة، تُسجَّل الدفعة بالمبلغ الذي خصمته Windcave فعليًا. تحقّق من الدفعة في Windcave Payline قبل الشحن، وأرجعها إذا لزم الأمر.
Refunded: أُرجعت الدفعة بالكامل أو حُرّر التفويض عبر الوحدة.
إذا وصلت دفعة معتمدة لطلب ملغى، أو وصلت دفعة معتمدة ثانية لطلب موجود مسبقًا، فلا يتغير الطلب. تطلب ملاحظة تتضمن معرّف المعاملة منك استرداد المبلغ في Windcave Payline (أو استعادة الطلب الملغى يدويًا).
Windcave payment block
تعرض صفحة الطلب كتلة Windcave payment تتضمن معرّف المعاملة ومعرّف الجلسة ونوع المعاملة وحالتها مع البيئة، والمبلغ المدفوع، ورمز التفويض والبطاقة، ومعاملة التحصيل أو الإلغاء، وإجمالي الدفع والمبلغ المسترد، وشارة Test mode (UAT) لدفعات الاختبار، وسجل الاستردادات، وجميع جلسات Windcave الخاصة بالسلة، وWindcave notes الخاصة بالطلب.
Capture (Auth mode)
بالنسبة إلى طلب في حالة Windcave payment on hold لديه تفويض لم يُحصَّل أو يُحرَّر بعد، تعرض الكتلة Capture Windcave payment مع المبلغ. انقر عليه وأكّد Capture the authorised amount through Windcave now? يُحصَّل المبلغ المفوَّض (إجمالي الطلب، ما لم تكن الدفعة غير مطابقة للطلب)، وينتقل الطلب إلى Payment accepted، وتُسجَّل الدفعة بمعرّف معاملة التحصيل. إذا لم تقبل Windcave التحصيل، تعرض الكتلة Windcave capture failed: مع السبب، ويُضاف السبب إلى الملاحظات، ويبقى الطلب معلّقًا.
Refunds
في كتلة Windcave payment أدخل المبلغ (يُملأ المبلغ غير المسترد بعد تلقائيًا)، واكتب سببًا إن شئت، ثم انقر على Refund via Windcave. أكّد السؤال Refund this amount through Windcave? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الطلبات؛ ولا يلزم الوصول إلى صفحات الوحدات. تُحتسب الاستردادات على المبلغ والعملة اللذين وافقت عليهما Windcave، لذلك بعد وجود اختلاف يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب. يُسجَّل الاسترداد بعد التحصيل على معاملة التحصيل. يُرسل الاسترداد إلى البيئة (UAT أو الإنتاج) والحساب اللذين تمت فيهما الدفعة، لذلك يجب أن تكون بيانات اعتماد تلك البيئة محفوظة. يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع معرّف معاملة Windcave. يضع الاسترداد الكامل الطلب في حالة Refunded. ولا يغيّر الاسترداد الجزئي الحالة.
بالنسبة إلى دفعة Auth لم تُحصَّل، يصبح الزر Release authorisation (void) ولا يمكن تحرير إلا المبلغ كاملًا. يؤدي المبلغ الجزئي إلى خطأ يطلب منك إرجاع المبلغ كاملًا أو تحصيل الدفعة أولًا.
إذا رفضت Windcave الاسترداد، تعرض الكتلة Windcave declined the refund: مع السبب، ولا يُسجَّل أي استرداد. وإذا كانت Windcave ما زالت تعالج الاسترداد، تعرض الكتلة Windcave has not confirmed the refund yet. See the order notes. ولا يُسجَّل الاسترداد. تحقّق من المعاملة في Windcave Payline: إذا اعتُمدت فسجّل الاسترداد يدويًا؛ وإلا فأعد المحاولة. ولا تُرسل المحاولة المكررة للاسترداد نفسه إلى Windcave مرتين.
لا تُنشئ الوحدة إشعارات دائنة. ولا تُرجع أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Windcave. ولا تُبلَّغ الاستردادات التي تتم في Windcave Payline إلى المتجر.
مفتاح الترخيص
تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Windcave Payment Gateway هي أول كتلة في Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى الأجزاء، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-windcave والرابط 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.
بدون مفتاح نشط لا يظهر Windcave للعملاء عند الدفع. إذا بدأت دفعة على أي حال، يرى العميل الرسالة This payment method is not available. Please choose another one. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager ضمن التبويب Alerts. لا تتأثر الطلبات الحالية: تظل الدفعات التي بدأت تُؤكَّد عبر الإشعار أو عودة العميل، وتعمل التحصيلات والاستردادات.
عند انتهاء صلاحية الترخيص تستمر الوحدة في العمل، لكن التحديثات والدعم تحتاج إلى تجديد. تُعاد مراجعة الحالة تلقائيًا أثناء عملك في لوحة الإدارة: مرة يوميًا خلال أول 14 يومًا بعد إدخال المفتاح، ثم مرة أسبوعيًا. لا حاجة إلى مهمة cron. إلغاء تثبيت الوحدة أو إعادة ضبطها يحذف دائمًا مفتاح الترخيص وحالة الترخيص.
استكشاف الأخطاء وإصلاحها
لا يظهر Windcave عند الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على بيانات الاعتماد الاثنتين: UAT API username وUAT API key في وضع الاختبار، وProduction API username وProduction API key في الوضع الفعلي. تعرض صفحة الإعدادات تحذيرًا عند غيابهما. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.
تمت الدفعة لكن لم يُنشأ أي طلب: لم تتمكن الوحدة بعد من الحصول على النتيجة من Windcave. انظر إلى حقل Log في صفحة الوحدة: تُسجَّل الأخطاء دائمًا، مثل عدم التمكن من التحقق من الجلسة. تحقّق من أن بيانات اعتماد بيئة الدفعة محفوظة وصحيحة. يتكرر التحقق عندما تعيد Windcave إرسال الإشعار (تردّ الوحدة بالرسالة payment could not be verified yet, retry later مع رمز خطأ، لكي تعيد Windcave المحاولة)، وعندما ينقر العميل على Check again، وعندما يبدأ العميل دفعة جديدة للسلة نفسها. يجب أن يقبل خادمك الطلبات القادمة من Windcave إلى Notification URL الظاهر في الإعدادات.
يردّ الإشعار بالرسالة order not found: لم تُنشئ هذا المتجر الجلسة، مثلًا جلسة لمتجر آخر يستخدم الحساب نفسه لدى Windcave. يُتجاهل هذا الإشعار.
Authentication failed في السجل: اسم مستخدم REST API أو المفتاح غير صحيح، أو ينتمي إلى البيئة الأخرى. تعمل بيانات UAT في وضع الاختبار فقط، وبيانات الإنتاج في الوضع الفعلي فقط. لا تعمل مفاتيح PxPay.
يرى العميل أن Windcave لم تتمكن من بدء الدفع بتفاصيل هذا الطلب: رفضت Windcave طلب الجلسة، مثلًا بسبب العملة أو بسبب طريقة دفع غير مفعّلة في حسابك. السبب الدقيق موجود في السجل.
الطلب في حالة Windcave payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Windcave payment. إما أن الدفعة تفويض Auth ينتظر التحصيل، أو أن المبلغ المدفوع أو العملة أو مرجع التاجر اختلف عن السلة. حصّل الدفعة أو شحنها أو أرجعها.
الدفعات التجريبية والدفعات الفعلية: تُفصل بيئتا UAT والإنتاج عن بعضهما. تُتحقق كل جلسة في البيئة التي أُنشئت فيها، وتذهب الاستردادات والتحصيلات إلى بيئة الدفعة، حتى لو بدّلت Test mode لاحقًا.
يفشل الاسترداد برسالة متعلقة بالبيئة: تمت الدفعة في UAT أو في الإنتاج، ولا توجد بيانات اعتماد محفوظة لتلك البيئة. أدخلها وأعد المحاولة.
لا يظهر Capture Windcave payment في كتلة الطلب: يظهر الزر فقط للطلبات في حالة Windcave payment on hold المدفوعة بـ Auth والتي لم تُحصَّل أو تُحرَّر بعد، ولا يظهر إلا للموظفين المخوّلين بتعديل الطلبات.
مكان التفاصيل: تُكتب الأخطاء والتحذيرات في السجل دائمًا؛ فعّل Debug log لتسجيل طلبات API وأحداث الدفع أيضًا.
إلغاء التثبيت
انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Windcave Payment Gateway، ثم اختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Clean uninstall مفعّلًا تُحذف إعدادات الوحدة والسجل. وإذا كان معطّلًا فتُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تبقى جلسات Windcave ومعاملاتها واستردادها وحالة الطلب Windcave payment on hold محفوظة دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا وتحصيلها بعد إعادة التثبيت. تحتفظ الطلبات الموجودة بملاحظات الدفع ومعرّفات المعاملات.
Windcave علامة تجارية تعود إلى مالكها. هذه الوحدة غير تابعة لـ Windcave ولا تحظى بتأييدها.
