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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: اليورو (EUR). تحصّل Eupago باليورو فقط، ولذلك تُخفى طريقة الدفع في صفحة الدفع للعملات الأخرى.

حساب Eupago: تحتاج إلى مفتاح API لقناة Eupago الخاصة بك، ومفتاح Webhook 2.0 الذي تنشئه في لوحة Eupago الإدارية (راجع الإعدادات). لوحة الإنتاج هي clientes.eupago.pt، ولوحة sandbox هي sandbox.eupago.pt. وبيئتا sandbox وlive حسابان منفصلان بمفاتيح منفصلة.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل مفتاح API لقناة Eupago، وأنشئ Webhook 2.0 في لوحة Eupago الإدارية، والصق مفتاحه (راجع الإعدادات).

6. اختر Payment Method، وفعّل Enable/Disable، ونفّذ طلبًا تجريبيًا في وضع sandbox، ثم ألغِ تحديد Sandbox Mode.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Eupago. عند تفعيل البوابة، تحذّرك الصفحة إذا كان مفتاح API للوضع الحالي فارغًا (فتُخفى البوابة حينها في صفحة الدفع)، أو تعرض Sandbox mode: no real payments are taken. ما دام وضع sandbox مفعّلًا. وفي قائمة طرق الدفع، تظهر Eupago بعلامة «تتطلب إجراءً» حتى يُضبط مفتاح API للوضع الحالي، ويظهر شارة وضع الاختبار في وضع sandbox.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Eupago.

Description: النص المعروض أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely via Eupago.

Payment Method: طريقة Eupago الواحدة المعروضة في صفحة الدفع.

Order Status After Payment: حالة الطلب التي تُعيَّن عند تأكيد الدفع: Processing (الافتراضي) أو Completed. وتُعيَّن الحالة فورًا، مع تغيير حالة واحد ورسالة بريد واحدة.

حساب Eupago

احصل على مفتاح API لقناتك ومفتاح Webhook 2.0 من لوحة Eupago الإدارية: clientes.eupago.pt (الإنتاج) أو sandbox.eupago.pt (sandbox).

Sandbox Mode: Enable sandbox/test mode يستخدم sandbox.eupago.pt ومفاتيح sandbox. لا تُخصم أي مدفوعات حقيقية. الافتراضي: on. ألغِ التحديد لتحصيل مدفوعات حقيقية بمفاتيح الإنتاج.

Live API Key: مفتاح API لقناة Eupago الإنتاجية الخاصة بك (clientes.eupago.pt).

Live Webhook Key: مفتاح التشفير لـ Webhook 2.0 الإنتاجي. مطلوب: تُرفض الإشعارات التي لا تحمل توقيعًا صالحًا.

Sandbox API Key: مفتاح API لقناة sandbox الخاصة بك (sandbox.eupago.pt).

Sandbox Webhook Key: مفتاح التشفير لـ Webhook 2.0 الخاص بـ sandbox.

Webhook URL

يُبلغ webhook متجرك بأن الدفع قد تم. أنشئ في لوحة Eupago الإدارية Webhook 2.0 بالرابط المعروض في هذا القسم من الإعدادات، وبطريقة POST مع تفعيل التشفير. الرابط يبدو هكذا: https://your-site/wc-api/eupago_payment_callback/. أنشئ webhook واحدًا في لوحة sandbox وآخر في لوحة الإنتاج.

انسخ مفتاح كل webhook إلى Sandbox Webhook Key أو Live Webhook Key. تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. ولا يُقبل webhook غير مشفَّر إلا إذا وقّعته Eupago، لذلك أبقِ التشفير مفعّلًا. تستجيب الإضافة لحالات الإشعارات التالية:

لا تتطلب الحالات الأخرى أي إجراء. كما يُقبل رد الاتصال القديم من نوع GET الذي ترسله Eupago إلى العنوان نفسه؛ وهو مصادَق عليه بمفتاح API ويُبلغ دائمًا عن دفع. ومن دون إشعارات لا تُعلَّم الطلبات كمدفوعة أبدًا: فالإضافة لا تستعلم من Eupago، ولا تدفع عودة العميل الطلب.

متقدم

