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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

خدمة 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 إرسال الإشعارات إلى متجرك، لذا يجب أن يكون متاحًا من الإنترنت دون وضع الصيانة أو المصادقة الأساسية (basic authentication) أو جدار حماية يحجب طلبات POST.

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

التثبيت

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

2. انقر Activate.

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

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

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

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

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

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Autopay. وتحذّرك الصفحة فوق الحقول عندما يكون 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: Use the Autopay test environment (testpay.autopay.eu) and the test credentials below. الافتراضي: مفعّل. أوقفه لاستقبال مدفوعات حقيقية على pay.autopay.eu باستخدام بيانات اعتماد الإنتاج.

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

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

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

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

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

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

أدخل هذين العنوانين في بوابة Autopay لخدمتك، للإنتاج وللاختبار. وتظهر العناوين الدقيقة في هذا القسم من الإعدادات.

ITN (transaction notification) URL: https://your-site/?wc-api=wc_ap_payment

Return URL (after payment): https://your-site/?wc-api=wc_ap_return

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

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

SUCCESS: تم الدفع؛ يُعلَّم الطلب كمدفوع بعد التحقق من المبلغ والعملة.

PENDING: بدأ الدفع؛ وتُضاف ملاحظة.

FAILURE: فشل الدفع؛ ويصبح الطلب المنتظر «فشل».

متقدم

Logging: Log payment events إلى WooCommerce > Status > Logs، والمصدر wcp_autopay_payment. لا تُسجَّل المفاتيح وبيانات العميل أبدًا. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Autopay) ويقدّم الطلب. تعرض الصفحة التالية Thank you for your order. You are being redirected to Autopay to complete the payment. وتنقل العميل إلى صفحة الدفع الخاصة بـ Autopay. وإذا عاد العميل بزر الرجوع في المتصفح، تعرض الصفحة زر Pay with Autopay بدلًا من التحويل مرة أخرى.

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

بعد الدفع يعود العميل إلى صفحة استلام الطلب. عنوان العودة موقّع، لكنه لا يغيّر حالة الطلب أبدًا. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Autopay الدفع عبر ITN موقّع، ويتطابق المبلغ والعملة مع الطلب.

إذا فشل الدفع يصبح الطلب «فشل»، ويمكن للعميل الدفع مجددًا من الطلب عبر رابط Pay. وإذا تعذّر بدء الدفع يرى العميل رسالة قصيرة، مثل Autopay payments are not configured. Please choose another payment method or contact the store. أو أن Autopay لا تقبل المدفوعات بهذه العملة.

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

لا تتضمن الإضافة استردادًا من WooCommerce، ولا اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة (1-Click)، ولا رمز BLIK أو نموذج بطاقة في صفحة الدفع، ولا اختيارًا للبنك أو قناة الدفع في صفحة الدفع. وتستخدم معرّف Service ID واحدًا لكل بيئة.

الطلبات

Order statuses

Pending payment: أُرسل العميل إلى Autopay ولم تؤكد Autopay الدفع بعد.

Processing or Completed: أكدت Autopay الدفع. تضع WooCommerce الطلب في حالة «قيد التنفيذ»، أو «مكتمل» للطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل. وتعرض ملاحظة الطلب المبلغ ومعاملة Autopay وتاريخ الدفع. ومعرّف المعاملة هو رقم معاملة Autopay (RemoteID).

On hold: أبلغت Autopay بمبلغ أو عملة يختلفان عن إجمالي الطلب، فلم يُعلَّم الطلب كمدفوع وأصبح «في الانتظار». تحقق من المعاملة في بوابة Autopay، وأكمل الطلب أو استرده يدويًا.

Failed: فشل الدفع. يمكن للعميل الدفع مجددًا من الطلب.

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

الاسترداد

لا يُدعم الاسترداد من WooCommerce. استرد المبلغ في بوابة Autopay، ثم سجّله في WooCommerce باسترداد يدوي.

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

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

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

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

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

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

Autopay لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن البيئة المحددة تحتوي على Service ID وShared key، وأن عملة المتجر محددة في Currencies. وتعرض صفحة الإعدادات تحذيرًا عند نقص أحد هذه العناصر.

تمت عملية الدفع لكن الطلب ما زال Pending payment: لم تُسلّم Autopay الـ ITN، أو رفضه المتجر. تحقق من أن عنوان ITN الظاهر في الإعدادات مضبوط للخدمة في بوابة Autopay (الإنتاج أو الاختبار)، ومن أن دالة التجزئة SHA-256، ومن أن مفتاح Shared key في الإضافة يطابق الخدمة. وتحقق من أن المتجر متاح من الإنترنت. فعّل Logging وراجع WooCommerce > Status > Logs، والمصدر wcp_autopay_payment.

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

يُظهر السجل أن معرّف الخدمة غير مضبوط: جاء الإشعار من خدمة لم يُدخَل Service ID الخاص بها في الإضافة.

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

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

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

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

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

إلغاء تفعيل الإضافة يُبقي جميع البيانات. للإزالة، ألغِ التفعيل ثم احذفها من صفحة Plugins. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالته، وكذلك إعدادات البوابة. ولا يوجد خيار للاحتفاظ بالإعدادات. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات معاملاتها.

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