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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب Windcave: تحتاج إلى حساب تاجر لدى Windcave مع بيانات اعتماد REST API: اسم مستخدم API ومفتاح API. تصدر Windcave هذه البيانات بشكل منفصل لبيئة الاختبار UAT (uat.windcave.com) ولبيئة الإنتاج (sec.windcave.com). اطلبها من دعم Windcave أو من مدير حسابك. مفاتيح PxPay لا تعمل مع هذه الإضافة. يجب تفعيل طرق الدفع التي تريد عرضها (البطاقات والمحافظ الإلكترونية وغيرها) في حسابك لدى Windcave.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل اسم مستخدم REST API ومفتاحه: بيانات اعتماد UAT لوضع الاختبار، وبيانات اعتماد الإنتاج للمدفوعات الفعلية (انظر قسم الإعداد).

6. اختر نوع المعاملة وطرق الدفع، وفعّل Enable/Disable ثم احفظ. أجرِ دفعة تجريبية مع تفعيل Test mode، ثم عطّل Test mode لتستقبل المدفوعات الفعلية.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Windcave. عندما يكون وضع الاختبار مفعّلًا، تعرض الصفحة الرسالة Test mode is on: payments go to the Windcave UAT environment and no real money is taken. وفي قائمة طرق الدفع يُعرض Windcave على أنه بحاجة إلى إعداد حتى يحتوي الوضع الحالي على اسم مستخدم API ومفتاح API معًا. يظهر إصدار الإضافة في أسفل الصفحة.

عام

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 فقط، ويستخدم الوضع الفعلي بيانات الإنتاج فقط.

