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

المتطلبات

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

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

عملة المتجر: CAD لحساب Moneris الكندي، وUSD لحساب Moneris USA القديم. تظهر طريقة الدفع فقط عندما تكون عملة السلة هي عملة الحساب.

HTTPS وPCI DSS: تُدخل أرقام البطاقات في صفحة الدفع الخاصة بمتجرك وتمر عبر خادمك. تتطلب المدفوعات الفعلية HTTPS والالتزام بمعيار PCI DSS SAQ D. إذا تعذر عليك ذلك، استخدم بدلًا منه حلًا بصفحة دفع مستضافة.

حساب Moneris: تحتاج إلى Store ID وAPI Token لمتجر Moneris Gateway الخاص بك، وهما موجودان في Moneris Merchant Resource Center > Admin > Store Settings. للاختبار، يُملأ متجر الاختبار العام لدى Moneris تلقائيًا. بيانات الاعتماد للاختبار وبطاقات الاختبار موجودة في بوابة المطورين لدى Moneris.

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

التثبيت

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

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

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

4. اختر دولة الحساب وأدخل Live Store ID وLive API Token. وضع الاختبار مفعّل افتراضيًا ويستخدم متجر الاختبار العام (store5 / yesguy لكندا، وmonusqa002 / qatoken للولايات المتحدة).

5. اختر Purchase أو Pre-Authorization وشعارات البطاقات، ثم فعّل Enable / Disable وانقر على Save.

6. أجرِ طلب اختبار ببطاقة اختبار من Moneris، ثم أوقف Test mode.

عند التثبيت، تنشئ الوحدة حالتين للطلب: Moneris payment authorized وMoneris payment on hold. ويفعّل PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء افتراضيًا. يمكنك تقييدها في Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Moneris Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. طالما أن وضع الاختبار مفعّل، تعرض الصفحة فوق الحقول الرسالة Moneris gateway is in TEST MODE. No real charges will be made.. في الوضع الحي، تحذّر إذا كانت الحقول الحية تحتوي على بيانات اعتماد اختبار من Moneris (فتُخفى طريقة الدفع حينها في الدفع)، وإذا لم يكن SSL مفعّلًا للمتجر. كما تحذّر إذا لم تكن عملة المتجر الافتراضية هي عملة حساب Moneris؛ فتُخفى طريقة الدفع في الدفع للعملات الأخرى.

Moneris

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

Title: عنوان طريقة الدفع الذي يراه العميل. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit card (Moneris). في وضع الاختبار، يُضاف (Test Mode) إلى العنوان. حقل إلزامي.

Description: النص الذي يظهر فوق حقول البطاقة في الدفع. الافتراضي: Pay securely with your credit card.

حساب Moneris

يوجد Store ID وAPI Token الخاصان بك في Moneris Merchant Resource Center ضمن Admin > Store Settings. بيانات الاعتماد للاختبار وبطاقات الاختبار موجودة في بوابة المطورين لدى Moneris. يحتوي القسم على روابط إلى الاثنين.

دولة حساب Moneris: الحسابات الكندية تحصّل بالدولار الكندي CAD، والحسابات الأمريكية بالدولار الأمريكي USD. تظهر طريقة الدفع فقط عندما تتطابق عملة السلة. الافتراضي: Canada (CAD).

Test mode: يستخدم بوابة Moneris QA وبيانات الاعتماد للاختبار؛ ولا تُجرى أي خصومات حقيقية. تُرسل عمليات التحصيل والإلغاء والاسترداد دائمًا إلى البيئة التي تم فيها الدفع. يرى العملاء فوق حقول البطاقة الرسالة TEST MODE: use a Moneris test card, no real charges are made.. الافتراضي: مفعّل.

Live Store ID: معرّف متجر الإنتاج، مثل monca01234.

Live API Token: رمز API الخاص بالإنتاج.

Test Store ID: متجر الاختبار العام لدى Moneris: store5 (كندا) أو monusqa002 (الولايات المتحدة). الافتراضي: store5.

Test API Token: رمز الاختبار العام: yesguy (كندا) أو qatoken (الولايات المتحدة). الافتراضي: yesguy.

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

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

الدفع

Transaction type: طريقة خصم المبلغ من البطاقة. الافتراضي: Purchase.

Card logos: علامات البطاقات التي تظهر مع طريقة الدفع في صفحة الدفع: Visa وMastercard وDiscover وAmerican Express وJCB. تعتمد العلامات المقبولة على حساب Moneris لديك. الافتراضي: Visa وMastercard.

متقدم

