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

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

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

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

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

التثبيت

1. في لوحة الإدارة انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Tranzila Payment Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

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

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

عند التثبيت تنشئ الوحدة حالة الطلب Tranzila payment on hold. يمنح PrestaShop وحدة دفع جديدة جميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. فوق الحقول تحذرك الصفحة عندما يكون اسم المحطة فارغًا (فتُخفى وسيلة الدفع في صفحة الدفع)، وعندما تكون الإشعارات معطلة أو يكون Trusted IP فارغًا (فتُوقف الطلبات المدفوعة للمراجعة اليدوية)، وعندما يكون الـ handshake مفعّلًا بدون كلمة مرور للمحطة (فلا يمكن فتح صفحة الدفع)، وعندما لا تكون عملة المتجر الافتراضية مدعومة. عند الحفظ لا يُحفظ اسم محطة غير صالح، ولا إدخال غير صالح في Trusted IP، ولا حقل رقمي ليس عددًا صحيحًا: تعرض الصفحة خطأً ويبقى القيم السابقة. الرقم خارج النطاق المسموح يُحفظ كأقرب قيمة مسموح بها، وتخبرك الصفحة بذلك.

Tranzila

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

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

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

المحطة

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

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

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

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

Clear saved passwords: ضع علامة على كلمة مرور وانقر على Save لحذفها. الحقل الفارغ يُبقي القيمة المحفوظة.

صفحة الدفع

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

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

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

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

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

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

تأكيد الدفع

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

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

Notification URL: يُعرض للاطلاع. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_tranzila_payment_gateway/notify، وقد يتضمن رمز لغة. يُرسل الرابط إلى Tranzila مع كل دفعة، لذلك لا تحتاج إلى إدخاله في محطة Tranzila.

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

متقدم

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

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

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

الدفع

في خطوة الدفع يختار العميل وسيلة الدفع (افتراضيًا Credit Card (Tranzila)) ويرى الوصف والملاحظة After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the 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 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.

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

تعمل الإشعارات أثناء وضع الصيانة للمتجر، ولا يحجبها تقييد الدول في متجرك. تُستخدم صفحة الدفع نفسها مع قالبي Classic وHummingbird.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى صفحة الدفع ولم يدفع، أو رُفض الدفع، أو لم يصل إشعار Tranzila بعد. لا توجد سوى السلة.

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

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

Refunded: استُرد الدفع بالكامل عبر الوحدة.

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

كتلة الدفع في Tranzila

تعرض صفحة الطلب كتلة Tranzila payment تتضمن رقم معاملة Tranzila ورقم التفويض والمحطة والحالة والمبلغ المدفوع والمسترد وعدد الأقساط وسجل الاستردادات، وجميع Payment pages of the cart مع نتيجتها، وTranzila notes الخاصة بالطلب.

الاستردادات

في كتلة Tranzila payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا السبب، ثم انقر على Refund via Tranzila. أكّد السؤال Refund this amount via Tranzila? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الطلبات؛ الوصول إلى صفحات الوحدات غير مطلوب. يُنفَّذ الاسترداد كمعاملة ائتمان لدى Tranzila للدفعة الأصلية، عبر المحطة التي حصّلتها، وبالمبلغ والعملة اللذين خصمتهما Tranzila فعليًا. لذلك بعد اختلاف في المبلغ أو العملة، يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب.

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

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

لا تنشئ الوحدة إشعارات دائنة (credit slips). أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا ترد الأموال عبر Tranzila. الاستردادات التي تُجرى في محطة Tranzila لا تُبلَّغ إلى المتجر. حدّث الطلب يدويًا إذا لزم الأمر.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Tranzila Payment Gateway هي الكتلة الأولى في Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مموّهًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. أسفلها سطر Product: presta-payment-tranzila ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة الواجهة الخلفية (تشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

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

من دون مفتاح نشط لا يظهر Tranzila للعملاء في صفحة الدفع. إذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. واجهة متجر PrestaShop لا تعرف أنك مسجّل الدخول إلى الواجهة الخلفية، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها في صفحة الدفع. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: الدفعات التي بدأت تُؤكَّد بإشعار Tranzila وبعودة العميل إلى المتجر، والاستردادات تعمل.

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

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

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

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

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

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

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

الإشعار يجيب Busy, retry: كانت السلة قيد المعالجة بطلب آخر في الوقت نفسه، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطلة). السجل يبيّن السبب. تحقق من الدفع في محطة Tranzila؛ إذا كان معتمدًا هناك ولم يُنشأ أي طلب، فتواصل مع العميل أو أنشئ الطلب يدويًا.

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

صفحة الدفع لا تُفتح مع تفعيل الـ handshake: تحقق من اسم المحطة وكلمة مرورها، ومن تفعيل الـ handshake في محطة Tranzila، ومن أن عنوان IP لخادمك مسموح به هناك. السجل يبيّن السبب.

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

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

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Tranzila Payment Gateway، واختر Uninstall. مفتاح الترخيص وحالة الترخيص لهذه الوحدة تُحذفان دائمًا. إذا كان Delete data on uninstall مفعّلًا تُحذف الإعدادات والسجلات. إذا كان معطلًا تُحفظ جميع الإعدادات لإعادة تثبيت لاحقة. معاملات Tranzila والاستردادات وحالة الطلب Tranzila payment on hold تبقى دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. الطلبات الحالية تحتفظ بملاحظات الدفع ومعرّفات المعاملات.

Tranzila علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Tranzila ولا تحظى بتأييدها.