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

المتطلبات

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

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

العملة: اليورو (EUR) فقط. تُخفى طريقة الدفع عندما لا تكون عملة السلة EUR. تقبل ifthenpay مبالغ من 0٫01 إلى 99٬999٫99 EUR.

حساب ifthenpay: سجّل في ifthenpay.com. تحتاج إلى مفتاح الطريقة التي تقدمها: Multibanco أو MB WAY أو Credit Card (الصيغة ABC-123456). تُعرض المفاتيح في الواجهة الخلفية لـ ifthenpay (backoffice.ifthenpay.com) أو ترسلها ifthenpay عند تفعيل الطريقة لحسابك. يجب أن تفعّل ifthenpay أيضًا الـ callback لمفتاحك (انظر الإعدادات)، ويجب أن يكون متجرك متاحًا من الإنترنت.

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

التثبيت

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

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox ifthenpay Gateway في قائمة الوحدات النمطية وانقر على Configure. تُنشئ الوحدة النمطية مفتاح مكافحة التصيد الخاص بها عند التثبيت.

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

4. اختر Payment Method، وأدخل مفتاح ifthenpay الخاص بها، ثم انقر على Save بحيث يتطابق Callback URL مع الطريقة المختارة.

5. انسخ Anti-phishing Key وCallback URL المعروضين في الإعدادات، واطلب من ifthenpay تفعيل الـ callback لمفتاحك (في الواجهة الخلفية أو عبر دعم ifthenpay).

6. فعّل Enable/Disable وانقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة النمطية: Modules > Module Manager > VibeFox ifthenpay Gateway > Configure. كل قسم يحتوي على زر Save يحفظ الصفحة بأكملها. بدون مفتاح الطريقة المختارة لا تُعرض طريقة الدفع عند الدفع. وأثناء تفعيل البوابة بدون هذا المفتاح، تعرض الصفحة ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.

ifthenpay

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

Title: عنوان طريقة الدفع الذي يظهر عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. القيمة الافتراضية: ifthenpay.

Description: وصف طريقة الدفع الذي يظهر عند الدفع. القيمة الافتراضية: Pay via Multibanco, MB WAY or Credit Card. غيّره ليتطابق مع الطريقة التي تقدمها.

Payment Method: الطريقة المعروضة عند الدفع. المطلوب فقط مفتاح هذه الطريقة.

مفاتيح ifthenpay

تُعرض المفاتيح (الصيغة ABC-123456) في الواجهة الخلفية لـ ifthenpay، أو ترسلها ifthenpay عند تفعيل طريقة الدفع لحسابك.

Multibanco Key: مفتاح ifthenpay Multibanco (MB) الخاص بك للمراجع الديناميكية.

MB WAY Key: مفتاح ifthenpay MB WAY الخاص بك.

Credit Card Key: مفتاح ifthenpay Credit Card الخاص بك. كما يتحقق من توقيع عودة العميل من صفحة البطاقات.

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

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

Callback (إشعارات الدفع)

يُخبر الـ callback متجرك بأن الدفع قد تم. اطلب من ifthenpay تفعيل الـ callback لكل مفتاح تستخدمه، مع مفتاح مكافحة التصيد وعنوان الـ callback المذكورين أدناه. تُؤكَّد طلبات Multibanco وMB WAY بالـ callback فقط؛ وتُؤكَّد مدفوعات البطاقات أيضًا بالعودة الموقعة من صفحة البطاقات.

Anti-phishing Key: تُنشئه الوحدة النمطية، ويُعرض لنسخه. ترسله ifthenpay مع كل callback؛ وتُرفض الـ callback التي لا تحتوي عليه.

Callback URL: عنوان الـ callback لطريقة الدفع المختارة، مع العناصر النائبة الخاصة بـ ifthenpay، ويُعرض لنسخه. مع الروابط الودية يبدأ هكذا: https://your-shop/module/wcp_ifthenpay_gateway/callback، وقد يحتوي على رمز لغة مثل /en/، ثم يتبعه معاملات الطريقة. انسخ الرابط كاملًا تمامًا كما يظهر في الإعدادات.