Test mode: Use the Windcave UAT test environment (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 (وضع الاختبار).

الدفع

Transaction type: طريقة تحصيل الدفعة. الافتراضي: Purchase.

Purchase (capture immediately): يُخصم المبلغ عند دفع العميل.

Auth (authorise now, capture later): يُحجز المبلغ فقط. يُوضع الطلب في حالة «في الانتظار»، ثم تحصّل المبلغ باستخدام Capture Windcave payment في إجراءات الطلب، أو تحرّره بإجراء استرداد للمبلغ كاملًا. تنتهي صلاحية التفويضات غير المحصّلة بعد بضعة أيام.

Payment methods: الطرق المعروضة في صفحة الدفع لدى Windcave: Cards وAccount2Account (تحويل مصرفي في نيوزيلندا) وApple Pay وGoogle Pay وPayPal وAlipay وWeChat Pay وUnionPay وInterac وhumm. يجب تفعيلها في حسابك لدى Windcave. اترك الحقل فارغًا لعرض جميع الطرق المفعّلة في الحساب. الافتراضي: Cards.

متقدم

Debug log: Log API requests and payment events. يقع السجل في WooCommerce > Status > Logs بالمصدر wcp_windcave_payment_gateway. تُسجَّل الأخطاء والتحذيرات دائمًا؛ ويضيف هذا الخيار طلبات API وأحداث الدفع. تُخفى مفاتيح API وبيانات البطاقة والبيانات الشخصية للعملاء. الافتراضي: معطّل.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. تُحفظ دائمًا بيانات الدفع المحفوظة في الطلبات (معرّفات معاملات Windcave اللازمة للاستردادات). الافتراضي: معطّل.

عنوان URL للإشعارات

لا تحتاج إلى إعداد عنوان URL للإشعارات في Windcave. ترسل الإضافة عناوين العودة وعنوان الإشعارات مع كل جلسة دفع. يرسل Windcave الإشعار (Fail-Proof Result Notification) إلى https://your-site/wc-api/windcave_p_notification/. لا يوقّع Windcave على عودة العميل ولا على الإشعار، لذلك لا تثق الإضافة بهما وحدهما: فهي تقرأ دائمًا نتيجة الجلسة من واجهة Windcave REST API باستخدام بيانات اعتمادك لبيئة الجلسة التي أُنشئت فيها.

الدفع

يختار العميل طريقة الدفع (الافتراضية Credit/Debit Card (Windcave)) ويقدّم الطلب. تنشئ الإضافة جلسة دفع Windcave لإجمالي الطلب بعملة الطلب، وتوجّه العميل إلى Windcave Hosted Payment Page. يُرسل رقم الطلب كمرجع للتاجر، مع لغة المتجر واسم العميل وبريده الإلكتروني وهاتفه وعنواني الفوترة والشحن. في وضع الاختبار، تعرض كتلة Checkout الرسالة Test mode: payments go to the Windcave UAT environment, no real money is taken. أسفل طريقة الدفع.

بعد الدفع، يعود العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب بأنه مدفوع إلا بعد تأكيد Windcave: تطلب الإضافة من واجهة Windcave REST API نتيجة الجلسة، سواء عند عودة العميل أو عند وصول إشعار Windcave. يضمن قفل لكل طلب تطبيق الدفع مرة واحدة فقط. إذا لم تكن النتيجة معروفة بعد، تتحقق صفحة استلام الطلب منها مرة أخرى وتعرض 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.

إذا عاد العميل دون إتمام الدفع، تعرض صفحة الدفع (أو صفحة Pay for order إذا بدأت المحاولة هناك) إحدى هذه الرسائل:

Declined: تم رفض الدفع. يُرجى المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.

Cancelled or expired: لم يكتمل الدفع في صفحة Windcave. طلبك محفوظ، ويمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى.

Not confirmed yet: لم نتمكن بعد من تأكيد دفعتك. إذا أتممت الدفع، فلا تدفع مرة أخرى: ستتلقى رسالة تأكيد بالبريد الإلكتروني فور أن يؤكدها Windcave.

Return could not be processed: لم نتمكن من معالجة عودتك من صفحة الدفع. إذا خُصم منك مبلغ، فيرجى التواصل معنا قبل الدفع مرة أخرى.

لا يُفرَّغ سلة التسوق ولا يُخفَّض المخزون قبل أن يدفع العميل. يمكن للعميل أن يدفع طلبًا غير مدفوع مرة أخرى، مثلًا من صفحة Pay for order. تتحقق المحاولة الجديدة أولًا من الجلسة السابقة: إذا كانت مدفوعة بالفعل فلا تُنشأ دفعة ثانية؛ وإذا لم يستخدم العميل صفحة الدفع قط ولم يتغير الطلب، فيُعاد توجيهه إلى الصفحة نفسها. وإذا كانت الدفعة السابقة قيد التأكيد في تلك اللحظة، يرى العميل الرسالة 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.

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

لا تتضمن الإضافة اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة، ولا نموذج بطاقة مضمّنًا في موقعك (يدفع العميل دائمًا في صفحة Windcave)، ولا دعمًا لواجهة PxPay 2.0، ولا تضيف أي رسوم إضافية. إذا أضاف Windcave رسومًا إضافية، يُطابَق الطلب مع المعاملة الرئيسية.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Windcave ولم يدفع بعد، أو لم يؤكد Windcave الدفع بعد. إذا ألغى العميل أو انتهت صلاحية الجلسة، يبقى الطلب في حالة «في انتظار الدفع» وتُضاف ملاحظة.

Processing or Completed: تم تأكيد دفعة Purchase. يضبط WooCommerce الطلب على «قيد التجهيز»، أو على «مكتمل» للطلبات التي لا تحتاج إلى شحن، كالمعتاد. تعرض ملاحظة الطلب المبلغ ومعرّف معاملة Windcave ورمز التفويض ونوع البطاقة مع رقم البطاقة المخفي والبيئة (UAT أو الإنتاج). معرّف معاملة الطلب هو معرّف معاملة Windcave.

On hold (authorised): تمت الموافقة على دفعة Auth لكنها لم تُحصَّل بعد. تشرح ملاحظة الطلب كيفية تحصيلها أو تحريرها.

On hold (does not match): أبلغ Windcave عن مبلغ أو عملة أو مرجع تاجر أو نوع معاملة يختلف عن الطلب (مثلًا تم تعديل الطلب بعد بدء الدفع). تسرد الملاحظة الاختلافات. تحقق من الدفعة في Windcave Payline قبل الشحن، واستردّها إذا لزم الأمر.

Failed: تم رفض الدفع. تعرض الملاحظة نص استجابة Windcave ورمزها. يمكن للعميل المحاولة مرة أخرى.

إذا وصلت دفعة معتمدة لطلب ملغى، أو دفعة معتمدة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب. تطلب منك ملاحظة تتضمن معرّف المعاملة استردادها في Windcave Payline (أو استعادة الطلب الملغى يدويًا).

التحصيل (وضع Auth)

افتح الطلب، واختر Capture Windcave payment في إجراءات الطلب، ثم انقر على زر التحديث. يظهر الإجراء فقط للطلبات في حالة «في الانتظار» التي لها تفويض لم يُحصَّل أو يُحرَّر بعد. يُحصَّل إجمالي الطلب، وتُضاف عملية التحصيل إلى ملاحظات الطلب، ويتقدم الطلب كطلب مدفوع (عادةً «قيد التجهيز»). إذا لم يقبل Windcave التحصيل، تعرض شاشة الطلب Windcave capture failed: مع السبب، ويُضاف السبب إلى ملاحظات الطلب.

الاستردادات

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

بالنسبة إلى دفعة Auth غير محصّلة، لا يمكن إلا الاسترداد الكامل: فهو يحرّر (يلغي) التفويض. يؤدي المبلغ الجزئي إلى خطأ يطلب منك استرداد المبلغ كاملًا أو تحصيل الدفعة أولًا.

إذا رفض Windcave الاسترداد، يعرض WooCommerce الرسالة Windcave declined the refund: مع السبب، ولا يُسجَّل أي استرداد. إذا كان Windcave ما زال يعالج الاسترداد، يعرض WooCommerce الرسالة Windcave has not confirmed the refund yet. See the order notes. ولا يُسجَّل الاسترداد. تحقق من المعاملة في Windcave Payline: إذا كانت معتمدة فسجّل الاسترداد يدويًا؛ وإلا فحاول مرة أخرى. لا تُرسل المحاولة المكررة للاسترداد نفسه إلى Windcave مرتين. لا تُبلَّغ الاستردادات التي تتم في Windcave Payline إلى المتجر.

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

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

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

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

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

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

Windcave does not appear at checkout: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على بيانات الاعتماد كلها: UAT API username وUAT API key في وضع الاختبار، وProduction API username وProduction API key في الوضع الفعلي.

The payment went through, but the order stays Pending payment: لم تتمكن الإضافة بعد من الحصول على النتيجة من Windcave. افتح ملاحظات الطلب: تذكر إحدى الملاحظات متى تعذّر التحقق من الجلسة ولماذا. تحقق من أن بيانات اعتماد بيئة الدفعة محفوظة وصحيحة. يتكرر التحقق عندما يعيد Windcave إرسال الإشعار (تردّ الإضافة بخطأ إلى أن يمكن التحقق من النتيجة، ليعيد Windcave المحاولة)، وعندما يفتح العميل صفحة استلام الطلب. يجب أن يقبل خادمك الطلبات الصادرة من Windcave إلى https://your-site/wc-api/windcave_p_notification/.

Authentication failed in the order notes or the log: اسم مستخدم REST API أو مفتاحه غير صحيح، أو ينتمي إلى البيئة الأخرى. تعمل بيانات اعتماد UAT في وضع الاختبار فقط، وبيانات اعتماد الإنتاج في الوضع الفعلي فقط. مفاتيح PxPay لا تعمل.

The customer sees that Windcave could not start the payment with the details of this order: رفض Windcave طلب الجلسة، مثلًا بسبب العملة أو بسبب طريقة دفع غير مفعّلة في حسابك. السبب الدقيق موجود في ملاحظات الطلب وفي السجل.

Order is On hold after payment: اقرأ ملاحظة الطلب. إما أن تكون الدفعة من نوع Auth تنتظر التحصيل، وإما أن المبلغ المدفوع أو العملة أو مرجع التاجر اختلف عن الطلب. حصّل الدفعة أو جهّز الطلب أو استرد الدفعة.

Test payments and live payments: تُفصل بيئتا UAT والإنتاج عن بعضهما. يُتحقق من كل جلسة في البيئة التي أُنشئت فيها، وتُرسل الاستردادات والتحصيلات إلى بيئة الدفعة، حتى لو غيّرت Test mode لاحقًا. تستخدم الطلبات التي أنشأتها الإضافة بالإصدار 1.0 بيئة إعداد API URL القديم.

Refund fails with a message about the environment: تمت الدفعة في UAT أو في الإنتاج، ولا توجد بيانات اعتماد محفوظة لتلك البيئة. أدخلها وأعد المحاولة.

Capture Windcave payment is missing in the order actions: يظهر الإجراء فقط للطلبات في حالة «في الانتظار» المدفوعة بطريقة Auth والتي لم تُحصَّل أو تُحرَّر بعد.

Where to find details: تُكتب الأخطاء والتحذيرات دائمًا في WooCommerce > Status > Logs بالمصدر wcp_windcave_payment_gateway. فعّل Debug log لتسجيل طلبات API وأحداث الدفع أيضًا.

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

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

إلغاء تفعيل الإضافة يحتفظ بكل البيانات. لإزالتها، ألغِ تفعيلها ثم احذفها من صفحة Plugins. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالة الترخيص. تُحذف إعدادات البوابة وخيارات الإضافة والسجلات (ملفات السجل بما فيها الملفات المدوّرة، وإدخالات السجل في قاعدة البيانات) فقط إذا كان Clean uninstall مفعّلًا. وإلا فستبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات معاملات Windcave.

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