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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. أدخل مفتاح الإنتاج الخاص بـ API وكلمة مروره، وألغِ تحديد Sandbox Mode، ثم احفظ.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > eWAY. فوق الحقول تعرض شارة الوضع: SANDBOX (تذهب المدفوعات إلى sandbox الخاص بـ eWAY، ولا يُخصم أي مبلغ حقيقي) أو LIVE (تُعالج المدفوعات الحقيقية بمفتاح API الإنتاج). تحذّرك الصفحة عندما يكون مفتاح API أو كلمة المرور الخاصة بالوضع الحالي مفقودين (وعندها لا تظهر البوابة في صفحة الدفع)، وعندما لا تكون عملة المتجر مدعومة. وفي قائمة طرق الدفع، يُعلَّم eWAY على أنه بحاجة إلى إعداد إلى أن تتوفر بيانات الاعتماد للوضع الحالي، ويظهر شارة وضع الاختبار في وضع sandbox.

عام

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: Enable sandbox (test) mode يرسل المدفوعات إلى sandbox الخاص بـ eWAY بمفتاح sandbox. لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. ألغِ التحديد لتحصيل مدفوعات حقيقية بمفتاح الإنتاج.

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

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

Sandbox API Key: مفتاح Rapid API لحساب eWAY التجريبي (partner/developer) الخاص بك.

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

الطلبات

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

متقدم

Debug log: Enable logging يسجّل استدعاءات API ونتائج المدفوعات في WooCommerce > Status > Logs، بالمصدر wcp_eway_payment_gateway. لا تُسجَّل بيانات البطاقات ولا المفاتيح. تُسجَّل الأخطاء دائمًا. الافتراضي: معطّل.

Uninstall: Delete all plugin data on uninstall. عند تحديده، تُحذف إعدادات البوابة وسجلاتها عند حذف الإضافة. تبقى مراجع الدفع المحفوظة في الطلبات. الافتراضي: معطّل.

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا تثق الإضافة بالمتصفح: إذ تطلب من eWAY، عبر الخادم مباشرة، نتيجة صفحة الدفع التي أُنشئت لهذا الطلب. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد eWAY، وعند تطابق المبلغ المعتمد والعملة مع الطلب. ثم يصل العميل إلى صفحة «تم استلام الطلب». إذا تعذّر الاستعلام من eWAY في تلك اللحظة، يبقى الطلب في حالة «بانتظار الدفع»، وتعرض الصفحة الرسالة 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. ويُعاد التحقق من الدفع عند فتح صفحة «تم استلام الطلب»، وقبل أن يلغي WooCommerce الطلب غير المدفوع تلقائيًا.

إذا رُفض الدفع، يعود العميل إلى صفحة الدفع (أو إلى صفحة Pay for order) مع سبب الرفض، مثل Your payment was declined: Insufficient funds. Please try again or use a different payment method. وإذا نقر العميل على Cancel في صفحة eWAY، تتحقق الإضافة أولًا من eWAY من أنه لم يُدفع أي مبلغ. ثم يُلغى الطلب الذي أُنشئ في صفحة الدفع، أما الطلب الذي دُفع من صفحة Pay for order فيبقى غير مدفوع. ويرى العميل الرسالة 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 إنشاء صفحة الدفع، يرى العميل رسالة قصيرة، مثل Payment error: Unable to connect to eWAY. Please try again.

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى eWAY ولم يدفع بعد، أو لم يمكن جلب النتيجة من eWAY بعد (تشير ملاحظة الطلب إلى ذلك).

Processing or Completed: تمت الموافقة على الدفع. وتتبع الحالة Order Status on Success. تعرض ملاحظة الطلب معرّف معاملة eWAY ورمز التفويض والرد. ومعرّف معاملة الطلب هو معرّف معاملة eWAY.

On hold after payment: اعتمدت eWAY مبلغًا أو عملة تختلف عن الطلب (مثل Approved for partial amount، أو عُدّل الطلب بعد أن فتح العميل صفحة الدفع)، أو اعتُمد الدفع بعد إلغاء الطلب. وتشرح الملاحظة ذلك. وفي صفحة «تم استلام الطلب» يرى العميل الرسالة Your payment was received and is being reviewed by the store. We will contact you if anything is needed. أكمل الطلب أو استرد الدفعة.

Failed: رفضت eWAY الدفع. تعرض الملاحظة رمز eWAY ومعناه.

Cancelled: ألغى العميل في صفحة eWAY بعد تقديم الطلب في صفحة الدفع، أو أُلغي الطلب من قِبلك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce، بعد أن أكدت eWAY أنه لم يُدفع.

إذا اعتُمدت دفعة ثانية لطلب مدفوع أصلًا، فلن يتغير الطلب. وتطلب ملاحظة منك استرداد المكرر في MyeWAY.

الاستردادات

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

الاستردادات التي تُجرى في MyeWAY لا تُزامَن مع WooCommerce. وإذا لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce دون استخدام زر الاسترداد الخاص بـ eWAY.

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

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

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

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

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

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

eWAY does not appear at checkout: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن مفتاح API وكلمة المرور الخاصين بالوضع الحالي مُعدّان (حقول sandbox في وضع sandbox، وحقول الإنتاج في وضع الإنتاج)، وأن عملة المتجر هي AUD أو NZD أو SGD أو HKD أو MYR. وفي صفحة Pay for order تُتحقَّق عملة الطلب.

The payment went through, but the order stays Pending payment: لم يعد العميل من eWAY، أو تعذّر الاستعلام من eWAY في تلك اللحظة. لا ترسل eWAY إشعارات لـ Shared Page. يُعاد التحقق من الدفع عند فتح صفحة «تم استلام الطلب»، وقبل أن يلغي WooCommerce الطلب غير المدفوع. تحقق من المعاملة في MyeWAY، وراجع WooCommerce > Status > Logs، بالمصدر wcp_eway_payment_gateway.

يرى العميل الرسالة This payment method is temporarily unavailable: مفتاح API أو كلمة المرور الخاصان بالوضع الحالي مفقودان، أو رفضتهما eWAY. تحقق من بيانات اعتماد الوضع الحالي.

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

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

يرى العميل الرسالة We could not confirm your payment with eWAY: تعذّر التحقق من نتيجة الدفع. يُحدَّث الطلب عند جلب النتيجة، ولا ينبغي للعميل أن يدفع مرة أخرى.

Order is On hold after payment: اقرأ ملاحظة الطلب. اختلف المبلغ المعتمد أو العملة عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. أكمل الطلب أو استرد الدفعة.

يفشل الاسترداد برسالة تتعلق بوضع sandbox أو الإنتاج: دُفع الطلب في تلك البيئة، ومفتاح API وكلمة المرور الخاصان بها غير مُعدّين. أدخلهما وأعد المحاولة.

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

للمطوّرين: يذكر ملف readme مرشّح eway_p_supported_currencies، في حال كان حسابك في eWAY مفعّلًا لعملات إضافية.

الإزالة

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

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