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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

العملة: ILS أو USD أو EUR أو GBP. بالنسبة لعملات العملاء الأخرى تُخفى طريقة الدفع عند الدفع.

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

عنوان IP الحقيقي للزائر: تُتحقق إشعارات الدفع مقابل عنوان IP الخاص بخادم Tranzila. إذا كان متجرك خلف وكيل (proxy) أو شبكة CDN مثل Cloudflare، فيجب أن يمرر خادم الويب عنوان IP الحقيقي للزائر إلى PHP (REMOTE_ADDR).

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل Terminal name (supplier)، وTerminal password (TranzilaPW) إذا كنت تستخدم المصافحة أو الاستردادات.

5. أبقِ Notifications مفعّلاً وتحقق من Trusted IP: يجب أن يحتوي على عناوين IP التي ترسل منها Tranzila الإشعارات. أكّد القائمة مع دعم Tranzila. يُرسل عنوان URL الخاص بالإشعار مع كل دفعة، لذلك لا تحتاج إلى نسخه في أي مكان.

6. موصى به: فعّل المصافحة في جهاز Tranzila الطرفي، واسمح هناك بعنوان IP لخادمك، ثم فعّل Handshake في الإضافة.

7. فعّل Enable/Disable وانقر على Save، ثم اختبر دفعة باستخدام جهاز Tranzila الطرفي للاختبار.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوات من 3 إلى 7 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Tranzila Payment Gateway > Edit. تظهر الأقسام في القائمة على اليسار؛ وزر Save أسفل القائمة يحفظ الصفحة كاملة. فوق الإعدادات تنبّهك الصفحة عندما يكون اسم الجهاز الطرفي فارغاً (وعندئذٍ تُخفى طريقة الدفع عند الدفع)، وعندما تكون الإشعارات معطلة أو يكون Trusted IP فارغاً (وعندئذٍ تُحتجز الطلبات المدفوعة للمراجعة اليدوية)، وعندما تكون المصافحة مفعّلة دون كلمة مرور للجهاز الطرفي (وعندئذٍ لا يمكن فتح صفحة الدفع)، وعندما تكون العملة الافتراضية للمتجر غير مدعومة. من دون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا ترفض الصفحة كل شيء دفعة واحدة. فالعنوان Title الفارغ أو الذي يزيد على 128 حرفاً، أو اسم الجهاز الطرفي غير الصالح، أو إدخال غير صالح في Trusted IP، أو حقل رقمي ليس عدداً صحيحاً، أو قيمة غير صالحة في Sort Order أو Total أو Geo Zone أو حالة الطلب، لا تُحفظ: تعرض الصفحة الرسالة في كتلة حمراء فوق الإعدادات، ويعرض الحقل القيمة السابقة من جديد. يُحفظ الرقم الخارج عن النطاق المسموح على أقرب قيمة مسموحة، وتخبرك الصفحة بذلك، مثلاً أن 5000 خارج النطاق 400–1500 وقد حُفظ كـ 1500. تُحفظ جميع الحقول الأخرى.

Tranzila

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

Title: اسم طريقة الدفع الذي يراه العميل عند الدفع، وعنوان صفحة الدفع. وهو أيضاً الاسم المحفوظ لطريقة الدفع في الطلب، لذلك فهو مطلوب ويمكن أن يبلغ 128 حرفاً كحد أقصى. الافتراضي: Credit Card (Tranzila).

Description: النص الذي يراه العميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: Pay securely with your credit card on the Tranzila payment page.

Sort Order: ترتيب Tranzila بين طرق الدفع عند الدفع. اتركه فارغاً أو أدخل عدداً صحيحاً (القيم السالبة مسموحة).

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

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

الجهاز الطرفي

Terminal name (supplier): اسم جهاز Tranzila الطرفي لديك، مثلاً myshop. الحروف والأرقام و"-" و"_" فقط. حتى يُدخل، لا تظهر طريقة الدفع عند الدفع. للاختبار، أدخل اسم جهاز Tranzila الطرفي للاختبار.

Terminal password (TranzilaPW): كلمة مرور API للجهاز الطرفي. مطلوبة للمصافحة وللاستردادات من صفحة الطلب.