Debug log: يسجّل طلبات API واستجاباتها في logs/wc_mng_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُقنّع أرقام البطاقات وCVV وتاريخ الانتهاء وAPI token. تُسجَّل الأخطاء دائمًا حتى عند إيقاف هذا الخيار. الافتراضي: معطّل.

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

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

الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا Credit card (Moneris)) ويُدخل Card number وExpiry (MM/YY) وCard code (CVC) في نموذج البطاقة الذي يظهر أسفل الخيار. الحقول الثلاثة كلها إلزامية. وعند تقديم الطلب، يرسل خادمك البطاقة إلى Moneris بإجمالي السلة ويحصل على النتيجة فورًا. لا توجد إعادة توجيه ولا webhook. تُستخدم بيانات البطاقة لهذا الطلب وحده؛ ولا تُحفظ أبدًا، ويُظهر السجل آخر أربعة أرقام فقط.

لا يُنشأ الطلب إلا من رد موافقة من Moneris. ثم يرى العميل صفحة تأكيد الطلب المعتادة. مع Pre-Authorization يبقى الطلب في Moneris payment authorized حتى تحصّل المبالغ. إذا عالج Moneris مبلغًا يختلف عن إجمالي السلة، أو تغيّرت السلة أثناء الدفع، يُنشأ الطلب في Moneris payment on hold مع ملاحظة.

إذا رُفضت البطاقة، يبقى العميل في صفحة الدفع مع الرسالة Your card was declined والسبب الذي أعلنه Moneris، ويمكنه مراجعة بيانات البطاقة أو استخدام بطاقة أخرى. لا يُنشأ أي طلب. وإذا تعذّر على Moneris معالجة الطلب (مثلًا بسبب Store ID أو API Token خاطئ)، يرى العميل الرسالة The payment could not be processed. Please try again or use another payment method.. ويُكتب السبب في السجل. أما أخطاء بيانات البطاقة فتعطي رسائل قصيرة مثل Invalid card number. أو Invalid card expiry date.، ولا يُرسل شيء إلى Moneris.

النقر الثاني أو فتح تبويب ثانٍ للمتصفح أثناء معالجة دفعة يعرض الرسالة A payment for this order is already being processed. Please wait a moment and check your order status before trying again.. لا تُخصم سلة لها طلب موجود مرة أخرى؛ بل يُوجَّه العميل إلى الطلب القائم.

إذا لم يرد Moneris (خطأ في الشبكة أو انتهاء المهلة)، ترسل الوحدة إلى Moneris طلب Status Check بمعرّف طلب Moneris نفسه لمعرفة ما إذا كانت المعاملة قد تمت. فإذا لم تكن لدى Moneris معاملة كهذه، يمكن للعميل الدفع مرة أخرى. وإذا لم يحصل Status Check على رد أيضًا، يُنشأ الطلب في Moneris payment on hold مع معرّف طلب Moneris، ولا يُدعى العميل إلى الدفع مرة ثانية.

لا تتضمن الوحدة بطاقات محفوظة أو Moneris Vault، ولا اشتراكات، ولا Apple Pay أو Google Pay أو Interac Online، ولا Moneris Checkout أو Hosted Tokenization، ولا 3-D Secure أو AVS أو Kount، ولا تسعيرًا بعملات متعددة.

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

حالات الطلب

No order yet: رُفضت البطاقة أو لم تُعالج. لا يوجد سوى السلة والمحاولة في السجل. يمكن للعميل الدفع مرة أخرى.

Payment accepted: تمت الموافقة على عملية الشراء. يُسجَّل الدفع برقم معاملة Moneris كمعرّف للمعاملة.

Moneris payment authorized: تمت الموافقة على التفويض المسبق وينتظر التحصيل. لم يُسجَّل أي دفع بعد.

Moneris payment on hold: اختلف المبلغ المعالَج عن إجمالي السلة، أو تغيّرت السلة أثناء الدفع، أو لم يؤكد Moneris النتيجة، أو كتب PrestaShop حالة مدفوعة رغم فشل التحصيل. وتشرح الملاحظات ذلك. في حالة الشراء بمبلغ مختلف، يُسجَّل الدفع بالمبلغ الذي عالجه Moneris.

Canceled: بالنسبة إلى طلب مُفوَّض مسبقًا، يحرر الإلغاء المبالغ المحجوزة (void).

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

كتلة الدفع Moneris

