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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل Terminal name (supplier)، وأدخل Terminal password (TranzilaPW) إذا كنت تستخدم الـ handshake أو الاستردادات.

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

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

8. فعّل Enable/Disable واختبر دفعة باستخدام محطة Tranzila التجريبية.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Tranzila. فوق الحقول، تحذّرك الصفحة عندما يكون اسم المحطة فارغًا (فتُخفى طريقة الدفع عندها في الدفع)، وعندما تكون الإشعارات معطلة أو يكون Trusted IP فارغًا (فتُوضع الطلبات المدفوعة عندها في الانتظار للمراجعة اليدوية)، وعندما يكون الـ handshake مفعّلًا بدون كلمة مرور المحطة (فلا يمكن فتح صفحة الدفع)، وعندما لا تكون عملة المتجر مدعومة. عند الحفظ، لا يُحفظ اسم محطة غير صالح أو إدخال غير صالح في Trusted IP: تعرض الصفحة خطأً ويبقى القيمة السابقة. تُصحَّح الأرقام خارج النطاق المسموح به إلى أقرب قيمة مسموح بها.

General

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

Title: اسم طريقة الدفع الذي يراه العملاء في الدفع. الافتراضي: Credit Card (Tranzila).

Description: النص المعروض أسفل طريقة الدفع في الدفع. الافتراضي: Pay securely with your credit card on the Tranzila payment page.

Terminal

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

Terminal password (TranzilaPW): كلمة مرور API للمحطة. مطلوبة للـ handshake وللاستردادات من WooCommerce.

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

Payment page

Payment page version: صفحة Tranzila المعروضة داخل iframe.

Payment page language: لغة صفحة Tranzila: Site language، وHebrew، وEnglish، وRussian، وSpanish، وGerman، وFrench، أو Japanese. الافتراضي: Hebrew. يستخدم Site language لغة الإعداد المحلي (locale) في WordPress الخاص بالزائر عندما تكون إحدى هذه اللغات، وإلا فيستخدم English.

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

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

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

Handshake: Lock the amount with a handshake token (recommended). قبل فتح صفحة الدفع، يطلب المتجر من Tranzila رمزًا لمرة واحدة مرتبطًا بمبلغ الطلب، بحيث لا يمكن تغيير المبلغ في المتصفح. يتطلب ذلك كلمة مرور المحطة، وتفعيل الـ handshake في محطة Tranzila، والسماح بعنوان IP لخادمك فيها. الافتراضي: معطّل.

Payment confirmation

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

Notifications: Confirm payments automatically with Tranzila notifications (notify URL). الافتراضي: مفعّل. يُرسل عنوان URL للإشعارات إلى Tranzila مع كل دفعة، لذلك لا يلزمك إدخاله في محطة Tranzila. يبدو هكذا: https://your-site/wc-api/tranzila_p_callback/ ويُعرض أسفل الحقل. عندما تكون الإشعارات معطلة، يُوضع الطلب لعميل عاد من صفحة دفع ناجحة في الانتظار، وتؤكد الدفعة يدويًا بعد التحقق منها في محطة Tranzila.

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

Advanced

Debug log: Log payment page, notification and refund events يكتب في WooCommerce > Status > Logs، بالمصدر wcp_tranzila_payment_gateway. تُسجَّل الأخطاء دائمًا حتى عند إيقاف هذا الخيار. لا تُكتب كلمات المرور والرموز وبيانات العملاء أبدًا. الافتراضي: معطّل.

Delete data on uninstall: Delete the settings, logs and Tranzila order data when the plugin is deleted. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit Card (Tranzila)) وينقر Continue to payment. يُنشأ الطلب بحالة Pending payment، وينتقل العميل إلى صفحة دفع الطلب في متجرك. هناك تُفتح صفحة دفع 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.

بعد دفعة ناجحة، تعيد Tranzila العميل وينتقل النافذة بأكملها إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Tranzila بإشعار. حتى ذلك الحين، تعرض الصفحة: 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. إذا كان الطلب في الانتظار للمراجعة، فتعرض: Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.

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

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

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

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

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

Order statuses

Pending payment: أُرسل العميل إلى صفحة الدفع ولم يدفع بعد، أو لم تصل إشعار Tranzila بعد.

