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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

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

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

التثبيت

يحتوي التنزيل على ملف zip واحد يضم الحزم الخاصة بإصداري OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_quickpay_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_quickpay_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر فوق Upload، ثم اختر الملف wcp_quickpay_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا تحتاج Extensions > Modifications إلى تحديث. وبدلًا من أداة التثبيت، يمكنك أيضًا نسخ محتويات مجلد upload الموجود في هذه الحزمة إلى المجلد الجذري لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox Quickpay Gateway، وانقر فوق Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر فوق Upload، ثم اختر الملف wcp_quickpay_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة بعد إعادة تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر فوق Install (زر + الأخضر) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Quickpay Gateway، وانقر فوق Install (زر + الأخضر)، ثم فوق Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح Quickpay والإعدادات كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. يختلف عنوان الاستدعاء (Callback URL) فقط (انظر الإعدادات).

يبدأ التثبيت الجديد بطريقة الدفع معطّلة.

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Quickpay Gateway > Edit. تظهر الأقسام في الجهة اليسرى، ويحفظ زر Save أسفل القائمة الصفحة بأكملها. وإلى أن يُحفظ كل من مفتاح API والمفتاح الخاص، تعرض الصفحة Quickpay needs setup: enter the API key and the private key. Until both are saved the payment method is hidden at checkout. وأثناء تفعيل Test payments، تذكّرك الصفحة بإيقافه عندما يصبح حساب Quickpay فعّالًا. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب أن يكون Title بين حرف واحد و128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا (الأرقام السالبة مسموحة)، ويجب أن يكون Total عددًا أكبر من 0 أو يساويه، ويجب أن تكون المنطقة الجغرافية وكل حالة طلب موجودة. وإلا لا يُحفظ شيء وتذكر الصفحة الحقل.

Quickpay

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

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

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely by card or MobilePay on the Quickpay payment page.

Sort Order: ترتيب Quickpay بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Quickpay فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المختارة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي سلة الشراء، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Quickpay: عدد أكبر من 0 أو يساويه. اتركه فارغًا لعرض Quickpay مهما كان المبلغ.

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

في مدير Quickpay (manage.quickpay.net، تحتوي الصفحة على روابط إليه)، افتح Settings > Integration. انسخ مفتاح API لمستخدم API (Settings > Users) والمفتاح الخاص بالحساب.

Callback URL: يعرض عنوان الاستدعاء الخاص بمتجرك. يبدو في OpenCart 3 هكذا: https://your-store/index.php?route=extension/payment/wcp_quickpay_gateway/callback، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_quickpay_gateway/payment/wcp_quickpay_gateway.callback ويُنشأ من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. يستدعيه Quickpay بعد كل عملية دفع (التفويض والتحصيل والاسترداد والإلغاء). ويُرسل تلقائيًا مع كل دفعة وتحصيل واسترداد، لذلك لا يلزم ضبط أي شيء في Quickpay.

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

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

لا تُعرض المفاتيح المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف قيمة محفوظة، ضع علامة على Clear the saved value on save أسفل الحقل، ثم انقر فوق Save.

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

Test payments: يقبل المدفوعات التي تتم ببطاقات اختبار Quickpay. لا توجد بيئة sandbox منفصلة في Quickpay: طالما أن حساب Quickpay في وضع الاختبار، تُجرى المدفوعات ببطاقات اختبار وتُعلَّم كمدفوعات تجريبية. فعّله فقط أثناء الاختبار. وعند إيقافه، لا تُعلّم أي دفعة تجريبية الطلب كمدفوع أبدًا. وعند تفعيله يرى العملاء Test mode: Quickpay test cards are accepted. في خطوة Confirm Order. الافتراضي: off.

الدفع

Capture: متى يُخصم المال من البطاقة.

Order status after payment: الحالة التي يحصل عليها الطلب المدفوع بعد أن يؤكد Quickpay الدفعة المحصّلة.

