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

المتطلبات

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

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

عملة المتجر: AUD أو NZD أو SGD أو HKD أو MYR. بالنسبة إلى عملات السلة الأخرى، لا تظهر طريقة الدفع في الدفع. تُحصَّل المدفوعات بعملة السلة.

حساب eWAY: تحتاج إلى حساب تاجر لدى eWAY مع إمكانية الوصول إلى Rapid API، ومفتاحه وكلمة مروره الخاصة بـ Rapid API، وتجدهما في MyeWAY ضمن Settings, API Key. للاختبار تحتاج إلى حساب sandbox لدى eWAY بمفتاح وكلمة مرور خاصين به. مفاتيح sandbox والإنتاج مختلفة. لا يلزم إعداد أي شيء في eWAY: يُرسل رابط العودة مع كل دفعة.

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

التثبيت

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

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

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

4. أدخل مفتاح API وكلمة المرور الخاصين بـ sandbox، واترك Sandbox Mode مفعّلًا، وفعّل Enable/Disable، ثم انقر على Save وأجرِ طلب اختبار.

5. أدخل مفتاح API وكلمة المرور الخاصين بالإنتاج، وألغِ تفعيل Sandbox Mode، ثم انقر على Save.

6. اختياريًا، أضف رابط cron المعروض في صفحة Configure إلى مهام cron في الخادم (راجع قسم الإعدادات).

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

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. فوق الحقول تعرض شارة الوضع: SANDBOX — payments go to the eWAY sandbox, no real money is charged. أو LIVE — real payments are taken with the live API key. تحذّرك الصفحة عند غياب مفتاح API أو كلمة المرور للوضع الحالي (وعندها لا تظهر طريقة الدفع في الدفع)، وعند عدم دعم eWAY للعملة الافتراضية للمتجر.

eWAY

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

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

Description: النص الذي يظهر أسفل طريقة الدفع في الدفع. الافتراضي: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

بيانات اعتماد API

مفتاح Rapid API وكلمة المرور موجودان في MyeWAY ضمن Settings, API Key. تقدّم eWAY أدلة لمفاتيح الإنتاج ومفاتيح sandbox، وهي مرتبطة في هذا القسم. تستخدم sandbox والإنتاج مفاتيح مختلفة.

Sandbox Mode: تُرسل المدفوعات إلى sandbox لدى eWAY بمفتاح sandbox وكلمة مروره. لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. ألغِ تفعيله لقبول مدفوعات حقيقية بمفتاح الإنتاج. وما دام مفعّلًا يرى العملاء Test mode: no real payment is taken. أسفل طريقة الدفع.

Live API Key: مفتاح Rapid API لحساب eWAY الخاص بالإنتاج.

Live API Password: كلمة مرور Rapid API لحساب eWAY الخاص بالإنتاج.

Sandbox API Key: مفتاح Rapid API لحساب sandbox لدى eWAY (حساب الشريك/المطور).

Sandbox API Password: كلمة مرور Rapid API لحساب sandbox لدى eWAY.

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

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

Return URL / re-checks: لا حاجة إلى إعداد أي webhook أو رابط عودة في eWAY، لأن رابط العودة يُرسل مع كل دفعة. يعرض هذا الحقل رابط cron اختياريًا. استدعِه من مهمة cron في الخادم، مثلًا كل 15 دقيقة. إذا دفع العميل ثم أغلق المتصفح قبل العودة إلى المتجر، يُستعلم عن الدفعة من eWAY بعد نحو ساعة وينشأ الطلب. إذا تعذّر الوصول إلى eWAY، يُكرَّر التحقق حتى ثلاث مرات. احتفظ بهذا الرابط سرًا: فهو يتضمن رمزًا مميزًا، والطلب الذي يحمل رمزًا خاطئًا يتلقى الرد Forbidden.

الطلبات

Order Status on Success: حالة الطلب بعد أن تؤكد eWAY الدفع.

أي مبلغ أو عملة معتمدة لا تطابق الطلب تذهب دائمًا إلى eWAY payment on hold.

متقدم

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

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit Card (eWAY)) ويؤكد. تطلب الوحدة من eWAY صفحة دفع لإجمالي السلة بعملة السلة، مع PS- ورقم السلة مرجعًا للفاتورة، إضافةً إلى عنوان الفوترة والبريد الإلكتروني للعميل، ثم تنقل العميل إلى eWAY Responsive Shared Page. هناك يدفع العميل ببطاقته. يُحصَّل المبلغ فورًا. لا يوجد طلب في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا تثق الوحدة بالمتصفح: إذ تطلب من eWAY، عبر الخادم مباشرةً، نتيجة صفحة الدفع التي أُنشئت لهذه السلة. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد eWAY الدفع ويتطابق المبلغ والعملة المعتمدان مع السلة. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with eWAY has been received. وللطلب الموقوف في الانتظار، تعرض الصفحة Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

إذا تعذّر الاستعلام من eWAY في تلك اللحظة، تعرض صفحة Payment confirmation الرسالة We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. مع زر Check again وزر Back to checkout. يُنشأ الطلب عندما يعيد العميل التحقق أو عندما يعمل رابط cron.

إذا رُفض الدفع، يعود العميل إلى الدفع مع سبب الرفض، مثل Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. وإذا نقر العميل على Cancel في صفحة eWAY، تتحقق الوحدة أولًا من eWAY من عدم دفع أي مبلغ (مثلًا في تبويب آخر). ثم يرى العميل الرسالة You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. وإذا لم يكتمل الدفع، فالرسالة هي The payment was not completed. Please try again. وتُحفظ السلة في جميع الحالات.