تعرض صفحة الطلب كتلة Moneris payment تتضمن معرّف طلب Moneris، ودولة الحساب ووضعه، وشارة Test mode للمدفوعات التجريبية، وTrans ID (وTrans ID للتفويض المسبق بعد التحصيل)، ونوع المعاملة وحالتها (غير محصّلة أو محصّلة أو محرّرة)، والإيصال ونوع البطاقة، والمبلغ المعالَج، وإجمالي الطلب والمبلغ المسترد، وسجل الاستردادات، وMoneris notes الخاصة بالطلب. وفي حالة الدفع غير المؤكد، تطلب الكتلة منك البحث عن معرّف طلب Moneris في Merchant Resource Center. وتحتاج جميع الإجراءات في الكتلة إلى صلاحية تعديل الطلبات فقط.

التحصيل والإلغاء

لتحصيل تفويض مسبق، انقر على Capture payment في الكتلة ثم أكّد، أو غيّر حالة الطلب إلى حالة مدفوعة مثل تم قبول الدفع أو تم الشحن أو تم التسليم. يُحصَّل إجمالي الطلب مطروحًا منه الاستردادات، ولا يمكن أن يتجاوز المبلغ المعتمد. بعد التحصيل بالزر يصبح الطلب Payment accepted، ويُسجَّل الدفع بـ Trans ID للتحصيل. وإذا رفض Moneris التحصيل، لا تتغير الحالة، ولا يُرسل بريد الحالة المدفوعة، وتشرح ملاحظة السبب: Status not changed: the Moneris pre-authorization could not be captured مع السبب. تنتهي صلاحية التفويضات المسبقة لدى Moneris بعد بضعة أيام، لذا حصّلها في الوقت المناسب.

لتحرير المبالغ، انقر على Void pre-authorization (cancel order) أو غيّر الطلب إلى Canceled. كما أن تغيير الطلب إلى Refunded يحرر تفويضًا مسبقًا مفتوحًا. وإذا فشل التحرير، تطلب ملاحظة منك تحريره في Merchant Resource Center.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر Moneris.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Moneris Gateway هي الكتلة الأولى في صفحة Modules > Module Manager > VibeFox Moneris Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُقنَّعًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: presta-payment-moneris ورابط 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.

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

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

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

لا يظهر Moneris في الدفع: تحقّق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي فيه Store ID وAPI Token. في الوضع الحي يجب أن تحتوي الحقول الحية على بيانات الاعتماد الإنتاجية، لا على بيانات اختبار Moneris. تحقّق من أن عملة السلة هي عملة الحساب: CAD لكندا، وUSD لحساب أمريكي. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لتلك العملة ولدولة العميل ولمجموعة العميل.

تمت عملية الدفع لكن الطلب في Moneris payment on hold: ليس للوحدة webhook؛ فالنتيجة تأتي فقط من رد Moneris. اقرأ Moneris notes في الكتلة. إذا لم يؤكد Moneris النتيجة، فهذا يعني أنه لم يرد وأن Status Check فشل أيضًا. ابحث عن معرّف طلب Moneris في Merchant Resource Center: إذا كانت المعاملة موجودة هناك فشحن الطلب (وأعد الاسترداد هناك إن لزم)؛ وإذا لم تكن موجودة فألغِ الطلب أو اطلب من العميل الدفع مرة أخرى. وإذا كان المبلغ مختلفًا، فراجع الطلب ونفّذه أو استرد الدفع.

يرى العميل الرسالة Payment gateway is misconfigured. Please contact the store administrator.: بيانات اعتماد الوضع الحالي مفقودة، أو أن الوضع الحي مفعّل وفيه بيانات اختبار Moneris في الحقول الحية. أدخل Store ID وAPI Token الإنتاجيين.

يرى العميل الرسالة This payment method does not support the order currency.: عملة السلة ليست عملة حساب Moneris.

يرى العميل خطأً أثناء الدفع: انظر إلى حقل Log في صفحة الوحدة. تُكتب الأخطاء دائمًا؛ فعّل Debug log لرؤية الطلبات والردود كاملة.

يفشل التحصيل: ليس للطلب تفويض مسبق بانتظار التحصيل، أو إجمالي الطلب صفر، أو أن المبلغ أكبر من المبلغ المعتمد. وتنتهي صلاحية التفويضات المسبقة لدى Moneris أيضًا بعد بضعة أيام.

يفشل الاسترداد أو التحصيل أو الإلغاء برسالة عن الوضع أو الحساب: تمت عملية الدفع في وضع الاختبار أو الوضع الحي، وبيانات اعتماد ذلك الوضع غير مضبوطة، أو تمت عملية الدفع بحساب Moneris من دولة أخرى. أدخل بيانات الاعتماد، أو عالج الدفع في Merchant Resource Center.

هجمات اختبار البطاقات: نماذج البطاقات المباشرة هدف لاختبار البطاقات. استخدم قواعد eFraud أو velocity في حساب Moneris لديك، ووحدة CAPTCHA أو تحديد المعدل لمتجرك.

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

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

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