حالات الطلب

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد الرد الموقّع من Quickpay. يسرد كل حقل أدناه حالات طلبات OpenCart لديك.

"Payment accepted" status: تم تأكيد الدفعة المحصّلة، والمبلغ والعملة متطابقان. الافتراضي: Processing.

"Delivered (completed)" status: يُستخدم بدلًا من ذلك عندما تكون Order status after payment هي Delivered (completed). الافتراضي: Complete.

"Quickpay payment on hold" status: الدفعة مُفوَّضة فقط وتنتظر التحصيل، أو أن المبلغ أو العملة غير متطابقين، أو أن التحصيل فشل. الافتراضي: Pending، لأن OpenCart ليس لديه حالة On hold؛ وتشرح ملاحظة على الطلب السبب. ويمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Cancelled status: تُضبط عند إلغاء دفعة طلب معلّق في Quickpay. وعندما تضبط طلبًا من هذه الإضافة على هذه الحالة، يُحذف رابط دفعه غير المدفوع في Quickpay (انظر الطلبات والاسترداد). الافتراضي: Canceled.

Refunded status: تُضبط بعد استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: Refunded.

خيارات متقدمة

Debug log: يكتب في الملف qpg_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُنقل إلى qpg_debug.old.log.php. ويجري تسجيل الأخطاء والتحذيرات، مثل الردود المرفوضة وأخطاء API الخاصة بـ Quickpay، دائمًا. فعّل هذا الخيار لتسجيل تفاصيل كل طلب ورد أيضًا. ولا تُسجَّل مفاتيح API وبيانات البطاقات وبيانات العملاء أبدًا. الافتراضي: off.

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

Delete data: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. وتُحفظ بيانات الطلبات (مدفوعات Quickpay والاستردادات والملاحظات) دائمًا. الافتراضي: off.

الاستيراد / التصدير

Export: يحفظ Download JSON الإعدادات في ملف JSON. ولا تُصدَّر مفتاح API والمفتاح الخاص.

Import: الصق ملف JSON المُصدَّر سابقًا وانقر فوق Import لاستعادة الإعدادات. تبقى المفاتيح المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Quickpay). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the Quickpay payment window to complete the payment. وينشئ OpenCart الطلب في هذه الخطوة، ما زال دون حالة. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة دفعة Quickpay بعملة الطلب ورابط دفع بإجمالي الطلب، وترسل العميل إلى نافذة الدفع الخاصة بـ Quickpay. يدفع العميل هناك بإحدى الطرق المفعّلة في نافذة الدفع لديك في Quickpay. ويُمرَّر البريد الإلكتروني للعميل إلى Quickpay. وتُفتح نافذة الدفع بلغة العميل عندما يقدمها Quickpay (الدنماركية والألمانية والإنجليزية والإسبانية والفنلندية والفرنسية والإيطالية والهولندية والنرويجية والبولندية والسويدية)، وإلا فبالإنجليزية. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في نافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع.

بعد الدفع يعود العميل إلى متجرك. ولا تُعلّم العودة نفسها أي شيء كمدفوع. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Quickpay: يضبط الرد الموقّع حالة الطلب عندما يتطابق المبلغ المحصّل والعملة مع الطلب. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح طلب OpenCart. ومع Authorize only، يحصل الطلب بدلًا من ذلك على "Quickpay payment on hold" status، وتحصّل الدفعة لاحقًا. وإذا لم يصل الرد بعد عندما يعود العميل، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by Quickpay. You will receive an e-mail as soon as the order is confirmed. مع الزرين Check again وBack to checkout. وعندما ينقل رد Quickpay لاحقًا طلبًا من "Quickpay payment on hold" status إلى حالة الدفع أو إلى Cancelled status، يُخطَر العميل بالبريد الإلكتروني.

