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

المتطلبات

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

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

خدمة Autopay: تحتاج إلى Service ID ومفتاح Shared key (مفتاح التجزئة) لخدمة Autopay الخاصة بك. وهما معروضان في بوابة التاجر لدى Autopay: portal.autopay.eu للإنتاج وtestportal.autopay.eu للاختبار. لخدمات الاختبار Service ID ومفتاح Shared key خاصان بها؛ اطلب من Autopay فتح واحدة. يجب أن تكون دالة التجزئة للخدمة SHA-256.

العملة: يجب أن تكون عملة السلة PLN أو EUR أو GBP أو USD أو CZK، وأن تقبلها خدمتك لدى Autopay.

متجر قابل للوصول: يجب أن تتمكن Autopay من إرسال الإشعارات إلى متجرك، لذلك يجب أن يكون متاحًا من الإنترنت دون مصادقة أساسية ودون جدار ناري يحجب طلبات POST. ولا يحجب وضع الصيانة وقيد الدولة في متجرك الإشعارات.

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

التثبيت

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

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

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

4. أدخل Service ID ومفتاح Shared key (للاختبار والإنتاج) واختر عملات خدمتك.

5. في بوابة Autopay اضبط عنوان ITN وعنوان العودة ودالة التجزئة SHA-256 لخدمتك (راجع الإعدادات).

6. فعّل Enable/Disable وانقر على Save. أجرِ طلبًا تجريبيًا في وضع الاختبار، ثم أوقف Test mode للمدفوعات الحقيقية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Autopay Payment > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذّرك الصفحة إذا كان Service ID أو Shared key للبيئة المختارة فارغًا، وإذا لم تكن عملة المتجر الافتراضية محددة في Currencies. وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع (للعملة غير المحددة).

Autopay

Enable/Disable: Enable Autopay payment gateway يشغّل طريقة الدفع أو يوقفها. الافتراضي: مُوقَف.

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

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

خدمة Autopay

يظهر Service ID ومفتاح Shared key في بوابة التاجر لدى Autopay (portal.autopay.eu أو testportal.autopay.eu، والرابط موجود في هذا القسم).

Test mode: يستخدم بيئة اختبار Autopay (testpay.autopay.eu) وبيانات الاعتماد التجريبية أدناه. الافتراضي: مُفعَّل. أوقفه لقبول المدفوعات الحقيقية على pay.autopay.eu ببيانات الإنتاج.

Service ID (production): معرّف الخدمة الرقمي من portal.autopay.eu.

Shared key (production): مفتاح التجزئة لخدمة الإنتاج. احتفظ به سرًّا.

Service ID (test): معرّف الخدمة الرقمي من testportal.autopay.eu.

Shared key (test): مفتاح التجزئة لخدمة الاختبار.

عند الحفظ يُرفض Service ID الذي يحتوي على رموز غير الحروف والأرقام والشرطات والشرطات السفلية مع خطأ، ولا يُحفظ أي شيء. ولا تُعرض مفاتيح Shared key المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها.

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

Currencies: العملات التي تقبلها خدمتك لدى Autopay: PLN وEUR وGBP وUSD وCZK. يفتح Autopay عادةً خدمة منفصلة لكل عملة. وتُعرض طريقة الدفع فقط عندما تكون عملة السلة محددة هنا. الافتراضي: PLN.

إشعارات الدفع (ITN) وعنوان العودة

أدخل هذه العناوين في بوابة Autopay لخدمتك، للإنتاج وللاختبار. تظهر العناوين الدقيقة في حقل Addresses من هذا القسم. وعند استخدام الروابط الودية تبدو هكذا، وربما مع رمز لغة مثل /en/:

انسخ العناوين تمامًا كما تعرضها الإعدادات. ومن دون عنوان ITN لا تُنشأ الطلبات أبدًا، لأن PrestaShop لا ينشئ الطلب إلا عندما تؤكد Autopay الدفع. ويُتحقق من كل ITN بتجزئة SHA-256 المحسوبة بمفتاح Shared key الخاص بالخدمة المذكورة في الإشعار. وتُرفض الإشعارات التي لا تحمل تجزئة صالحة أو تحمل Service ID غير معروف. ولا يُطبَّق الإشعار على سلة إلا إذا بدأ دفعها بالخدمة نفسها لدى Autopay، لذلك لا يؤكد إشعار اختبار أبدًا دفعة إنتاج. أما الإشعارات الخاصة بالمدفوعات التي بدأت قبل تبديل Test mode فتظل تُتحقق بالمفتاح الصحيح، ما دامت بيانات الاعتماد الاثنتان محفوظتين.

تتعامل الوحدة مع حالات الدفع التالية في ITN:

متقدم

Logging: يكتب أحداث الدفع في logs/wc_ap_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. ولا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: مُوقَف. وما دام موقوفًا لا يُكتب أي شيء، بما في ذلك الأخطاء.

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Autopay) مع وصفها ويؤكد. تعرض الصفحة التالية Thank you. You are being redirected to Autopay to complete the payment. Your order is created as soon as Autopay confirms it. وتنقل العميل إلى صفحة الدفع الخاصة بـ Autopay. وإذا عاد العميل بزر الرجوع في المتصفح، تعرض الصفحة زر Pay with Autopay بدلًا من إعادة التوجيه مرة أخرى. ولا يوجد طلب بعد في هذه المرحلة.