يُقارَن مفتاح مكافحة التصيد في كل callback بمفتاحك. المفتاح المفقود أو الخاطئ يتلقى ردًا بالرمز 403، ولا يتغير الطلب. يجب أن يطابق الـ callback أيضًا دفعة من هذه الوحدة النمطية: في Multibanco بالكيان والمرجع، وفي MB WAY بالسلة وأحد طلبات MB WAY الخاصة بها، وفي Credit Card بالسلة وأحد طلبات البطاقة الخاصة بها. بدون callback يعمل، لا تُؤكَّد طلبات Multibanco وMB WAY أبدًا، ولا تُؤكَّد مدفوعات البطاقات إلا بالعودة الموقعة. يعمل الـ callback أثناء وضع الصيانة للمتجر، ولا يتأثر بقيد الدول الخاص بمتجرك.

متقدم

Test Mode: تستخدم Credit Card وMultibanco نقاط النهاية التجريبية (sandbox) لـ ifthenpay؛ ولا يُخصم أي مبلغ حقيقي، وتستخدم مفاتيح الاختبار التي توفرها ifthenpay. ليس لـ MB WAY بيئة تجريبية: اختبره بمفتاح اختبار من ifthenpay. يعرض الدفع شارة TEST MODE. القيمة الافتراضية: off.

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفع مؤكَّد، مع تغيير واحد للحالة.

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

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

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

الدفع

Multibanco. عند الدفع يرى العميل You will receive a Multibanco reference to complete the payment. وعندما يؤكد العميل، تُنشئ الوحدة النمطية مرجع Multibanco ديناميكيًا لإجمالي السلة، ويُنشأ الطلب في حالة Awaiting ifthenpay payment. تعرض صفحة تأكيد الطلب Multibanco Payment Details: الكيان والمرجع والمبلغ، مع Please use these details to pay at any Multibanco ATM or through your online banking. وتُضاف التفاصيل نفسها إلى بريد تأكيد الطلب. يُدفع الطلب عندما ترسل ifthenpay callback الدفع.

