بوابة Windcave Terminal

تتيح لك بوابة Windcave Terminal قبول مدفوعات البطاقات حضوريًا على جهاز Windcave الطرفي عبر Windcave HIT. تبدأ المدفوعات من WCPOS وتُستكمل على الجهاز الطرفي، ثم يُسجَّل التأكيد في طلب WooCommerce.

إصدار جديد في 0.1.0 — بانتظار اعتماد Windcave

الإصدار 0.1.0 هو الإصدار الأول. تشترط Windcave اعتماد ضمان الجودة (QA) للتكامل قبل استخدامه في بيئة الإنتاج، وهذا التكامل لم يُعتمد بعد. استخدم بيانات اعتماد Windcave UAT (الاختبار) إلى حين اكتمال الاعتماد. تصدر Windcave Vendor ID أثناء الاعتماد.

الميزات

اتصال HIT سحابي

اتصل عبر خدمة HIT السحابية من Windcave، باستخدام Station ID واحد لكل جهاز طرفي ومن دون إقران محلي

مطالبات الجهاز الطرفي على الشاشة

تابع مطالبات الجهاز الطرفي وأزراره من لوحة الدفع، بما في ذلك YES/NO للتحقق من التوقيع وCANCEL

إتمام موثّق

لا تكتمل الطلبات إلا بعد التحقق من مرجع الدفع والمبلغ والبيئة وإجمالي الطلب والعملة

إرجاء الدفع

بعد انتهاء المهلة، أرجئ الدفع المعلّق وتابع العمل بينما يتحقق فحص في الخلفية من حالته

إشعارات النتائج

فعّل إشعارات النتائج الاختيارية (FPRN) لتتمكن Windcave من إشعار موقعك كخيار احتياطي للاستطلاع الدوري

آلية العمل

تستخدم بوابة الدفع Windcave HIT (Host Initiated Transaction) عبر HTTPS. تحدد Environment نقطة نهاية UAT أو الإنتاج، ويُعرَف كل جهاز طرفي باستخدام Station ID الصادر عن Windcave.

عند بدء الدفع، يُرسل إجمالي الطلب الكامل والعملة إلى الجهاز الطرفي. وتستطلع صفحة الدفع Windcave كل 1.5 ثانية، مع عرض مطالبات الجهاز الطرفي والأزرار المتاحة. تتيح Result notifications (FPRN) الاختيارية لـ Windcave إشعار الموقع كخيار احتياطي للاستطلاع الدوري.

الإعداد

1

تثبيت Windcave Terminal for WooCommerce

نزّل ملف zip الخاص بالإضافة (وليس ملف zip للشيفرة المصدرية على GitHub) من صفحة إصدارات GitHub. ارفع الملف عبر إضافات > إضافة جديد > رفع إضافة وفعّل الإضافة بعد تثبيت WooCommerce وتفعيله.

يتطلب التفعيل PHP 7.4+ وامتداد PHP DOM (php-xml). إذا كان أيٌّ منهما غير متوفر، فسيُرفض التفعيل مع عرض رسالة.

2

الحصول على بيانات اعتماد HIT من Windcave

اطلب من Windcave HIT username وHIT key وStation ID واحدًا لكل جهاز طرفي. اطلب حساب تطوير عبر نموذج متطلبات التكامل لدى Windcave.

بيانات اعتماد UAT والإنتاج منفصلة. استخدم بيانات اعتماد UAT ريثما ينتظر هذا التكامل الاعتماد.

3

تهيئة بوابة الدفع

1. انتقل إلى WP Admin > WooCommerce > الإعدادات > المدفوعات وافتح Windcave Terminal
2. اضبط Environment على UAT (testing) (الإعداد الافتراضي). يُستخدم Production بعد اعتماد Windcave وباستخدام بيانات اعتماد الإنتاج
3. أدخل HIT username وHIT key الصادرين عن Windcave
4. أدخل Station IDs، كل معرّف في سطر منفصل
5. (اختياري) عيّن Default Station ID. فعّل Lock terminal selection لاستخدام هذا الخيار الافتراضي دائمًا ومنع أمناء الصندوق من تغييره
6. اترك Vendor ID فارغًا إلى أن تصدره Windcave أثناء الاعتماد
7. احفظ إعداداتك

4

تفعيل إشعارات النتائج (اختياري)

فعّل Result notifications (FPRN) واحفظ لطلب إشعار Windcave لموقعك عند توفر نتيجة المعاملة. وهذا خيار احتياطي للاستطلاع الدوري.

5

التفعيل في WCPOS

1. انتقل إلى WP Admin > نقطة البيع > الإعدادات > إتمام الطلب
2. اعثر على بوابة الدفع Windcave Terminal وفعّلها لنظام POS
3. احفظ إعداداتك

