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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

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

5. اختر Payment Method، وفعّل Enable/Disable، ثم انقر على Save. أجرِ طلبًا تجريبيًا في وضع sandbox، ثم أوقف تفعيل Sandbox Mode.

عند التثبيت تنشئ الوحدة حالتين للطلب: Awaiting Eupago payment وEupago payment on hold. يقدّم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ ويجب أن يبقى اليورو مسموحًا به للوحدة.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Eupago Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. عند تفعيل طريقة الدفع، تعرض الصفحة تحذيرًا فوق الحقول إذا كان مفتاح API للوضع الحالي فارغًا (فتُخفى طريقة الدفع في صفحة الدفع)، أو تعرض Sandbox mode: no real payments are taken. ما دام وضع sandbox مفعّلًا.

Eupago

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Eupago. مطلوب: العنوان الفارغ يعرض Enter a title for the payment method.

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

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

Order Status After Payment: حالة الطلب التي تُعيَّن عند تأكيد الدفع.

حساب Eupago

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

Sandbox Mode: يستخدم sandbox.eupago.pt ومفاتيح sandbox. لا تُحصَّل أي مدفوعات حقيقية. الافتراضي: مفعّل. أوقفه لتحصيل مدفوعات حقيقية بمفاتيح الإنتاج. وما دام مفعّلًا يرى العملاء SANDBOX / TEST MODE أسفل طريقة الدفع.

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.

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

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

عنوان URL الخاص بـ Webhook

يُخبر الـ webhook متجرك بأن الدفع قد تم. في لوحة Eupago الإدارية، أنشئ Webhook 2.0 بعنوان URL المعروض في هذا القسم، وطريقة POST، مع تفعيل التشفير. مع الروابط الودية يبدو العنوان هكذا: https://your-shop/module/wcp_eupago_gateway/webhook، وقد يتضمن رمز لغة مثل /pt/. انسخ العنوان تمامًا كما تعرضه الإعدادات. أنشئ webhook واحدًا في لوحة sandbox وآخر في لوحة الإنتاج.

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

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

متقدم

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

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة وسجلات مدفوعات Eupago لهذه الوحدة والسجل. تبقى الطلبات وبيانات الدفع الخاصة بها. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Eupago) في خطوة الدفع، ثم يُكمل الطلب. ما يحدث بعد ذلك يتوقف على Payment Method.

Multibanco: في صفحة الدفع يرى العميل You will receive Multibanco payment details after placing the order. تُنشئ الوحدة مرجع Multibanco لإجمالي السلة. يُنشأ الطلب فورًا في حالة Awaiting Eupago payment، كأي طلب في PrestaShop، وتُفرَّغ السلة. تعرض صفحة تأكيد الطلب 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 وتُنشئ الطلب في حالة Awaiting Eupago payment. تطلب صفحة تأكيد الطلب من العميل فتح تطبيق MB WAY على رقم الهاتف المُقنّع والموافقة على الطلب خلال 5 دقائق.

Credit Card: في صفحة الدفع يرى العميل You will be redirected to a secure payment page to enter your card details. يُرسَل العميل إلى صفحة البطاقات الخاصة بـ Eupago، بالبرتغالية أو الإسبانية أو الإنجليزية حسب لغة السلة. لا يوجد طلب بعد، وتُحفظ السلة. لا يُنشأ الطلب إلا عندما تؤكد Eupago الدفع. إذا وصل الإشعار قبل عودة العميل، يرى صفحة تأكيد الطلب المعتادة. وإلا تعرض صفحة Payment confirmation الرسالة Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. مع زر Check again. إذا فشل الدفع بالبطاقة أو أُلغي، يعود العميل إلى صفحة الدفع مع الرسالة 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 الدفع بإشعار موثَّق. لا تظهر تفاصيل الدفع إلا ما دام الطلب في حالة Awaiting Eupago payment. إذا أبلغت Eupago لاحقًا بأن الدفع أُلغي أو انتهت صلاحيته أو فشل، ولم يكن الطلب مدفوعًا، تعرض صفحة تأكيد الطلب الرسالة Your Eupago payment was not completed. Please contact us about this 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. لا يُنشأ أي طلب، وتبقى التفاصيل في السجل. وتعرض السلة المسعّرة بعملة أخرى الرسالة Eupago only supports payments in EUR.

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

الطلبات

حالات الطلب

No order yet: بدأت عملية دفع بالبطاقة ولم تؤكدها Eupago بعد. لا توجد إلا السلة.

Awaiting Eupago payment: أُنشئ مرجع Multibanco أو طلب MB WAY. تعرض الملاحظة الكيان والمرجع، أو رقم الهاتف المُقنّع.

Payment accepted or Delivered: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. يُسجَّل الدفع بمعرّف معاملة Eupago بوصفه معرّف المعاملة، وتعرض ملاحظة الطريقة ومعرّف المعاملة والمرجع.

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

Canceled: أبلغت Eupago بأن الدفع أُلغي أو انتهت صلاحيته، وذلك لمحاولة الدفع الحالية لطلب معلّق.

Payment error: أبلغت Eupago بخطأ في محاولة الدفع الحالية لطلب معلّق.

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

كتلة الدفع الخاصة بـ Eupago

تعرض صفحة الطلب كتلة Eupago payment تضم كل محاولات الدفع للسلة: التاريخ، والطريقة، وشارة Sandbox لمدفوعات sandbox، والمبلغ، والكيان والمرجع في Multibanco أو رقم MB WAY المُقنّع، ومعرّف معاملة Eupago، والحالة. ما دام الطلب في حالة Eupago payment on hold، تعرض الكتلة تحذير Manual review. وتحتها تعرض Eupago notes ملاحظات الوحدة على الطلب، الأحدث أولًا.

الاستردادات

لا تُدعم الاستردادات من PrestaShop. استرد المبلغ للعميل في لوحة Eupago الإدارية، وحدّث الطلب في PrestaShop يدويًا. لا ترسل أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Eupago.

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

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

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

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

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

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

تم الدفع لكن الطلب ما زال في Awaiting Eupago payment أو لم يُنشأ أي طلب: إشعار Eupago لا يصل أو يُرفض. في لوحة Eupago الإدارية للوضع الذي تستخدمه، تحقق من أن Webhook 2.0 موجود، وأن عنوانه مطابق تمامًا للعنوان المعروض في Webhook URL، وأن الطريقة POST وأن التشفير مفعّل. تحقق من أن مفتاحه موجود في الحقل المناسب (Sandbox Webhook Key أو Live Webhook Key). فعّل Debug Log وراجع حقل Log في صفحة الوحدة. إذا لم يصل أي إشعار، فتحقق من الدفع في لوحة 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 أبدًا دفعة live، والعكس صحيح. تحقق من أن مفتاحي sandbox وlive غير متبادلين.

يرد الـ webhook بـ Order not found: الإشعار يخص سلة ليس لها دفع Eupago في هذا المتجر، مثل دفعة تمت من متجر آخر بالقناة نفسها لـ Eupago.

يرد الـ webhook بـ Busy or Retry: كانت السلة قيد المعالجة بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). تُعيد Eupago إرسال الإشعار. السبب موجود في السجل.

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

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

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

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

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

Eupago علامة تجارية مملوكة لصاحبها. هذه الوحدة غير مرتبطة بـ Eupago ولا مُعتمدة منها.