MB WAY. يُدخل العميل MB WAY phone number (912 345 678 أو +351 912 345 678 أو 351#912345678 للدول الأخرى)؛ ويُملأ هاتف عنوان الفوترة تلقائيًا. ترسل الوحدة النمطية طلب دفع إلى الهاتف، ويُنشأ الطلب في حالة Awaiting ifthenpay payment. تقول صفحة تأكيد الطلب: A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. يُدفع الطلب عندما ترسل ifthenpay الـ callback. يُخزَّن رقم هاتف مُقنَّع فقط.

بطاقة الائتمان. يرى العميل You will be redirected to a secure page to enter your card details. ويُوجَّه إلى صفحة البطاقات الخاصة بـ ifthenpay. لا يوجد طلب بعد، وتُحفظ السلة. بعد دفع ناجح يعود العميل إلى متجرك. لا تُقبل العودة إلا مع توقيع صالح من ifthenpay، والمفتاح الآمن للسلة، وسر خاص بتلك المحاولة، وطلب البطاقة الخاص بالسلة؛ عندها يُنشأ الطلب كمدفوع ويرى العميل صفحة تأكيد الطلب القياسية. إذا تعذّر التحقق من العودة فلا يتغير شيء، وتعرض صفحة Payment confirmation الرسالة Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. مع زر Check again؛ وينشئ الـ callback الطلب فور وصوله. إذا فشل الدفع بالبطاقة أو أُلغي، يعود العميل إلى الدفع مع الرسالة 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. تُحفظ كل محاولة دفع بالبطاقة للسلة، لذلك يبقى الدفع الذي تم في تبويب أقدم مقبولًا.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد ifthenpay للدفع، ويُتحقق من المبلغ حتى السنت مقابل إجمالي الطلب. إذا تعذّر بدء الدفع، يبقى العميل عند الدفع مع رسالة قصيرة، مثل The Multibanco reference could not be created. Please try again or choose another payment method. أو The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. أو The payment service is temporarily unavailable. Please try again in a few minutes. يُكتب السبب الفني في السجل.

تقدم الوحدة النمطية طريقة واحدة من ifthenpay في كل مرة. ولا تدعم Payshop أو Cofidis Pay أو Apple Pay أو Google Pay أو PIX أو Pay-by-Link، ولا الاشتراكات أو البطاقات المحفوظة، ولا الانتهاء أو الإلغاء التلقائي لمراجع Multibanco غير المدفوعة، ولا الاستعلام عن حالة الدفع.

الطلبات

حالات الطلب

No order yet: بدأ دفع بالبطاقة ولم يُؤكَّد بعد، أو فشل أو أُلغي. لا يوجد سوى السلة.

Awaiting ifthenpay payment: صدر مرجع Multibanco أو أُرسل طلب MB WAY. يخفض PrestaShop المخزون عند إنشاء الطلب. لا تُلغي المراجع غير المدفوعة وطلبات MB WAY المرفوضة الطلب تلقائيًا؛ ألغِ هذه الطلبات بنفسك عند الحاجة.

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

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

الدفعة الثانية لطلب مدفوع بالفعل تضيف ملاحظة فقط، للتحقق من وجود دفع مكرر في الواجهة الخلفية لـ ifthenpay. لا تُعاد فتح الطلبات المستردة ولا الطلبات الملغاة بعد الدفع أبدًا.

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

تعرض صفحة الطلب كتلة ifthenpay payment تضم محاولات دفع الطلب (التاريخ، والطريقة، وشارة Sandbox لمدفوعات الاختبار، والمبلغ، والكيان والمرجع في Multibanco أو هاتف MB WAY المُقنَّع، ومعرّف طلب ifthenpay والحالة)، وتحذير Manual review طالما أن الطلب في حالة ifthenpay payment on hold، وifthenpay notes الخاصة بالطلب.

الاسترداد

الاسترداد من PrestaShop غير مدعوم. استرد الدفع في الواجهة الخلفية لـ ifthenpay، وسجّله يدويًا في PrestaShop. لا تضيف الـ callback الخاصة بالاسترداد (DEVOLVIDO) سوى ملاحظة. والحالات الأخرى التي تبلغ عنها ifthenpay تضيف ملاحظة فقط أيضًا.

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

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

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

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

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

لا تظهر ifthenpay عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاح Payment Method المختار مملوء، وأن عملة السلة EUR، وأن الإجمالي بين 0٫01 و99٬999٫99 EUR. في Payment > Preferences تحقق من أن الوحدة النمطية مسموحة لـ EUR ولدولة العميل ولمجموعته.

دفع العميل لكن الطلب يبقى في Awaiting ifthenpay payment أو لم يُنشأ أي طلب: الـ callback لا يصل إلى متجرك. تحقق من أن ifthenpay فعّلت عنوان الـ callback ومفتاح مكافحة التصيد للمفتاح الذي تستخدمه، وأن العنوان هو عنوان الطريقة المختارة. يجب أن يكون المتجر متاحًا من الإنترنت، لا على localhost ولا خلف تسجيل دخول. ابحث عن أسطر Callback rejected في الحقل Log في صفحة الوحدة النمطية.

الـ callback يرد بالرمز 403 Forbidden: مفتاح مكافحة التصيد في الـ callback مفقود أو مختلف عن المفتاح في الإعدادات. أرسل المفتاح المعروض في الإعدادات إلى ifthenpay مرة أخرى.

الـ callback يرد بالرمز 503 Not configured: لم يُنشأ مفتاح مكافحة التصيد بعد. افتح إعدادات الوحدة النمطية مرة واحدة؛ ستعيد ifthenpay محاولة الـ callback.

الـ callback يرد بالرمز 503 Busy: كانت السلة نفسها تُعالَج بطلب آخر في تلك اللحظة. ستعيد ifthenpay محاولة الـ callback.

الـ callback يرد Order not found: المرجع أو الطلب لا يتبع دفعة من هذه الوحدة النمطية، أو طُلبت السلة بطريقة دفع أخرى.

لماذا وُضع طلب مدفوع في حالة الانتظار؟ كان المبلغ المستلم مختلفًا عن إجمالي الطلب، أو وصل الدفع بعد إلغاء الطلب. اقرأ الملاحظات في كتلة ifthenpay payment، وتحقق من الدفع في الواجهة الخلفية لـ ifthenpay، ثم أكمل الطلب أو استرده يدويًا.

تعذّر إرسال طلب MB WAY: رقم الهاتف غير مرتبط بـ MB WAY أو صيغته خاطئة. استخدم 912 345 678، أو 351#912345678 لأرقام الدول الأخرى.

وضع الاختبار وMB WAY: لا تملك ifthenpay بيئة تجريبية لـ MB WAY؛ استخدم مفتاح اختبار توفره ifthenpay.

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

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

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