يمكن للعميل المحاولة مرة أخرى. قبل إنشاء صفحة دفع جديدة، تُتحقق من eWAY من الصفحة السابقة للسلة. إذا كانت مدفوعة بالفعل، يُنشأ الطلب بدلًا من دفعة ثانية. إذا تعذّر على eWAY إنشاء صفحة الدفع، يبقى العميل في الدفع مع رسالة قصيرة، مثل Payment error: Unable to connect to eWAY. Please try again. أو eWAY could not start the payment مع رموز أخطاء eWAY.

لا ترسل eWAY إشعارات من الخادم إلى الخادم لـ Shared Page: تُؤخذ النتيجة عند عودة العميل وعبر رابط cron. ولا تحتوي الوحدة على حقول بطاقات في موقعك، ولا بطاقات محفوظة أو اشتراكات، ولا تفويض فقط أو تحصيل منفصل، ولا تقيّم درجات الاحتيال من Beagle (المعاملات التي تحجبها قواعد eWAY لمكافحة الاحتيال تُرفض من eWAY نفسها).

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

حالات الطلب

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

Payment accepted or Delivered: اعتُمدت الدفعة. تتبع الحالة Order Status on Success. تُسجَّل الدفعة بمعرّف معاملة eWAY، وتعرض ملاحظة معرّف المعاملة ورمز التفويض والاستجابة والوضع (sandbox أو الإنتاج).

eWAY payment on hold: اعتمدت eWAY مبلغًا أو عملة مختلفة عن السلة (مثل Approved for partial amount، أو تغيرت السلة بعد أن فتح العميل صفحة الدفع)، أو اعتُمدت الدفعة بعد أن ألغاها العميل في صفحة eWAY، أو اعتُمدت بعد إلغاء الطلب. تُسجَّل الدفعة بالمبلغ الذي حصّلته eWAY، وتشرح الملاحظة السبب. تحقّق من الطلب ثم جهّزه أو استرد الدفعة.

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

إذا اعتُمدت دفعة ثانية لسلة مدفوعة بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة استرداد النسخة المكررة في MyeWAY. ولا تُطبَّق أي دفعة معتمدة لمرجع فاتورة آخر على الطلب أبدًا.

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

تعرض صفحة الطلب كتلة eWAY payment تتضمن معرّف المعاملة ورمز التفويض والاستجابة من eWAY والحالة والوضع ومرجع الفاتورة والمبلغ المدفوع والمسترد وشارة Sandbox للمدفوعات التجريبية وسجل الاستردادات وeWAY notes الخاصة بالطلب.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر eWAY. ولا تُزامَن الاستردادات التي تُجرى في MyeWAY مع PrestaShop. حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

بدون مفتاح نشط، لا تُعرض eWAY للعملاء عند الدفع. وإذا بُدئ الدفع رغم ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يُرجى اختيار طريقة أخرى. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى back office، لذا تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager على علامة التبويب Alerts. الطلبات الحالية لا تتأثر: تبقى الدفعات التي بدأت مؤكدة، وتعمل الاستردادات.

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

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

eWAY does not appear at checkout: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاح API وكلمة المرور للوضع الحالي معيّنان (حقول sandbox في وضع sandbox، وحقول الإنتاج في وضع الإنتاج)، وأن عملة السلة هي AUD أو NZD أو SGD أو HKD أو MYR. تعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد. وفي Payment > Preferences تحقّق من السماح بالوحدة لعملة السلة وبلد العميل ومجموعة العميل.

The payment went through, but no order was created: لم يعد العميل من eWAY، أو تعذّر الاستعلام من eWAY في تلك اللحظة. لا ترسل eWAY إشعارات لـ Shared Page. اضبط رابط cron من Return URL / re-checks: فهو يلتقط الدفعة بعد نحو ساعة. تحقّق من المعاملة في MyeWAY وانظر إلى الحقل Log في صفحة الوحدة.

The customer sees This payment method is temporarily unavailable: مفتاح API أو كلمة المرور للوضع الحالي مفقودان، أو رفضتهما eWAY. تحقّق من بيانات اعتماد الوضع الحالي.

The customer sees eWAY could not start the payment: أعادت eWAY رموز أخطاء، تظهر في الرسالة. غالبًا ما تكون بيانات الفوترة غير صالحة.

The customer sees We could not match this payment to an order: رابط العودة لا ينتمي إلى سلة في هذا المتجر، أو اعتمدت eWAY دفعة لمرجع فاتورة آخر. إذا خُصم المبلغ من العميل، فابحث عن الدفعة في MyeWAY.

The customer sees We could not check the status of your previous payment attempt: كان طلب آخر يعالج السلة نفسها. يمكن للعميل المحاولة مرة أخرى بعد لحظات.

Order is eWAY payment on hold after payment: اقرأ eWAY notes في كتلة eWAY payment (راجع حالات الطلب)، ثم جهّز الطلب أو استرد الدفعة.

Refund fails with a message about the sandbox or live mode: دُفع الطلب في تلك البيئة، ومفتاح API وكلمة المرور الخاصان بها غير معيّنين. أدخلهما ثم أعد المحاولة.

Refund fails with at most … can be refunded: المبلغ أكبر من المبلغ الذي حصّلته eWAY مطروحًا منه الاستردادات السابقة.

للمطورين: تسرد ملفات README الخاصة بالوحدة الخطاف actionWcpEwaySupportedCurrencies، وذلك إذا كان حسابك لدى eWAY مفعّلًا لعملات إضافية.

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

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

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