Refund password (CreditPass): فقط إذا كان جهازك الطرفي يتطلب كلمة مرور منفصلة لمعاملات الائتمان (الاسترداد). اتركه فارغاً في الحالات الأخرى.

لا تُعرض كلمات المرور المحفوظة مرة أخرى. يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف كلمة مرور محفوظة، ضع علامة على Clear saved password on save أسفل الحقل وانقر على Save.

صفحة الدفع

Payment page version: صفحة Tranzila المعروضة في الإطار (iframe).

Payment page language: لغة صفحة Tranzila: Site language، أو العبرية، أو الإنجليزية، أو الروسية، أو الإسبانية، أو الألمانية، أو الفرنسية، أو اليابانية. الافتراضي: Hebrew. يستخدم Site language لغة واجهة المتجر الخاصة بالعميل عندما تكون إحدى هذه اللغات، وإلا فالإنجليزية.

iFrame width (px): من 300 إلى 1200. الافتراضي: 600. على الشاشات الصغيرة لا يتجاوز الإطار عرض الصفحة أبداً.

iFrame height (px): من 400 إلى 1500. الافتراضي: 650.

Max installments: الحد الأقصى لعدد الأقساط (tashlumim) التي يمكن للعميل اختيارها في صفحة الدفع، حتى 36. القيمة 0 أو 1 تعني بلا أقساط. الافتراضي: 0. يجب أن يكون الجهاز الطرفي مسموحاً له بمعالجة الأقساط.

Handshake: يثبّت المبلغ برمز مصافحة (موصى به). قبل فتح صفحة الدفع، يطلب المتجر من Tranzila رمزاً لمرة واحدة مرتبطاً بالمبلغ، بحيث لا يمكن تغيير المبلغ في المتصفح. يتطلب كلمة مرور الجهاز الطرفي، وتفعيل المصافحة في جهاز Tranzila الطرفي، والسماح هناك بعنوان IP لخادمك. الافتراضي: off.

تأكيد الدفع

إشعارات Tranzila غير موقّعة. لا يحصل الطلب على حالة مدفوع إلا عندما يأتي الإشعار من Trusted IP، ويتطابق رمز صفحة الدفع والطلب والجهاز الطرفي والمبلغ والعملة مع صفحة الدفع. مع المصافحة، يجب أن يتطابق الرمز أيضاً. عودة العميل من صفحة الدفع لا تُعلّم الطلب مدفوعاً أبداً.

Notifications: يؤكد المدفوعات تلقائياً عبر إشعارات Tranzila (عنوان URL للإشعار). الافتراضي: on. عندما تكون الإشعارات معطلة، يضع العميل الذي يعود من صفحة دفع ناجحة الطلب في On hold status، وتؤكد الدفعة يدوياً بعد التحقق من جهاز Tranzila الطرفي.

Notification URL: يُعرض للمعلومية. في OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_tranzila_payment_gateway/notify، وفي OpenCart 4 يبدو هكذا: https://your-store/index.php?route=extension/wcp_tranzila_payment_gateway/payment/wcp_tranzila_payment_gateway.notify. ويُبنى من عنوان واجهة متجر تثبيت OpenCart الخاص بك. يُرسل العنوان إلى Tranzila مع كل دفعة، لذلك لا تحتاج إلى إدخاله في جهاز Tranzila الطرفي. ويعمل أيضاً عندما يكون المتجر في وضع الصيانة (في OpenCart 4 تسمح عملية بدء تشغيل الإضافة بمرور الإشعار وعودة العميل).

Trusted IP: عناوين IP أو نطاقات CIDR لخوادم Tranzila التي ترسل الإشعارات، مفصولة بفواصل. الافتراضي: 80.244.170.7. أكّد القائمة الحالية مع دعم Tranzila. تُرفض الإشعارات الواردة من عناوين أخرى. إذا كان الحقل فارغاً فلا يمكن التحقق من الإشعارات: فالدفعة الناجحة المبلغ عنها تضع الطلب في On hold status للمراجعة اليدوية، والرفض المبلغ عنه لا يغيّر شيئاً.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا من إشعار Tranzila متحقَّق منه. ليس لدى OpenCart حالة On hold، لذلك تُستخدم الحالة التي تختارها هنا، وتشرح ملاحظة في الطلب السبب. يسرد كل حقل أدناه حالات طلبات OpenCart الخاصة بك.