إذا ألغى العميل في نافذة الدفع، يُحذف رابط الدفع في Quickpay ويعود العميل إلى صفحة الدفع مع الرسالة The payment was cancelled. You can try again or choose another payment method. وإذا رُفضت البطاقة، فالرسالة هي The payment was not completed. You can try again or choose another payment method. وتُحتفظ بالسلة. وتحصل المحاولة الجديدة للطلب نفسه على رابط جديد للدفعة نفسها في Quickpay. وينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order؛ وتُحذف روابط دفع الطلبات السابقة من السلة نفسها عندئذٍ، حتى لا يمكن دفع رابط قديم بالتوازي أبدًا. وطالما أن دفعة من السلة مُفوَّضة وتنتظر تحصيلها، لا تُبدأ دفعة ثانية؛ ويرى العميل صفحة Payment confirmation.

في OpenCart 4 تظهر رسائل الإلغاء والرفض فوق صفحة الدفع. ويحتفظ OpenCart 4 بطلب واحد لصفحة الدفع ويحدّثه في كل مرة تُعرض فيها خطوة Confirm Order، لذلك بعد الإلغاء أو الرفض تُدفع الطلب نفسه برابط جديد للدفعة نفسها في Quickpay. وإذا أُغلق ذلك الطلب دون دفع في الأثناء، يعود العميل إلى صفحة الدفع مع Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، ويدفع Confirm Order التالي طلبًا جديدًا. وإذا كان لطلب صفحة الدفع حالة بالفعل لكن السلة تغيّرت منذ ذلك، بما في ذلك كمية جديدة، يعود العميل إلى صفحة الدفع وتُدفع السلة الجديدة بطلب جديد.

إذا تعذّر بدء الدفع، يبقى العميل في خطوة Confirm Order مع الرسالة 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.

يعمل الرد وعودة العميل أيضًا أثناء وضع الصيانة للمتجر: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، ويضيف الإضافة على OpenCart 4 إجراء بدء تشغيل (startup action) لها.

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

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى Quickpay ولم يدفع، أو رُفضت البطاقة، أو أن الدفعة مُفوَّضة وتنتظر التحصيل التلقائي. وفي Sales > Orders لا تظهر مثل هذه الطلبات إلا مع الفلتر Order Status مضبوطًا على Missing Orders.

"Payment accepted" أو "Delivered (completed)" status: أكّد Quickpay الدفعة المحصّلة بالمبلغ والعملة الصحيحين. تتبع الحالة Order status after payment. وتعرض ملاحظة معرّف دفعة Quickpay (مع وسم TEST للدفعات التجريبية).

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

Cancelled status: أُلغيت دفعة طلب معلّق في مدير Quickpay.

Refunded status: تم استرداد الدفعة بالكامل من خلال الإضافة.

لا تغيّر الدفعة التي تصل لطلب مدفوع أو ملغى أو مسترد أيّ شيء في الطلب. وتطلب ملاحظة منك التحقق من الدفعة في مدير Quickpay، على سبيل المثال لاسترداد دفعة مكررة. وإذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل، يبقى الطلب الجديد بلا حالة، ويتلقى الطلب المدفوع الملاحظة.

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

الملاحظات هي إدخالات في History الطلب لا يراها العميل.

تبويب VibeFox Quickpay Gateway

في Sales > Orders افتح طلبًا دُفع عبر Quickpay. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Quickpay Gateway معرّف الدفع Payment ID مع الوسم Test payment للدفعات التجريبية، وStatus الدفع، وAmount / refunded، وقائمة جميع دفعات Quickpay الخاصة بالطلب (عند وجود أكثر من واحدة)، وزر التحصيل، ونموذج الاسترداد، وسجل الاستردادات، وQuickpay notes الخاصة بالطلب. ويُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة. ويحتاج التحصيل والاسترداد إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups).

التحصيل

مع Authorize only، انقر فوق Capture Quickpay payment في التبويب، وأكّد Capture the order total through Quickpay? يُحصَّل إجمالي الطلب؛ والتحصيل الجزئي غير متاح. وإذا أكّد Quickpay فورًا، يُنقل الطلب إلى حالة الدفع المحددة في Order status after payment، دون إخطار العميل ودون تغيير المخزون، شأنه شأن تغيير الحالة يدويًا. وإلا تشير ملاحظة إلى أن التحصيل قد طُلب، ويُعلَّم الطلب كمدفوع عندما يؤكد رد Quickpay ذلك. ويُعرض التحصيل المرفوض في التبويب ويُدوَّن في ملاحظات الطلب.

