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

المتطلبات

WordPress: 6.2 أو أحدث.

WooCommerce: 7.1 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

حساب Quickpay: تحتاج إلى قيمتين من لوحة Quickpay: مفتاح API لمستخدم API (لإنشاء المدفوعات والتحصيل والاسترداد)، والمفتاح الخاص بالحساب (للتحقق من توقيع استدعاءات Quickpay). لا يلزم إعداد أي شيء آخر في Quickpay. يجب أن يكون موقعك متاحًا من الإنترنت، وألا يكون محميًا بكلمة مرور أو في وضع الصيانة، حتى تصل استدعاءات Quickpay.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق مفتاح API والمفتاح الخاص من لوحة Quickpay، ثم انقر Test API key (انظر الإعدادات).

6. اختر وضع التحصيل وحالة الطلب بعد الدفع، وفعّل Enable/Disable ثم احفظ. وبينما يكون حساب Quickpay في وضع الاختبار، فعّل Test payments وأجرِ دفعة باستخدام بطاقة اختبار Quickpay.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Quickpay. وإلى أن يُدخَل مفتاح API والمفتاح الخاص معًا، يظهر Quickpay في قائمة طرق الدفع بحالة تحتاج إلى إعداد، ويُخفى عند الدفع، لأنه لا يمكن إنشاء الدفعة أو تأكيدها.

عام

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely by card or MobilePay on the Quickpay payment page.

بيانات اعتماد Quickpay API

في لوحة Quickpay (manage.quickpay.net) افتح Settings > Integration. انسخ مفتاح API لمستخدم API (Settings > Users) والمفتاح الخاص بالحساب. يعرض القسم أيضًا عنوان URL للاستدعاء لمتجرك، ويبدو هكذا: https://your-site/wc-api/qpg_quickpay/. يُرسل تلقائيًا مع كل دفعة، لذلك لا يلزم إعداد أي شيء في Quickpay.

API key: مفتاح API لمستخدم API في Quickpay. يُستخدم لإنشاء المدفوعات والتحصيل والاسترداد.

أسفل الحقل، يتحقق الزر Test API key من المفتاح المكتوب في الحقل (أو المحفوظ، إن كان الحقل فارغًا) عبر طلب موثَّق إلى Quickpay. ويرد بإحدى الرسائل Connection successful — the API key is valid. أو Quickpay rejected the API key. أو API key is not configured. أو Connection failed: متبوعة بالسبب.

Private key: المفتاح الخاص بالحساب. يُستخدم للتحقق من توقيع استدعاءات Quickpay (HMAC-SHA256). وبدونه لا يمكن تأكيد أي دفعة، وتُرفض الاستدعاءات.

Test payments: Accept payments made with Quickpay test cards. ليس لدى Quickpay بيئة اختبار منفصلة (sandbox): فبينما يكون حسابك في وضع الاختبار، تُنفَّذ المدفوعات ببطاقات الاختبار وتُعلَّم بأنها اختبار. فعّله فقط أثناء الاختبار. وعند إيقافه، لا تُعلِّم مدفوعة الاختبار الطلب كمدفوع أبدًا، بل يُضاف إلى الطلب ملاحظة بدلًا من ذلك. وعند تفعيله، تعرض صفحة الدفع الرسالة Test mode: Quickpay test cards are accepted.. الافتراضي: معطّل.

الدفع

Capture: الوقت الذي يُخصم فيه المبلغ من البطاقة.

Order status after payment: حالة الطلب بعد أن يؤكد Quickpay الدفعة المحصّلة. تُعيَّن الحالة مرة واحدة، مع تغيير واحد للحالة ومجموعة واحدة من رسائل البريد الإلكتروني.

متقدم

Debug log: Enable logging. يوجد السجل في WooCommerce > Status > Logs، والمصدر wcp_quickpay_gateway. تُسجَّل الأخطاء والتحذيرات، مثل الاستدعاءات المرفوضة وأخطاء Quickpay API، دائمًا. فعّل هذا الخيار لتسجيل كل طلب واستدعاء أيضًا. ولا تُسجَّل مفاتيح API أو بيانات البطاقات أو تفاصيل العملاء أبدًا. الافتراضي: معطّل.