تمرر الوحدة إجمالي السلة بعملة السلة، ورقم السلة كمرجع للطلب، والوصف (Cart والرقم)، وبريد العميل الإلكتروني. وفي صفحة Autopay يختار العميل طريقة الدفع ويدفع.

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Autopay عبر ITN موقّع، ويتطابق المبلغ والعملة مع السلة. عندها يُنشأ الطلب ويتلقى العميل رسائل الطلب القياسية من PrestaShop. وبعد الدفع يعود العميل إلى متجرك. وعنوان العودة موقّع، لكنه لا ينشئ طلبًا أو يغيّره أبدًا. وإذا كان الطلب موجودًا بالفعل، يرى العميل صفحة تأكيد الطلب القياسية. وإذا لم يصل ITN بعد، تعرض صفحة Payment confirmation النص Thank you. Your payment is being confirmed by Autopay — your order will be created as soon as Autopay confirms it, and you will receive an e-mail. مع الزرين Check again وBack to checkout.

إذا أبلغت Autopay عن دفع فاشل، يعود العميل إلى صفحة الدفع مع The payment was not completed. You can try again or choose another payment method. وتُحفظ السلة. وإذا تعذّر بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل Autopay payments are not configured. Please choose another payment method or contact the store.، أو رسالة تفيد بأن Autopay لا تستطيع قبول المدفوعات بهذه العملة.

لا تدعم الوحدة الاسترداد من PrestaShop، ولا الاشتراكات أو المدفوعات المتكررة، ولا البطاقات المحفوظة، ولا رمز BLIK أو نموذج البطاقة في صفحة الدفع، ولا اختيار البنك أو قناة الدفع في صفحة الدفع، وتستخدم Service ID واحدًا لكل بيئة.

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى Autopay ولم يدفع، أو فشل الدفع، أو لم تؤكد Autopay الدفع بعد. لا توجد سوى السلة.

Payment accepted: أكدت Autopay الدفع، ويتطابق المبلغ والعملة. يُسجَّل الدفع بمعرّف معاملة Autopay (remoteID) كمعرّف للمعاملة، وتعرض ملاحظة المبلغ ومعاملة Autopay وتاريخ الدفع.

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

لا يتغيّر طلب مدفوع أبدًا بإشعار فشل لاحق. وإذا أبلغت Autopay عن دفعة ناجحة أخرى لطلب مدفوع، تحذّر ملاحظة من أن العميل ربما دفع مرتين. ولا يُطبَّق إشعار خاص بدفعة بدأت بخدمة Autopay أخرى، وتشرح ملاحظة ذلك. والملاحظات مرئية للموظفين فقط، في كتلة Autopay payment في صفحة الطلب.

كتلة Autopay payment

تعرض صفحة الطلب كتلة Autopay payment تتضمن Autopay OrderID، وService ID والبيئة، والمبلغ والعملة، وحالة الدفع، ومعرّف معاملة Autopay، وشارة Test mode للمدفوعات التجريبية، وملاحظات Autopay notes للطلب. والكتلة للقراءة فقط.

المبالغ المستردة

الاسترداد عبر Autopay غير مدعوم. استرجع الدفعة في بوابة Autopay، ثم سجّلها في PrestaShop بأدوات الطلبات القياسية.

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

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

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

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

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

لا يظهر Autopay في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مُفعَّل، وأن البيئة المختارة لديها Service ID ومفتاح Shared key، وأن عملة السلة محددة في Currencies. وتعرض صفحة الإعدادات تحذيرًا عند غياب أي منها. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

تم الدفع، لكن لم يُنشأ أي طلب: لم تُسلّم Autopay الإشعار ITN، أو رفضه المتجر. تحقق من أن عنوان ITN المعروض في الإعدادات مضبوط للخدمة في بوابة Autopay (الإنتاج أو الاختبار)، وأن دالة التجزئة هي SHA-256، وأن مفتاح Shared key في الوحدة يطابق الخدمة. وتحقق من أن المتجر متاح من الإنترنت. وفعّل Logging وراجع حقل Log في صفحة الوحدة.

يُظهر السجل ITN rejected: invalid hash: مفتاح Shared key لا يطابق الخدمة، أو دالة التجزئة للخدمة ليست SHA-256.

يُظهر السجل أن service ID غير مُعدّ: جاء الإشعار من خدمة لم يُدخل Service ID الخاص بها في الوحدة، أو مفتاح Shared key الخاص بها فارغ.

يُظهر السجل could not lock the cart, Autopay will retry: كانت السلة تُعالَج بإشعار آخر في اللحظة نفسها. ويرد المتجر بحيث ترسل Autopay الإشعار مرة أخرى. ويحدث الأمر نفسه عندما تعذّر إنشاء الطلب، مثلًا لأن الوحدة مُوقفة.

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

تقول ملاحظة إن الإشعار لم يُطبَّق (NOT applied): لم يبدأ دفع هذا الطلب بخدمة Autopay هذه، مثل إشعار اختبار لطلب حقيقي. تحقق من المعاملة في بوابة Autopay.

بعد الدفع يصل العميل إلى الصفحة الرئيسية: تعذّر التحقق من عنوان العودة، مثلًا لأن Service ID غير مُدخل في الوحدة. ولا يتأثر الطلب؛ إذ يتبع ITN.

يرى العميل This payment method is not available.: طريقة الدفع غير معروضة لهذه السلة (موقوفة، أو بيانات الاعتماد ناقصة، أو العملة غير محددة، أو غير مسموح بها في Payment > Preferences).

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

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

Autopay علامة تجارية تعود إلى مالكها. هذه الوحدة غير تابعة لـ Autopay ولا معتمدة من قِبلها.