الاسترداد

في التبويب أدخل Amount (تُملأ القيمة التي لم تُسترد بعد تلقائيًا)، واختياريًا Reason (optional)، ثم انقر فوق Refund via Quickpay. أكّد السؤال Refund this amount through Quickpay? This cannot be undone. والاسترداد الكامل والجزئي مدعومان للدفعات المحصّلة. ويجري الاسترداد بالمبلغ والعملة اللذين حصّلهما Quickpay، لا بإجمالي الطلب. ويعالج Quickpay الاستردادات بشكل غير متزامن: يعرض سجل الاستردادات requested، ويضبطها الرد على confirmed أو failed ويضيف النتيجة إلى الملاحظات. ولا يُحتسب الاسترداد الفاشل كمُسترد. وإذا رفض Quickpay الاسترداد فورًا، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويضبط الاسترداد الكامل الطلب على Refunded status دون إخطار العميل ودون إعادة المنتجات إلى المخزون؛ ولا يغيّر الاسترداد الجزئي الحالة. ولا يمكن استرداد دفعة مُفوَّضة لم تُحصَّل أبدًا؛ ألغِها في مدير Quickpay.

لا تُعيد الإرجاعات في Sales > Returns المال عبر Quickpay.

الاستردادات التي تُجرى مباشرة في مدير Quickpay تُضاف إلى الملاحظات فقط. ولا تتغير حالة الطلب تلقائيًا. حدّثها يدويًا إذا لزم الأمر.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Quickpay Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox Quickpay Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر فوق Activate. بعد ذلك تعرض الكتلة المفتاح مموّهًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-quickpay والرابط Manage licenses and domains in your account، الذي يفتح حسابك على vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify على الإضافة. وتتبع نصوص الكتلة لغة لوحة الإدارة (تتضمن الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. وبعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر فوق Check now. وإذا تعذّر الوصول إلى خادم التراخيص، تستمر الإضافة في العمل بآخر حالة معروفة.

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

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

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

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

لا يظهر Quickpay في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن API key وPrivate key محفوظان معًا. وبدون المفتاحين تُخفى طريقة الدفع، وتعرض صفحة الإعدادات تحذيرًا. وتحقّق أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

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

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

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

يعرض السجل Callback: no order found for payment …: الرد يخص دفعة Quickpay لم ينشئها هذا المتجر، مثل دفعة تمت خارج OpenCart.

يُظهر السجل أن السلة مقفلة بطلب آخر: كان رد آخر من السلة نفسها يُطبَّق في تلك اللحظة. يتلقى الرد خطأ، لذلك يعيد Quickpay إرساله.

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

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

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

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

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

للمطوّرين: قبل إنشاء رابط الدفع، تُطلق الإضافة حدث OpenCart المسمى qpg_quickpay_link_data مع معاملات الرابط والطلب.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر فوق Uninstall (الزر الأحمر −) بجانب VibeFox Quickpay Gateway. يُزال دائمًا مفتاح ترخيص هذه الإضافة وحالة الترخيص. ويزيل OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal والحالات في قسم Order statuses، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. ويُحذف أيضًا حدث OpenCart الخاص بالإضافة (في OpenCart 4 تُحذف أحداثه وإجراء بدء التشغيل الذي يسمح بمرور الرد وعودة العميل في وضع الصيانة). وإذا كان Delete data مفعّلًا، تُحذف إعدادات البوابة الأخرى (العنوان والوصف والمفاتيح والدفعات التجريبية والتحصيل والتسجيل) والسجل. وإذا كان معطّلًا، تُحفظ من أجل إعادة التثبيت لاحقًا. وتُحفظ دائمًا مدفوعات Quickpay واستردادها، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Quickpay Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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