Delete data: Delete the gateway settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف شيئًا أبدًا. تبقى بيانات الطلبات (معرّفات دفعات Quickpay والملاحظات) محفوظة دائمًا. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Quickpay، ويظهر مع أيقونتي Visa وMastercard) ويقدّم الطلب. تنشئ الإضافة دفعة Quickpay للطلب بعملة الطلب ورابط دفع بإجمالي الطلب، وتنقل العميل إلى نافذة دفع Quickpay. يدفع العميل هناك بإحدى الطرق المفعّلة في نافذة دفع Quickpay لديك. ويُمرَّر بريد الفوترة إلى Quickpay. تُفتح نافذة الدفع بلغة موقعك عندما يوفرها Quickpay (الدنماركية والألمانية والإنجليزية والإسبانية والفنلندية والفرنسية والإيطالية والهولندية والنرويجية والبولندية والسويدية)، وإلا فبالإنجليزية.

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. والعودة بحد ذاتها لا تُعلِّم أي شيء كمدفوع. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكده Quickpay عبر الاستدعاء الموقَّع، ويتطابق المبلغ والعملة مع الطلب. وعند استخدام Authorize only، ينتقل الطلب إلى حالة «في الانتظار» بدلًا من ذلك، وتحصّل الدفعة لاحقًا.

إذا ألغى العميل في نافذة الدفع أثناء الشراء، يُلغى الطلب غير المدفوع بالطريقة المعيارية في WooCommerce، وتُستعاد سلة المشتريات. وفي صفحة Pay for order، يعيد الإلغاء العميل إلى تلك الصفحة، فيبقى الطلب قابلًا للدفع. ويمكن إعادة محاولة الدفعة الفاشلة أو الملغاة: فالمحاولة الجديدة تعيد استخدام دفعة Quickpay الخاصة بالطلب برابط جديد، فلا يمكن دفع الرابط القديم بالتوازي أبدًا. وعند إلغاء طلب غير مدفوع يُحذف رابط الدفع الخاص به في Quickpay.

إذا تعذر بدء الدفع، يرى العميل الرسالة The Quickpay payment could not be started. Please try again or choose another payment method. وتُضاف السبب التقني إلى ملاحظات الطلب والسجل. وإذا كانت المفاتيح مفقودة، يرى العميل الرسالة Quickpay is not available at the moment. Please choose another payment method.

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

تقبل الإضافة المدفوعات لمرة واحدة فقط. لا تتضمن اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة، ولا رسوم دفع، ولا ترسل سلة المشتريات أو بنود الفاتورة إلى Quickpay، ولا تتضمن طرقًا منفصلة لـ MobilePay أو Apple Pay أو Klarna: يختار العميل من بين طرق نافذة دفع Quickpay لديك.

الطلبات والاستردادات

حالات الطلب

Pending payment: أُرسل العميل إلى Quickpay ولم يدفع بعد. ومع التحصيل التلقائي، تُسجَّل على الطلب أي دفعة مُفوَّضة تنتظر التحصيل.

Processing or Completed: أكد Quickpay الدفعة المحصّلة بالمبلغ والعملة الصحيحين. وتتبع الحالة Order status after payment. وتعرض ملاحظة الطلب معرّف دفعة Quickpay (مع وسم TEST للمدفوعات التجريبية)، ويُحفظ كمعرّف المعاملة للطلب.

On hold: الدفعة مُفوَّضة فقط وتنتظر Capture Quickpay payment؛ أو أبلغ Quickpay عن مبلغ أو عملة تختلف عن إجمالي الطلب (مثلًا عُدّل الطلب بعد بدء الدفع، أو حُصّل مبلغ مختلف في لوحة Quickpay)؛ أو فشل التحصيل ولا يزال المبلغ محجوزًا فقط. وتشرح ملاحظة الطلب ذلك، حتى عندما يكون الطلب في حالة «في الانتظار» من قبل.

Failed: رُفضت محاولة الدفع. يمكن للعميل الدفع مرة أخرى.

Cancelled: ألغى العميل في نافذة الدفع، أو ألغيت الطلبية منك أو بسبب مهلة حجز المخزون في WooCommerce، أو أُلغيت الدفعة في لوحة Quickpay.

لا تغيّر أي دفعة تصل لطلب مدفوع أو ملغى أو مُسترَد الطلب. وتطلب منك ملاحظة مراجعة الدفعة في لوحة Quickpay، مثلًا لاسترداد دفعة مكررة.

التحصيل

مع Authorize only، افتح الطلب، واختر Capture Quickpay payment من إجراءات الطلب، ثم انقر زر التحديث. يُحصَّل إجمالي الطلب؛ ولا يتوفر التحصيل الجزئي. فإن أكد Quickpay فورًا، يُعلَّم الطلب كمدفوع. وإلا فستوضح ملاحظة أن التحصيل قد طُلب، ويُعلَّم الطلب كمدفوع عندما يؤكد استدعاء Quickpay ذلك. ويظهر التحصيل المرفوض في شاشة الطلب ويُدوَّن في ملاحظات الطلب.