Debug Log: Enable logging يكتب استدعاءات API والإشعارات في WooCommerce > Status > Logs، والمصدر wcp_eupago_gateway. لا تُسجَّل المفاتيح ولا رسائل البريد ولا أرقام الهواتف الكاملة. وتُسجَّل الأخطاء دائمًا. الافتراضي: off.

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

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Eupago) ثم يقدّم الطلب. في وضع sandbox تعرض صفحة الدفع SANDBOX / TEST MODE. وما يحدث بعد ذلك يعتمد على Payment Method.

Multibanco: في صفحة الدفع يرى العميل You will receive Multibanco payment details after placing the order. تُنشئ الإضافة مرجع Multibanco لإجمالي الطلب. يُوضع الطلب في حالة «في الانتظار»، ويُخصم المخزون، ويُفرَّغ السلة. وتعرض صفحة استلام الطلب Multibanco Payment Details مع الكيان والمرجع والمبلغ. وتُضاف التفاصيل نفسها إلى بريد الطلب الإلكتروني للعميل طالما الطلب ينتظر الدفع. ويدفع العميل عبر ماكينة الصراف الآلي أو الخدمات المصرفية عبر الإنترنت.

MB WAY: في صفحة الدفع يُدخل العميل MB WAY Phone Number، وهو حقل يُملأ مسبقًا برقم هاتف الفوترة. ويمكن إدخال الأرقام البرتغالية بدون +351. والرقم غير الصحيح يعرض Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). ترسل الإضافة طلب الدفع إلى تطبيق MB WAY. يُوضع الطلب في حالة «في الانتظار»، ويُخصم المخزون، ويُفرَّغ السلة. وتطلب صفحة استلام الطلب من العميل فتح تطبيق MB WAY والموافقة على الطلب خلال 5 دقائق.

Credit Card: في صفحة الدفع يرى العميل You will be redirected to a secure payment page to enter your card details. يُرسَل العميل إلى صفحة البطاقات الخاصة بـ Eupago، باللغة البرتغالية أو الإسبانية أو الإنجليزية حسب لغة الموقع. يبقى الطلب في حالة «بانتظار الدفع» وتُحفظ السلة. وبعد الدفع يعود العميل إلى صفحة استلام الطلب، وتعرض Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. إلى أن يصل الإشعار. وإذا فشل الدفع بالبطاقة أو تُرك، ينتقل العميل إلى صفحة Pay for order وتظهر له الرسالة The card payment was not completed. You can try again or choose another payment method. أو The card payment was cancelled. You can try again or choose another payment method.

في جميع الطرق، لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Eupago الدفع بإشعار موثَّق. ويمكن للعميل دفع طلب غير مدفوع مرة أخرى من صفحة Pay for order، وتظل كل مراجع الدفع التي أُنشئت للطلب صالحة للتحقق.

إذا تعذّر على Eupago بدء الدفع، يرى العميل رسالة قصيرة، مثل The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. لا يتغير الطلب، والتفاصيل موجودة في السجل.

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

تقدّم الإضافة طريقة Eupago واحدة لكل تثبيت. ولا تتضمن استردادًا من WooCommerce، ولا بطاقات محفوظة، ولا اشتراكات أو تفويضًا مسبقًا، ولا PayShop أو Cofidis Pay أو Bizum أو طرق Eupago أخرى، ولا تذكيرات برسائل SMS، ولا تاريخ انتهاء لـ Multibanco، ولا استعلامًا دوريًا عن الحالة.

الطلبات

حالات الطلب

Pending payment: بدأ دفع بالبطاقة ولم تؤكده Eupago بعد.

On hold, awaiting payment: أُنشئ مرجع Multibanco أو طلب MB WAY. تعرض ملاحظة الطلب الكيان والمرجع، أو رقم الهاتف المُخفى.

Processing or Completed: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تعرض ملاحظة الطلب طريقة الدفع ومعرّف المعاملة في Eupago والمرجع. ومعرّف معاملة الطلب هو معرّف معاملة Eupago.