Order status after payment: تم تأكيد الدفعة بإشعار متحقَّق منه (المبلغ والعملة والجهاز الطرفي والرمز متطابقة). الافتراضي: Processing.

On hold status: تحتاج الدفعة إلى مراجعتك: المبلغ أو العملة أو رمز المصافحة مختلف، أو تعذّر التحقق من الإشعار (لا يوجد Trusted IP)، أو الإشعارات معطلة وعاد العميل من صفحة دفع ناجحة. الافتراضي: Pending. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Refunded status: يُعيَّن عند استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: Refunded.

Cancelled order status: لا تعيّنه الإضافة. الطلب الذي يكون بهذه الحالة ويُدفع لاحقاً يُعاد فتحه مع ملاحظة تطلب التحقق من المخزون. الافتراضي: Canceled.

Payment error status: لا تعيّنه الإضافة. الطلب الذي يكون بهذه الحالة يُدفع بدفعة Tranzila معتمدة لاحقة. الافتراضي: Failed.

متقدم

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

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا يتم تصدير كلمات المرور.

Import: الصق ملف JSON المُصدَّر سابقاً وانقر على Import لاستعادة الإعدادات. تُحفظ كلمات المرور المحفوظة.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضياً Credit Card (Tranzila)). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة After you confirm, you will enter your card details on the secure Tranzila payment page. The order is confirmed once Tranzila confirms the payment. ينشئ OpenCart الطلب في هذه الخطوة، ما زال بلا حالة. عندما ينقر العميل على Confirm Order، ينتقل إلى صفحة دفع في متجرك. هناك تُفتح صفحة الدفع الخاصة بـ Tranzila داخل إطار (iframe)، مع إجمالي الطلب بعملة الطلب، وبيانات الفوترة، وقائمة مختصرة بالمنتجات. تقول الصفحة Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". ويوجد الرابط Choose another payment method أسفل الإطار. إذا كانت الأقساط مسموحة، يختار العميل عددها في صفحة Tranzila. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في نافذة Payment method options، وينقر على Confirm Order أسفل صفحة إتمام الطلب.

كل عرض لصفحة الدفع هو محاولة دفع جديدة برمزها الخاص (ورمز المصافحة الخاص بها). إعادة تحميل الصفحة تفتح محاولة جديدة للطلب في جلسة العميل نفسها؛ ورابط صفحة الدفع المفتوح في متصفح آخر يعيد إلى الدفع.

بعد دفعة ناجحة، تعيد Tranzila العميل وتتابع النافذة كاملةً. لا يُعلَّم الطلب مدفوعاً إلا بعد أن تؤكده Tranzila بإشعار. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون. وعندما يُدفع طلب محتجز لاحقاً، يتلقى العميل رسالة البريد الإلكتروني حول الحالة الجديدة للطلب. إذا وصل الإشعار بالفعل، يرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your payment with Tranzila has been received. إذا كان الطلب محتجزاً للمراجعة، تعرض الصفحة Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. إذا لم يصل الإشعار بعد، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. مع الزرين Check again وBack to checkout.

إذا رُفضت الدفعة أو أُلغيت، يعود العميل إلى صفحة الدفع مع الرسالة The payment was not completed. You have not been charged — please try again or choose another payment method. عندما تبلّغ Tranzila عن رمز استجابة، تُضاف الأسباب والرمز، مثلاً أن البطاقة منتهية الصلاحية. تبقى السلة محفوظة ويبقى الطلب بلا حالة. وفي OpenCart 4 تُعرض هذه الرسالة فوق صفحة إتمام الطلب. ينشئ OpenCart 3 طلباً جديداً في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيُحدّث طلب الدفع؛ ولا تُخصم مرة أخرى سلة دفعها بالفعل أحد هذه الطلبات. ويُعدّ أي تغيير في السلة، بما في ذلك تغيير الكمية، سلةً جديدة تحتاج إلى دفعها الخاص.

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