ملاحظة

يتحكم مربع الاختيار Enable/Disable في شاشة إعدادات WooCommerce بعملية الدفع في المتجر الإلكتروني فقط. يستخدم WCPOS بوابة الدفع هذه بمجرد تهيئتها، سواء تم تحديد ذلك المربع أم لا.

مرجع الإعدادات

الإعداد	وظيفته
Enable/Disable	يفعّل بوابة الدفع لعملية الدفع في المتجر الإلكتروني. يُتحكم في تفعيل POS ضمن نقطة البيع > الإعدادات > إتمام الطلب
Title	تسمية الدفع؛ القيمة الافتراضية هي Windcave Terminal
Description	وصف الدفع؛ القيمة الافتراضية هي Pay in person on the Windcave terminal.
Environment	UAT (testing) (افتراضيًا) أو Production. لكل منهما بيانات اعتماد HIT منفصلة؛ ويتطلب الإنتاج اعتماد Windcave
HIT username	اسم مستخدم HIT الذي أصدرته Windcave للبيئة المحددة
HIT key	مفتاح HIT الذي أصدرته Windcave للبيئة المحددة
Station IDs	معرّف Station ID واحد صادر عن Windcave في كل سطر، واحد لكل جهاز طرفي
Default Station ID	محطة Station المحددة مسبقًا، وتُستخدم أيضًا عند عدم تحديد محطة
Lock terminal selection	يستخدم محطة Station الافتراضية دائمًا لمنع أمناء الصندوق من تغييرها. لا يسري هذا الخيار إلا عند تعيين محطة افتراضية
Vendor ID	تصدره Windcave أثناء الاعتماد. اتركه فارغًا حتى توفره Windcave
POS name	الاسم المُرسل إلى Windcave للتعرّف على نظام POS؛ القيمة الافتراضية هي WCPOS
Result notifications (FPRN)	يطلب من Windcave إشعار الموقع عند توفر نتيجة المعاملة، كخيار احتياطي للاستطلاع الدوري. يكون معطلًا افتراضيًا
Checkout logs	يعرض أدوات السجل في لوحة الدفع. يكون معطلًا افتراضيًا
Log level	Off أو Errors only أو Debug. القيمة الافتراضية Debug، ويسجل الطلبات والاستجابات مع إخفاء المفاتيح وبيانات البطاقة
Support	يوفر Download support bundle ورابطًا لعرض السجلات في WooCommerce > Status > السجلات

لا يوجد زر لاختبار الاتصال: تُفحص بيانات الاعتماد ومعرّفات Station IDs عند تنفيذ أول عملية دفع.

الاستخدام

معالجة المدفوعات

1. Add Items: أضف المنتجات إلى سلة التسوق في POS
2. Select Gateway: اختر Windcave Terminal كطريقة الدفع
3. Choose Terminal: اختر محطة Station أو استخدم الخيار الافتراضي المقفل. يلزم الاختيار عند وجود محطتين أو أكثر وعدم تعيين خيار افتراضي
4. Start Payment: انقر Start Terminal Payment لإرسال إجمالي الطلب إلى الجهاز الطرفي
5. Follow Prompts: تظهر مطالبات الجهاز الطرفي والأزرار المتاحة على الشاشة، بما في ذلك YES/NO للتحقق من التوقيع وCANCEL عند إتاحته
6. Automatic Completion: بعد الموافقة والتحقق، يكتمل الطلب وينتقل POS إلى الإيصال

عناصر التحكم في الدفع

• Start Terminal Payment: أرسل طلب دفع جديدًا إلى محطة Station المحددة
• Cancel Terminal Payment: يضغط زر CANCEL في الجهاز الطرفي عندما يتيحه الجهاز. وإلا، فألغِ العملية من الجهاز الطرفي أو أرجئ الدفع عند ظهور هذا الخيار
• Set payment aside: يظهر بعد انتهاء مهلة 5 دقائق. ويُبقي المحاولة قيد فحص في الخلفية لمدة 10 دقائق لتتمكن من تحصيل الدفع بطريقة أخرى؛ ولا يلغي الدفع لدى Windcave
• إعادة تحميل الصفحة: تستأنف عملية دفع جارية بالفعل

الإيصالات

يُحفَظ نص إيصال الجهاز الطرفي، عند إرجاع Windcave له، في ملاحظة خاصة بالطلب في WooCommerce.

المبالغ المستردة

المبالغ المستردة من WooCommerce غير مدعومة في 0.1.0. أجرِ استرداد المبلغ عبر بوابة Windcave (Payline) أو الجهاز الطرفي، ثم سجّل الاسترداد في WooCommerce يدويًا.

السجلات وحزمة الدعم