On hold, manual review: أبلغت Eupago عن دفعة بمبلغ أو عملة مختلفة، أو بمرجع لم يُنشأ لهذا الطلب، أو لطلب أُلغي أو فشل في الأثناء (مثل مرجع Multibanco دُفع متأخرًا). وتوضّح الملاحظة السبب. تحقّق من الدفع والمخزون، ثم أكمل الطلب يدويًا أو استرد المبلغ للعميل. ولا تُكمل الإشعارات اللاحقة لهذه الدفعة الطلب دون علمك.

Cancelled: أبلغت Eupago بأن الدفع أُلغي أو انتهت صلاحيته، لمحاولة الدفع الحالية لطلب غير مدفوع.

Failed: أبلغت Eupago عن خطأ في محاولة الدفع الحالية لطلب غير مدفوع.

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

الاستردادات: لا تُدعَم الاستردادات من WooCommerce. استرد المبلغ للعميل من لوحة Eupago الإدارية، وسجّل الاسترداد في WooCommerce بزر Refund manually.

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

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

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

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

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

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

لا تظهر Eupago في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاح API للوضع الحالي مضبوط (Sandbox API Key في وضع sandbox، وLive API Key في وضع الإنتاج)، وأن عملة المتجر EUR. ومع Multibanco يجب أن يكون إجمالي الطلب بين 1 € و999 999.99 €.

تم الدفع لكن الطلب ما زال Pending payment أو On hold: إشعار Eupago لا يصل أو يُرفض. في لوحة Eupago الإدارية للوضع الذي تستخدمه، تحقّق من وجود Webhook 2.0، وأن رابطه مطابق تمامًا للرابط المعروض في الإعدادات، وأن الطريقة POST، وأن التشفير مفعّل. وتحقّق من أن مفتاحه موجود في الحقل المناسب (Sandbox Webhook Key أو Live Webhook Key). فعّل Debug Log وراجع WooCommerce > Status > Logs، والمصدر wcp_eupago_gateway. وإذا لم يصل إشعار أبدًا، فتحقّق من الدفعة في لوحة Eupago الإدارية.

يرد الـ webhook بـ Invalid signature أو Missing signature: مفتاح الـ webhook في الإضافة لا يطابق مفتاح الـ webhook، أو أن الـ webhook غير مشفَّر وغير موقّع. انسخ المفتاح مرة أخرى وأبقِ التشفير مفعّلًا.

يرد الـ webhook بـ Webhook key not configured: لم يُضبط أيّ من مفتاحي الـ webhook. وتعيد Eupago إرسال الإشعار بعد أن تلصق المفتاح.

يرد الـ webhook بـ Decryption failed: التوقيع صالح، لكن تعذّر فك تشفير المحتوى. تحقّق من إعدادات Webhook 2.0 في لوحة Eupago الإدارية.

يرد الـ webhook بـ Environment mismatch: الإشعار موقّع بمفتاح وضع غير الوضع الذي وُضع فيه الطلب. ولا يدفع إشعار sandbox أبدًا طلبًا في الإنتاج، والعكس صحيح.

يرد رد الاتصال القديم بـ Invalid API key: مفتاح API الذي أرسلته Eupago لا يطابق Live API Key ولا Sandbox API Key.

يرى العميل The MB WAY payment could not be started: تحقّق من أن رقم الهاتف مرتبط بـ MB WAY، ثم أعد المحاولة.

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. كان المبلغ أو العملة مختلفين، أو المرجع غير معروف، أو وصل الدفع بعد إلغاء الطلب. تحقّق من الدفع في لوحة Eupago الإدارية، ثم أكمل الطلب أو استرد المبلغ للعميل.

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

للمطورين، توثّق وثائق الإضافة الفلاتر eupago_p_icon (أيقونة صفحة الدفع) وeupago_p_card_language (لغة صفحة بطاقات Eupago: PT أو EN أو ES).

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

تعطيل الإضافة يحتفظ بجميع البيانات. ولحذفها، عطّلها ثم احذفها من صفحة Plugins. ويُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. ولا تُحذف إعدادات البوابة والسجلات إلا إذا كان Delete Data on Uninstall مفعّلًا؛ وإلا تبقى لإعادة التثبيت لاحقًا. وتُحفظ الطلبات ومراجع Eupago الخاصة بها دائمًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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