إذا تعذّر فتح صفحة الدفع، مثلاً عندما تفشل المصافحة، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل Could not connect to Tranzila. Please try again in a moment. ويُكتب السبب التقني في السجل.

لا تقبل الإضافة إلا الدفعات الفردية بالبطاقة، في صفحة Tranzila. ليس لديها بطاقات أو رموز محفوظة، ولا اشتراكات، ولا تفويض وتحصيل منفصلان (J5)، ولا أزرار خاصة بـ Bit أو Apple Pay أو Google Pay (كل ما تعرضه صفحة الدفع الخاصة بـ Tranzila يُعرض داخل الإطار)، ولا فواتير Tranzila.

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى صفحة الدفع ولم يدفع، أو رُفضت الدفعة، أو لم يصل إشعار Tranzila بعد. في Sales > Orders لا تظهر هذه الطلبات إلا مع الفلتر Order Status المضبوط على Missing Orders. وفي OpenCart 4.1 قد تحمل هذه الطلبات الحالة Voided، التي يضبطها OpenCart عند عرض خطوة التأكيد مرة أخرى؛ وتعدّها الإضافة طلباً بلا حالة.

حالة الطلب بعد الدفع (الافتراضي Processing): تم تأكيد الدفعة بإشعار متحقَّق منه. تعرض ملاحظة المبلغ، ومعاملة Tranzila (index)، ورقم التفويض، وعدد الأقساط إن وُجدت.

On hold status (الافتراضي Pending): أُبلغ عن الدفعة لكنها لم تُقبل تلقائياً: لم يتطابق المبلغ أو العملة أو رمز المصافحة؛ أو تعذّر التحقق من الإشعار لأن Trusted IP فارغ؛ أو الإشعارات معطلة وعاد العميل من صفحة دفع ناجحة. تشرح الملاحظة السبب. تحقق من الدفعة في جهاز Tranzila الطرفي وغيّر الحالة يدوياً.

Refunded status (الافتراضي Refunded): تم استرداد الدفعة بالكامل عبر الإضافة.

إذا وصلت دفعة لطلب في حالة محتجز أو ملغى أو خطأ دفع، يحصل الطلب على Order status after payment؛ ويحصل الطلب الملغى إضافة إلى ذلك على ملاحظة تطلب منك التحقق من المخزون قبل الشحن. إذا وصلت دفعة ثانية لطلب مدفوع أو مسترَد بالفعل، أو لطلب آخر من سلة مدفوعة بالفعل، فلا يتغير الطلب. تطلب منك ملاحظة على الطلب المدفوع التحقق منه واسترداد النسخة المكررة في جهاز Tranzila الطرفي. تُتجاهل الإشعارات المكررة للمعاملة نفسها.

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

علامة تبويب VibeFox Tranzila Payment Gateway

في Sales > Orders افتح طلباً مدفوعاً عبر Tranzila. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Tranzila Payment Gateway الـ Transaction (index)، وAuthorization، وTerminal، وStatus، والمبالغ Paid / refunded، وعدد Installments، ونموذج الاسترداد، وسجل الاستردادات، وجميع Payment pages of the cart مع نتيجة كل منها، وTranzila notes الخاصة بالطلب. تظهر علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

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

يكون النموذج متاحاً عندما تكون كلمة مرور الجهاز الطرفي مضبوطة ويكون للطلب معاملة Tranzila مؤكدة. وإلا تبيّن علامة التبويب السبب، مثلاً Refunds need the terminal password (TranzilaPW) in the gateway settings. لا يمكن استرداد طلب دُفع على جهاز طرفي غير الجهاز المضبوط حالياً في الإعدادات (مثلاً جهاز اختبار) من صفحة الطلب؛ استرده في ذلك الجهاز الطرفي لـ Tranzila.

إذا لم تقبل Tranzila الاسترداد، تعرض علامة التبويب الخطأ، مثلاً Tranzila declined the refund مع الرمز ومعناه، ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع معاملة الائتمان من Tranzila. يضبط الاسترداد الكامل Refunded status للطلب دون إشعار العميل ودون إعادة المنتجات إلى المخزون، مثل تغيير الحالة يدوياً. لا يغيّر الاسترداد الجزئي الحالة.

