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

المتطلبات

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

PHP: ‏8.0 أو أحدث.

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

الإشعار: يجب أن يكون متجرك متاحًا من الإنترنت حتى تتمكن Windcave من إرسال إشعار الدفع. لا يلزم إعداد أي شيء في Windcave لذلك.

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

التثبيت

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

OpenCart 3

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

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

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

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

5. اختر نوع المعاملة وطرق الدفع، ثم فعّل Enable/Disable واضغط Save. نفّذ دفعة تجريبية بينما Test mode مفعّل، ثم أوقف Test mode لقبول المدفوعات الحقيقية.

OpenCart 4

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

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

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

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

يبدأ التثبيت الجديد بطريقة الدفع معطّلة.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Windcave Payment Gateway > Edit. تُعرض الأقسام على اليسار؛ وزر Save أسفل القائمة يحفظ الصفحة كاملة. عند تفعيل وضع الاختبار تعرض الصفحة Test mode is on: payments go to the Windcave UAT environment and no real money is taken. وإذا كانت طريقة الدفع مفعّلة لكن الوضع الحالي لا يحتوي على اسم مستخدم API أو مفتاحه، تحذّر الصفحة من أنها مخفية في الخطوة الأخيرة من الشراء، مثل Windcave is enabled but the UAT API username / key are empty — the payment method is hidden at checkout. وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

عند الحفظ، لا يمكن أن يكون Title فارغًا، ويجب ألا يتجاوز 128 حرفًا (Enter a title for the payment method (at most 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (Sort Order must be a whole number.)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0 (Total: enter a number, 0 or greater.)، ويجب أن تكون المنطقة الجغرافية وحالات الطلب المختارة موجودة؛ وإلا فلن يُحفظ شيء وتعرض الصفحة الخطأ.

Windcave

Enable/Disable: Enable Windcave payments يفعّل طريقة الدفع أو يعطّلها. الإعداد الافتراضي: off.

Title: اسم طريقة الدفع الذي يراه العميل في الخطوة الأخيرة من الشراء، وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الإعداد الافتراضي: Credit/Debit Card (Windcave). حقل إلزامي، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الإعداد الافتراضي: You will be redirected to the secure Windcave payment page to complete your payment.

Sort Order: موضع Windcave بين طرق الدفع عند الخروج من الشراء. اتركه فارغًا أو أدخل عددًا صحيحًا؛ الأعداد السالبة مسموحة.

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

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Windcave: رقم أكبر من أو يساوي 0. اتركه فارغًا لعرضه مهما كان الإجمالي.

Windcave REST API

أدخل بيانات اعتماد REST API التي أصدرتها Windcave (اسم المستخدم ومفتاح API، وليس مفاتيح PxPay). يمكن حفظ بيانات اعتماد الإنتاج وUAT جنبًا إلى جنب. يستخدم وضع الاختبار بيانات UAT فقط، ويستخدم الوضع الحي بيانات الإنتاج فقط. يتضمن القسم رابطًا إلى وثائق Windcave REST API.

Test mode: يستخدم بيئة الاختبار UAT لـ Windcave (uat.windcave.com). لا يُحصَّل أي مبلغ حقيقي. تستخدم المدفوعات الجديدة بيانات UAT. تتجه المبالغ المستردة والتحصيلات دائمًا إلى البيئة التي دُفع فيها الطلب. الإعداد الافتراضي: off.

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 the saved key on save أسفل الحقل، ثم اضغط Save.

Notification URL: يعرض العنوان الذي ترسل إليه Windcave إشعار الدفع (Fail-Proof Result Notification). يُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك، على OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_windcave_payment_gateway/notify، وعلى OpenCart 4 https://your-store/index.php?route=extension/wcp_windcave_payment_gateway/payment/wcp_windcave_payment_gateway.notify. لا يلزم إعداد أي شيء في 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. يمكنك اختيار أكثر من طريقة. يجب تفعيل الطرق في حساب Windcave الخاص بك. اترك الحقل فارغًا (Every method enabled on the account) لعرض جميع الطرق المفعّلة في الحساب. الإعداد الافتراضي: Cards.

Orders

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). يحصل الطلب على حالة فقط بعد أن توافق Windcave على الدفعة. تسرد كل الحقول أدناه حالات طلبات OpenCart الخاصة بك.

Order Status After Payment: تُعيَّن بعد عملية Purchase موافَق عليها أو بعد التحصيل. الإعداد الافتراضي: Processing.

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

Cancelled Order Status: لا تعيّنها الإضافة. لا تغيّر دفعة موافَق عليها تصل لطلب في هذه الحالة الطلب؛ وتطلب منك ملاحظة استرداد الدفعة في Windcave Payline أو استعادة الطلب. الإعداد الافتراضي: Canceled.

Refunded Status: تُعيَّن بعد استرداد الدفعة كاملةً، أو تحرير التفويض، من صفحة الطلب. الإعداد الافتراضي: Refunded.

Advanced

Debug log: يسجّل طلبات الواجهة البرمجية وأحداث الدفع في windcave_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. طالما أن هذا الخيار متوقف، تُسجَّل الأخطاء والتحذيرات فقط. لا تُسجَّل مفاتيح API وبيانات البطاقات والبيانات الشخصية للعملاء أبدًا. الإعداد الافتراضي: off.

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

Clean uninstall: يحذف إعدادات الإضافة وسجلاتها عند إلغاء تثبيتها. تبقى بيانات الدفع المحفوظة مع الطلبات (معرّفات معاملات Windcave اللازمة للاسترداد) محفوظة دائمًا. الإعداد الافتراضي: off.

يظهر إصدار الإضافة أسفل القسم.

Import / Export

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر مفاتيح API.

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

الخروج من الشراء (Checkout)

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card (Windcave)). في خطوة Confirm Order يرى العميل وصفك؛ وفي وضع الاختبار يرى أيضًا Test mode: payments go to the Windcave UAT environment, no real money is taken. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. عندما يضغط العميل Confirm Order، تنشئ الإضافة جلسة دفع في Windcave لمجموع الطلب بعملة الطلب، وتنقل العميل إلى Windcave Hosted Payment Page. يُرسَل رقم طلب OpenCart بوصفه مرجع التاجر، مع لغة الطلب واسم العميل وبريده الإلكتروني وهاتفه وعنوان الفوترة (وعنوان الشحن عندما يتطلب الطلب شحنًا). في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، ثم ينقر على Confirm Order في أسفل صفحة الدفع.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Windcave: تطلب الإضافة نتيجة الجلسة من Windcave REST API، سواء عند عودة العميل أو عند وصول إشعار Windcave. يضمن القفل الخاص بكل سلة أن تُطبَّق الدفعة مرة واحدة فقط. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your Windcave payment has been received. وبالنسبة إلى طلب محجوز (تفويض أو دفعة لا تطابق الطلب)، تعرض الصفحة Your payment was received by Windcave. The store 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 الدفعة.