إلغاء طلب مُفوَّض لا يحرر المبلغ المحجوز تلقائيًا. وتذكّرك ملاحظة الطلب بإلغاء الدفعة في لوحة Quickpay؛ وإلا فسينتهي الحجز عند انتهاء صلاحية التفويض.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Quickpay. يُدعم الاسترداد الكامل والجزئي للمدفوعات المحصّلة. ويعالج Quickpay الاستردادات بشكل غير متزامن: تشير ملاحظة إلى أنه طُلب استرداد، ويضيف الاستدعاء النتيجة النهائية، confirmed أو FAILED مع السبب. وإن رفض Quickpay الاسترداد فورًا، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ولا يمكن استرداد دفعة مُفوَّضة لم تُحصَّل أبدًا؛ ألغِها في لوحة Quickpay.

تُدوَّن المدفوعات والاستردادات التي تتم مباشرةً في لوحة Quickpay على الطلب فقط. ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce. وإذا لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Quickpay.

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

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

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

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

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

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

Quickpay لا يظهر عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن كلًا من API key وPrivate key مُدخل. ومن دون المفتاحين تُخفى طريقة الدفع.

تمت عملية الدفع، لكن الطلب يبقى في حالة Pending payment: لم يصل استدعاء Quickpay إلى متجرك أو رُفض. تحقق من أن موقعك متاح من الإنترنت (دون حماية بكلمة مرور أو وضع صيانة)، وأن Private key هو المفتاح الخاص بالحساب نفسه في Quickpay. وتُكتب الاستدعاءات المرفوضة دائمًا في WooCommerce > Status > Logs، والمصدر wcp_quickpay_gateway. فعّل Debug log لرؤية كل استدعاء.

يُظهر السجل Callback rejected: invalid checksum.: المفتاح الخاص في الإعدادات لا يخص الحساب الذي أرسل الاستدعاء. انسخه مجددًا من Settings > Integration في لوحة Quickpay.

يُظهر السجل Callback rejected: the private key is not configured.: أدخل المفتاح الخاص. فلا تُقبل الاستدعاءات أبدًا دونه.

يُظهر السجل Callback: no order found for payment …: ينتمي الاستدعاء إلى دفعة Quickpay لا يعرفها أي طلب في هذا المتجر، مثل دفعة أُنشئت خارج WooCommerce أو لطلب محذوف.

يُظهر السجل Callback: order #… is locked by another request.: كان استدعاء آخر للطلب نفسه يُطبَّق في تلك اللحظة. ويُرد على الاستدعاء بخطأ، فلا يُعتبر مُعالَجًا. وإذا بقي الطلب دون تغيير، فتحقق من الدفعة في لوحة Quickpay.

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

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. قد تكون الدفعة مُفوَّضة فقط وتنتظر Capture Quickpay payment، أو قد يختلف المبلغ أو العملة المدفوعان عن الطلب، أو فشل التحصيل. حصّل المبلغ، أو أنجز الطلب، أو استرد الدفعة من لوحة Quickpay.

Test API key يُظهر Quickpay rejected the API key.: المفتاح خاطئ أو يخص مستخدمًا ليس لديه صلاحية API. انسخ مفتاح API لمستخدم API من لوحة Quickpay.

يرى العميل The Quickpay payment could not be started.: افتح ملاحظات الطلب أو السجل. تعرض الملاحظة خطأ Quickpay، مثل عملة لا يقبلها حساب Quickpay لديك.

يفشل الاسترداد: يجب أن يكون للطلب دفعة Quickpay محصّلة. وتعني الرسالة The Quickpay payment of this order has not been captured — there is nothing to refund. أن الدفعة مُفوَّضة فقط؛ ألغِها في لوحة Quickpay بدلًا من ذلك.

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

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

يؤدي تعطيل الإضافة إلى الاحتفاظ بجميع البيانات. ولإزالتها، عطّلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة وسجلات الإضافة (ملفات السجل، بما فيها الملفات المؤرشفة، وإدخالات السجل في قاعدة البيانات) فتُحذف فقط إذا كان Delete data مفعّلًا. وإلا فتبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

Quickpay علامة تجارية مسجّلة لمالكها. هذه الإضافة غير تابعة لـ Quickpay ولا معتمدة من قِبلها.