Processing or Completed: أُكِّد الدفع بإشعار موثَّق. يضبط WooCommerce الحالة Processing، أو Completed للطلبات التي لا تحتاج إلى شحن. تعرض ملاحظة الطلب المبلغ ومعاملة Tranzila ورقم التفويض، وعدد الأقساط إذا وُجدت. معرّف المعاملة هو فهرس المعاملة لدى Tranzila.

On hold: استُلم الدفع لكنه لم يُقبَل تلقائيًا: المبلغ أو العملة أو رمز الـ handshake لم يتطابق مع الطلب، أو تعذّر التحقق من الإشعار لأن Trusted IP فارغ، أو الإشعارات معطلة وعاد العميل من صفحة دفع ناجحة. تشرح ملاحظة الطلب السبب. تحقق من الدفعة في محطة Tranzila وغيّر الحالة يدويًا.

Failed: أبلغت Tranzila عن دفعة مرفوضة لطلب في الانتظار. تعرض الملاحظة رمز الاستجابة ومعناه. لا يُعيَّن الطلب المدفوع بالفعل إلى Failed أبدًا.

إذا وصلت دفعة لطلب مُلغى، يُعاد فتح الطلب مع ملاحظة تطلب منك التحقق من المخزون قبل الشحن. إذا غيّر العميل طريقة الدفع في صفحة Pay for order ثم دفع في صفحة Tranzila كانت لا تزال مفتوحة، تُعاد طريقة دفع الطلب إلى Tranzila. إذا وصلت دفعة ثانية لطلب مدفوع أو مكتمل أو مسترد، فلا يتغير الطلب. تطلب ملاحظة منك التحقق من ذلك واسترداد النسخة المكررة في محطة Tranzila. تُتجاهل الإشعارات المكررة لنفس المعاملة.

Refunds

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Credit Card (Tranzila) (يعرض الزر عنوان طريقة الدفع). يُدعم الاسترداد الكامل والجزئي. يُنفَّذ الاسترداد كمعاملة ائتمان لدى Tranzila على الدفعة الأصلية. يكون الزر متاحًا عندما تكون كلمة مرور المحطة مُعيّنة ويكون للطلب معاملة Tranzila مؤكدة برقم تفويض. يُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معاملة الائتمان لدى Tranzila.

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

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

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

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

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

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

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

Tranzila does not appear at checkout: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Terminal name (supplier) معبأ، وأن عملة المتجر (في صفحة Pay for order، عملة الطلب) هي ILS أو USD أو EUR أو GBP. تعرض صفحة الإعدادات تحذيرًا عندما يكون اسم المحطة مفقودًا أو عندما لا تكون العملة مدعومة.

The payment went through, but the order stays Pending payment: لم يصل الإشعار أو رُفض. تحقق من أن Notifications مفعّل، وأن Trusted IP يتضمن العناوين التي ترسل منها Tranzila الإشعارات. تُكتب الأخطاء دائمًا في WooCommerce > Status > Logs، بالمصدر wcp_tranzila_payment_gateway. تعني رسالة أن عنوان IP غير موجود في قائمة Trusted IP أنه يجب تصحيح إعداد Trusted IP أو إعداد الوكيل (proxy): خلف وكيل أو CDN، يجب أن يمرر خادم الويب عنوان IP الحقيقي للزائر إلى PHP.

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

Notification answers Bad request or Not found: الطلب أو مفتاحه أو المحطة أو فهرس المعاملة في الإشعار لا تطابق أي طلب في هذا المتجر.

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

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

Some paid orders are On hold: اقرأ ملاحظة الطلب. المبلغ أو العملة أو رمز الـ handshake لم يتطابق، أو تعذّر التحقق من الإشعار (Trusted IP فارغ أو الإشعارات معطلة). تحقق من الدفعة في محطة Tranzila وغيّر الحالة يدويًا.

The payment page does not open with the handshake on: تحقق من اسم المحطة وكلمة مرورها، ومن أن الـ handshake مفعّل في محطة Tranzila، ومن أن عنوان IP لخادمك مسموح به هناك. يعرض السجل السبب.

Refunds fail: تحتاج الاستردادات إلى Terminal password (TranzilaPW). بعض المحطات تتطلب أيضًا كلمة مرور ائتمان منفصلة؛ أدخلها في Refund password (CreditPass). يجب استرداد الطلبات المدفوعة في محطة أخرى في تلك المحطة.

Other currencies: تدعم الإضافة ILS وUSD وEUR وGBP. يمكن للمطورين تعديل القائمة باستخدام المرشح tranzila_p_currency_map.

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

الإلغاء والحذف

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

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