إذا عاد العميل دون إكمال الدفع، يبقى الطلب بدون حالة وتبقى السلة محفوظة، وتعرض صفحة الدفع إحدى هذه الرسائل:

في OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع.

يمكن للعميل أن يعيد المحاولة بالسلة نفسها (ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك يُدفع الطلب نفسه في جلسة 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 بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة فوق الزر: Windcave could not start the payment with the details of this order. Please check your billing details and try again, or choose another payment method. أو The payment could not be started because the payment service is temporarily unavailable. Please try again in a moment or choose another payment method. يُكتب السبب في السجل. وإذا لم تكن لدى الوضع الحالي بيانات اعتماد، يرى العميل This payment method is not available at the moment. Please choose another payment method or contact us.

في OpenCart 4، إذا حصل طلب الدفع على حالة دون دفعة Windcave، أو أغلقه المتجر في الأثناء، فإن Confirm Order التالي يعيد العميل إلى صفحة الدفع مع This order can no longer be paid. Please check your cart and confirm the order again. فوق صفحة الدفع، وتُدفع السلة بطلب جديد. وإذا كان طلب الدفع مدفوعًا بالفعل لكن السلة تغيّرت منذ ذلك الحين، بما في ذلك الكمية الجديدة، يُعاد العميل إلى صفحة الدفع وتُدفع السلة الجديدة بطلب جديد.

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

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

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

Order statuses

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

Order Status After Payment (الافتراضي Processing): وافقت Windcave على دفعة Purchase وهي متطابقة مع الطلب. تعرض الملاحظة المبلغ ومعرّف المعاملة ورمز التفويض ونوع البطاقة مع رقمها المخفي والبيئة (UAT أو الإنتاج).

Windcave Payment On Hold Status، مُفوَّض (الافتراضي Pending): وافقت Windcave على دفعة Auth لكنها لم تُحصَّل بعد. توضح الملاحظة كيفية تحصيلها أو تحريرها.

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

Refunded Status (الافتراضي Refunded): استُرد المبلغ كاملًا أو حُرر التفويض عبر الإضافة.

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

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

VibeFox Windcave Payment Gateway tab

في Sales > Orders افتح طلبًا دُفع عبر Windcave. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Windcave Payment Gateway الخانات التالية: Transaction ID وSession ID وType / status مع البيئة وAmount paid وAuth code / card وCapture transaction أو التفويض المحرَّر وPayment total / refunded وعلامة Test mode (UAT) للدفعات التجريبية وزر التحصيل ونموذج الاسترداد وسجله وWindcave sessions of this cart وWindcave notes الخاصة بالطلب. تُعرض علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

Capture (Auth mode)

بالنسبة إلى طلب في Windcave Payment On Hold Status وله تفويض لم يُحصَّل بعد ولم يُحرَّر، تعرض علامة التبويب الزر Capture Windcave payment. اضغطه وأكّد Capture the authorised amount through Windcave now? يُحصَّل المبلغ المفوَّض، وينتقل الطلب إلى Order Status After Payment، وتظهر معاملة التحصيل في علامة التبويب. إذا لم تقبل Windcave التحصيل، تعرض علامة التبويب Windcave capture failed: مع السبب، ويُضاف السبب إلى الملاحظات، ويبقى الطلب محتجزًا. يحتاج التحصيل إلى صلاحية تعديل الإضافة وبيانات اعتماد بيئة الدفعة.

Refunds

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

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

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

لا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Windcave. لا تُبلَّغ المبالغ المستردة المنفذة في Windcave Payline إلى المتجر.

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

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

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

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

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

لا يظهر Windcave في الخطوة الأخيرة من الشراء: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على بيانات الاعتماد الاثنتين: UAT API username وUAT API key في وضع الاختبار، وProduction API username وProduction API key في الوضع الحي. تعرض صفحة الإعدادات تحذيرًا عند غيابهما. تحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت عملية الدفع لكن الطلب يبقى بدون حالة: لم تتمكن الإضافة بعد من الحصول على النتيجة من 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 طلب الجلسة، مثلًا بسبب العملة أو بسبب طريقة دفع غير مفعّلة في حسابك. السبب الدقيق موجود في السجل.

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

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في علامة التبويب VibeFox Windcave Payment Gateway. إما أن الدفعة Auth تنتظر التحصيل، أو أن المبلغ المدفوع أو العملة أو مرجع التاجر اختلف عن الطلب. حصّل الدفعة أو نفّذ الطلب أو استرد الدفعة.

دفعات الاختبار والدفعات الحقيقية: بيئة UAT والإنتاج منفصلتان. تُتحقق كل جلسة في البيئة التي أُنشئت فيها، وتتجه الاستردادات والتحصيلات إلى بيئة الدفعة، حتى لو بدّلت Test mode لاحقًا.

يفشل الاسترداد برسالة متعلقة بالبيئة: دُفعت الدفعة في UAT أو في الإنتاج، ولا توجد بيانات اعتماد محفوظة لتلك البيئة. أدخلها وأعد المحاولة.

زر Capture Windcave payment غير موجود في علامة تبويب الطلب: يظهر الزر فقط للطلبات في Windcave Payment On Hold Status المدفوعة بطريقة Auth والتي لم تُحصَّل أو تُحرَّر بعد، وفقط عندما تكون بيانات اعتماد بيئة الدفعة محفوظة، ولا يظهر إلا للمستخدمين الذين يمكنهم تعديل الإضافة.

أين تجد التفاصيل: تُكتب الأخطاء والتحذيرات دائمًا في السجل؛ فعّل Debug log لتسجيل طلبات الواجهة البرمجية وأحداث الدفع أيضًا.

للمطورين: قبل إنشاء جلسة Windcave، تُطلق الإضافة حدث OpenCart ‏windcave_p_session_request مع معلمات الجلسة والطلب.

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

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

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

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