لا ترجع مرتجعات المنتجات في Sales > Returns أي أموال عبر Tranzila. الاستردادات التي تتم في جهاز Tranzila الطرفي لا تُبلَّغ إلى المتجر. حدّث الطلب يدوياً إذا لزم الأمر.

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

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

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

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

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

لا يظهر Tranzila عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Terminal name (supplier) مملوء، وأن عملة العميل ILS أو USD أو EUR أو GBP. تعرض صفحة الإعدادات تحذيراً عندما يكون اسم الجهاز الطرفي مفقوداً أو العملة الافتراضية غير مدعومة. تحقق أيضاً من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمت عملية الدفع لكن الطلب بقي بلا حالة: لم يصل الإشعار أو رُفض. تحقق من أن Notifications مفعّل، وأن Trusted IP يسرد العناوين التي ترسل منها Tranzila الإشعارات. تُكتب الأخطاء دائماً في السجل؛ راجع حقل Log في صفحة الإضافة. تعني رسالة أن عنوان IP ليس في قائمة Trusted IP أنه يجب تصحيح إعداد Trusted IP أو إعداد الوكيل (proxy): خلف وكيل أو شبكة CDN يجب أن يمرر خادم الويب عنوان IP الحقيقي للزائر إلى PHP. وبالنسبة للمطورين الذين يقع متجرهم خلف وكيل عكسي موثوق، تُطلق الإضافة حدث OpenCart wcp_tranzila_payment_gateway/remote_ip لضبط عنوان IP.

الإشعار يرد بـ Forbidden: جاء من عنوان IP غير موجود في Trusted IP.

الإشعار يرد بـ Bad request أو Not found: الطلب أو رمز صفحة الدفع أو الجهاز الطرفي أو فهرس المعاملة في الإشعار لا يطابق أي صفحة دفع في هذا المتجر.

الإشعار يرد بـ Accepted for manual review: Trusted IP فارغ، لذلك تعذّر التحقق من الإشعار. الدفعة الناجحة تُبقي الطلب محتجزاً. املأ Trusted IP لتأكيد الدفعات تلقائياً.

الإشعار يرد بـ Busy, retry: كانت السلة تُعالَج بطلب آخر في الوقت نفسه، أو تعذّر تعيين حالة الطلب. يعرض السجل السبب. تحقق من الدفعة في جهاز Tranzila الطرفي.

بعض الطلبات في حالة on-hold: اقرأ الملاحظات في علامة التبويب VibeFox Tranzila Payment Gateway. لم يتطابق المبلغ أو العملة أو رمز المصافحة، أو تعذّر التحقق من الإشعار (Trusted IP فارغ أو الإشعارات معطلة). تحقق من الدفعة في جهاز Tranzila الطرفي وغيّر الحالة يدوياً.

لا تفتح صفحة الدفع مع تفعيل المصافحة: تحقق من اسم الجهاز الطرفي وكلمة مرور الجهاز الطرفي، ومن تفعيل المصافحة في جهاز Tranzila الطرفي، ومن السماح هناك بعنوان IP لخادمك. يعرض السجل السبب.

الاستردادات تفشل: الاستردادات تتطلب Terminal password (TranzilaPW). بعض الأجهزة الطرفية تتطلب أيضاً كلمة مرور ائتمان منفصلة؛ أدخلها في Refund password (CreditPass). الطلبات المدفوعة على جهاز طرفي آخر يجب استردادها في ذلك الجهاز. إذا كان رد Tranzila غير متوقع، تبيّن علامة التبويب أن الاسترداد لم يُؤكَّد: تحقق من جهاز Tranzila الطرفي قبل المحاولة مجدداً. من دون صلاحية تعديل الطلبات تعرض علامة التبويب You do not have permission to refund orders.

عملات أخرى: الإضافة تدعم ILS وUSD وEUR وGBP فقط.

للمطورين: قبل عرض صفحة الدفع تُطلق الإضافة حدث OpenCart wcp_tranzila_payment_gateway/payment_page_params مع حقول صفحة الدفع والطلب.

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

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

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

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