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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: 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. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد wcp_moneris_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

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

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

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

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

7. أجرِ طلب اختبار ببطاقة اختبار من Moneris، ثم ألغِ تحديد Test mode.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Moneris. تعرض الصفحة فوق الحقول رسالة Moneris gateway is in TEST MODE. No real charges will be made. ما دام وضع الاختبار مفعّلًا. وفي الوضع الفعلي تحذّرك عندما تحتوي حقول الإنتاج على بيانات اعتماد اختبار من Moneris (وعندها تُخفى البوابة في صفحة الدفع)، وعندما لا يستخدم الموقع HTTPS. كما تحذّرك إذا لم تكن عملة المتجر هي عملة حساب 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 account country: الحسابات الكندية تحصّل بالدولار الكندي CAD، والحسابات الأمريكية بالدولار الأمريكي USD. لا تظهر البوابة إلا عندما تتطابق عملة الطلب. الافتراضي: Canada (CAD).

Test mode: Enable test mode (Moneris QA gateway, test credentials, no real charges). تُرسل الاستردادات وعمليات التحصيل والإلغاء دائمًا إلى البيئة التي تم فيها الدفع. يرى العملاء 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.

الدفع

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

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

متقدم

Debug log: Log API requests and responses (card number, CVV, expiry and API token are masked). تُسجَّل الأخطاء دائمًا. يمكنك مراجعة السجل في WooCommerce > Status > Logs بالمصدر wcp_moneris_gateway. الافتراضي: معطّل.

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

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit card (Moneris)) ويُدخل رقم البطاقة وتاريخ الانتهاء ورمز الأمان في نموذج البطاقة الخاص بـ WooCommerce في صفحة الدفع لديك. عند تقديم الطلب يرسل خادمك البطاقة إلى Moneris بإجمالي الطلب ويحصل على النتيجة فورًا. لا توجد إعادة توجيه ولا webhook. يُرسل رمز الأمان (CVD) دائمًا، لذلك تظل قواعد eFraud في متجر Moneris سارية.

لا يُعلَّم الدفع الموافَق عليه كمدفوع إلا عندما يُبلغ Moneris بإتمام المعاملة وتساوي قيمة المبلغ المعالَج إجمالي الطلب. بعد ذلك ينتقل العميل إلى صفحة استلام الطلب. مع Pre-Authorization يبقى الطلب في حالة قيد الانتظار حتى تحصّل المبلغ.

إذا رُفضت البطاقة، يرى العميل Your card was declined مع السبب الذي يذكره Moneris، ويمكنه مراجعة بيانات البطاقة أو استخدام بطاقة أخرى. وإذا تعذّر على Moneris معالجة الطلب (مثلًا بسبب Store ID أو API Token غير صحيح)، يرى العميل The payment could not be processed. Please try again or use another payment method. ويُضاف السبب إلى ملاحظات الطلب والسجل. وإذا نقر العميل مرة أخرى أثناء معالجة دفعة، يظهر A payment for this order is already being processed. Please wait a moment and check your order status before trying again. ولا يُعاد خصم أي طلب مدفوع أو مُفوَّض مسبقًا.

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

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

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

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

حالات الطلب

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

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

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

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

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

لتحصيل تفويض مسبق، غيّر حالة الطلب إلى قيد المعالجة أو مكتمل، أو اختر Capture Moneris pre-authorization من إجراءات الطلب. يُحصَّل إجمالي الطلب الحالي مطروحًا منه الاستردادات، ولا يمكن أن يتجاوز المبلغ المعتمد. إذا رفض Moneris التحصيل، تعود الحالة إلى قيد الانتظار مع ملاحظة، ولا يُرسل أي بريد لطلب قيد المعالجة أو مكتمل. تنتهي صلاحية التفويضات المسبقة لدى Moneris بعد بضعة أيام، لذا حصّلها في الوقت المناسب.

لتحرير المبالغ، ألغِ الطلب أو اختر Void Moneris pre-authorization (cancel order) من إجراءات الطلب. ويؤدي تغيير الطلب إلى مسترد أيضًا إلى تحرير أي تفويض مسبق مفتوح. إذا فشل التحرير، تطلب منك ملاحظة تحريره في Merchant Resource Center.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Credit card (Moneris) (يعرض الزر Title الخاص بك). يُدعم الاسترداد الكامل والجزئي. لا يمكن استرداد التفويض المسبق إلا بعد تحصيله؛ وقبل ذلك ألغِ الطلب لتحرير المبالغ. يُرسل الاسترداد إلى البيئة والحساب اللذين تم فيهما الدفع، لذلك يجب أن تكون بيانات اعتماد ذلك الوضع مُدخلة. إذا لم يقبل Moneris الاسترداد، تعرض WooCommerce Refund failed مع السبب، ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف معاملة Moneris.

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

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

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

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

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

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

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

تمت عملية الدفع لكن الطلب بقي في حالة بانتظار الدفع أو قيد الانتظار: ليس للإضافة webhook؛ فالنتيجة تأتي فقط من رد Moneris. إذا كان الطلب في حالة قيد الانتظار وتقول ملاحظته إن Moneris لم يؤكد النتيجة، فإن 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.

يرى العميل خطأ أثناء الدفع: افتح ملاحظات الطلب أو فعّل Debug log وراجع WooCommerce > Status > Logs بالمصدر wcp_moneris_gateway.

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

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

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

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

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

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

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