اعثر على السجلات في WooCommerce > Status > السجلات ضمن المصدر windcave-terminal. مستوى السجل الافتراضي هو Debug، ويسجل طلبات Windcave واستجاباتها مع إخفاء المفاتيح وبيانات البطاقة.

انقر Download support bundle في شاشة إعدادات بوابة الدفع لتنزيل ملف .json، وأرسله مع رقم الطلب. يحتوي الملف على تفاصيل البيئة والإعدادات مع إخفاء مفتاح HIT واسم المستخدم، ومحاولات الدفع من ما يصل إلى 20 طلبًا حديثًا بعد إزالة الإيصالات، وآخر 1,000 سطر من أحدث ملفي سجل؛ وقد تتضمن أسطر السجل نص إيصال الجهاز الطرفي مع إخفاء أرقام البطاقات.

إذا كان WooCommerce يستخدم معالج سجلات قاعدة البيانات، فلن تحتوي الحزمة على أي أسطر سجل. صدّر السجلات من WooCommerce > Status > السجلات بدلًا من ذلك.

فعّل Checkout logs لعرض أدوات السجل في لوحة الدفع.

المتطلبات

حساب Windcave: HIT username وHIT key وStation ID لكل جهاز طرفي؛ ويتطلب الاستخدام في بيئة الإنتاج اعتماد Windcave

الأجهزة المتوافقة: جهاز Windcave طرفي يستخدم HIT

WCPOS: يلزم إصدار Pro لإتمام الدفع في POS

الخادم: WordPress 5.2+ وWooCommerce وPHP 7.4+ مع امتداد DOM (php-xml)

العملة: عملة ذات منزلتين عشريتين

اتصال مستقر: اتصال موثوق بالإنترنت للتواصل عبر API

النطاق والقيود

يلزم الاعتماد

لم تعتمد Windcave هذا التكامل بعد. استخدم بيانات اعتماد UAT حتى اكتمال اعتماد ضمان الجودة (QA) من Windcave؛ ولا تستخدمه في بيئة الإنتاج قبل الاعتماد.

• لا تُدعم المبالغ المستردة من WooCommerce في 0.1.0
• الإكراميات والرسوم الإضافية والسحب النقدي غير مدعومة
• لا تُدعم إلا العملات ذات المنزلتين العشريتين
• يُحصَّل على الجهاز الطرفي إجمالي الطلب كاملًا؛ ولا يُدعم دفع جزء فقط من الطلب على الجهاز الطرفي
• تُدخل Station IDs يدويًا؛ ولا يجري اكتشاف الأجهزة الطرفية تلقائيًا
• صُممت بوابة الدفع للاستخدام في POS. أما في المتجر الإلكتروني، فلا تعمل إلا في صفحة order-pay

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

المشكلات الشائعة

رُفض التفعيل: يلزم امتداد PHP DOM (php-xml)

• امتداد PHP DOM غير متوفر على الخادم
• اطلب من مزود الاستضافة تفعيل php-xml. يتطلب التفعيل أيضًا PHP 7.4+

لم تُهيأ أي Station IDs

• إعداد Station IDs فارغ
• أضف Station IDs الصادرة عن Windcave في إعدادات بوابة الدفع، واحدًا في كل سطر، ثم احفظ

لم تُهيأ بيانات اعتماد Windcave HIT

• حقل HIT username أو HIT key فارغ
• أدخلهما كليهما في إعدادات بوابة الدفع واحفظ. تأكد من أن Environment يطابق بيانات الاعتماد هذه

لا يزال الجهاز الطرفي يُنهي معاملة سابقة

• لا تزال معاملة سابقة قيد التنفيذ على محطة Station تلك
• أكملها أو ألغها على الجهاز الطرفي، ثم حاول مجددًا

لا تملك Windcave سجلًا لهذه المعاملة

• لا يزال سجل المعاملة غير موجود لدى Windcave بعد فترة السماح الأولية البالغة 30 ثانية
• ابدأ الدفع مجددًا

وافقت Windcave على الدفع، لكن تعذّر تطبيقه

• لم تجتز النتيجة الموافق عليها عمليات التحقق اللازمة لإتمام هذا الطلب
• تحقق من بوابة Windcave وملاحظات الطلب قبل تحصيل المبلغ مجددًا

بدأت عملية الدفع هذه في بيئة مختلفة

• تم تغيير Environment أثناء معالجة الدفع
• عُد إلى البيئة التي بدأ فيها الدفع، أو تحقق من بوابة Windcave

الحصول على المساعدة

• أرسل حزمة الدعم من شاشة إعدادات بوابة الدفع مع رقم الطلب
• زُر مستودع GitHub للإبلاغ عن المشكلات
• تواصل مع دعم Windcave بشأن أسئلة الحساب وبيانات الاعتماد والأجهزة