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

المتطلبات

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

PHP: 8.0 أو أحدث.

عملة المتجر: HUF أو EUR أو USD. لا تقبل SimplePay عملات أخرى، ولا تُعرض طريقة الدفع بينما اختار العميل عملة أخرى.

حسابات التاجر في SimplePay: تمنح SimplePay حساب تاجر منفصلًا لكل عملة، وحسابات منفصلة للإنتاج وsandbox. لكل حساب تحتاج إلى MERCHANT وSECRET KEY الخاصين به من لوحة إدارة التجار في SimplePay (admin.simplepay.hu للإنتاج، وsandbox.simplepay.hu لـ sandbox)، في account > Technical data. إذا كنت تبيع بـ HUF فقط، فحساب HUF يكفي. لا تحتاج إلى أي مفاتيح أخرى.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل MERCHANT وSECRET KEY لحسابات SimplePay الخاصة بك لكل عملة تبيع بها: حسابات sandbox للاختبارات، وحسابات الإنتاج للمدفوعات الحقيقية (راجع Configuration).

5. انسخ IPN URL المعروض في صفحة الإعدادات إلى كل حساب تاجر (الإنتاج وsandbox) في لوحة إدارة التجار في SimplePay.

6. فعّل Enable/Disable واضغط Save. اختبر دفعة مع تفعيل Sandbox mode، ثم عطّل Sandbox mode لقبول المدفوعات الحقيقية.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص وحسابات التجار وIPN URL كما في الخطوات من 3 إلى 6 الخاصة بـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين، ويختلف IPN URL فقط (راجع IPN URL).

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

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox SimplePay Gateway > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ الزر Save الموجود أسفل القائمة الصفحة كاملة. وفوق الإعدادات تحذّرك الصفحة عندما لا تكون العملة الافتراضية للمتجر مدعومة من SimplePay، أو عندما لا يكون لها حساب تاجر في الوضع الحالي. وفي الحالتين لا تُعرض طريقة الدفع للطلبات بتلك العملة. وبينما وضع sandbox مفعّل تعرض الصفحة Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

SimplePay (OTP)

Enable/Disable: Enable SimplePay Gateway يشغّل طريقة الدفع أو يوقفها. Default: off.

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. Default: SimplePay (Card Payment). حقل مطلوب.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. Default: Pay securely with your credit or debit card via SimplePay. يمكن للتجار المجريين وضع إعلان نقل البيانات الخاص بـ SimplePay هنا.

Sandbox mode: يستخدم sandbox الخاص بـ SimplePay لمدفوعات الاختبار مع حسابات sandbox. وهو يبدّل عنوان API وحسابات التجار معًا. لا يُخصم أي مبلغ حقيقي. Default: on. عطّله لقبول المدفوعات الحقيقية بحسابات الإنتاج. وطالما هو مفعّل يرى العملاء في خطوة Confirm Order الرسالة Sandbox mode: no real payment is taken. الطلبات التي بدأت في sandbox تُسترد دائمًا في sandbox.

Sort Order: موضع SimplePay بين طرق الدفع عند الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا (القيم السالبة مسموحة).

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

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض SimplePay. اتركه فارغًا لعرض SimplePay مهما كان الإجمالي.

حسابات التجار للإنتاج

الحسابات المستخدمة عندما يكون Sandbox mode معطّلًا. املأ حسابات العملات التي يبيع بها متجرك. توجد قيم MERCHANT وSECRET KEY في لوحة إدارة التجار في SimplePay (admin.simplepay.hu، حيث توجد روابط الأقسام)، في account > Technical data. لا يُستخدم الحساب إلا عندما يكون حقلاه مملوءين.

HUF account — Merchant ID: قيمة MERCHANT لحساب HUF الخاص بالإنتاج.

HUF account — Secret key: قيمة SECRET KEY لحساب HUF الخاص بالإنتاج.

EUR account — Merchant ID وEUR account — Secret key: القيمتان نفسهما لحساب EUR الخاص بالإنتاج.

USD account — Merchant ID وUSD account — Secret key: القيمتان نفسهما لحساب USD الخاص بالإنتاج.

حسابات التجار لـ sandbox

الحسابات المستخدمة عندما يكون Sandbox mode مفعّلًا. الحقول هي نفسها الموجودة في حسابات الإنتاج: HUF account — Merchant ID وHUF account — Secret key، والأزواج نفسها لـ EUR وUSD. خذ القيم من لوحة إدارة التجار في sandbox لدى SimplePay (sandbox.simplepay.hu)، في account > Technical data.

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

IPN URL

IPN هي الرسالة التي ترسلها SimplePay إلى متجرك عند تغيّر حالة الدفع. وهي الطريقة المعتادة لحصول الطلب على حالته. يعرض هذا القسم IPN URL الخاص بمتجرك. على OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_simplepay_gateway/ipn، وعلى OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_simplepay_gateway/payment/wcp_simplepay_gateway.ipn. ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك. اضبط هذا العنوان لكل حساب تاجر، الإنتاج وsandbox، في لوحة إدارة التجار في SimplePay. انسخ العنوان تمامًا كما تعرضه الإعدادات، لأن IPN الذي يُعاد توجيهه يضيع.

يجب أن تكون IPN موقّعة بـ SECRET KEY لحساب التاجر الذي تذكره، وفي الوضع (sandbox أو الإنتاج) الذي بدأ فيه الدفع. تُرفض رسائل IPN التي لا توقيع صالح لها. تؤكد الإضافة كل IPN صالح لـ SimplePay بالصيغة الموقّعة التي تطلبها SimplePay. تُستخدم حالات IPN التالية:

تُسجَّل حالات الرفض والإلغاء وانتهاء المهلة فقط لآخر محاولة دفع لسلة لم يُدفع فيها شيء بعد. أما الحالات الأخرى فلا تغيّر شيئًا. وبدون IPN لا يحصل الطلب على حالته إلا عندما يعود العميل إلى المتجر بعد دفع ناجح.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود، missing order). لا يحصل الطلب على حالة إلا بعد أن تؤكد SimplePay الدفع. تعرض حقول الحالات حالات طلبات OpenCart لديك.

Order Status After Payment: الحالة التي يحصل عليها الطلب المدفوع.

Paid Order Status: حالة الطلب المدفوع عندما تكون Order Status After Payment هي Processing. Default: Processing.

Complete Order Status: حالة الطلب المدفوع عندما تكون Order Status After Payment هي Completed. Default: Complete.

On Hold (Review) Status: تمّ الدفع بمبلغ أو عملة مختلفين عن الطلب (راجع Order statuses). Default: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Refunded Status: تُعيَّن بعد استرداد الدفع بالكامل من صفحة الطلب. Default: Refunded.

متقدم

Logging: يكتب استدعاءات API وIPN والعودات في simplepay_op_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُدوَّر. لا تُسجَّل المفاتيح وبيانات العملاء. تُسجَّل الأخطاء دائمًا، حتى عندما يكون هذا الخيار معطّلًا. Default: off.

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

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

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

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

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

الدفع

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

بعد دفع ناجح يعود العميل إلى متجرك. العودة وحدها لا تدفع الطلب أبدًا: تطلب الإضافة من SimplePay حالة المعاملة بطلب موقّع، لذلك يحصل الطلب على حالته حتى لو تأخرت IPN. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد SimplePay ذلك. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع Successful transaction. SimplePay transaction ID: والمعرّف. إذا لم تؤكد SimplePay الدفع بعد، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by SimplePay. SimplePay transaction ID: مع المعرّف، وYour order will be confirmed as soon as SimplePay confirms the payment — please do not pay again.، والزرين Check again وBack to checkout؛ وتحدد IPN حالة الطلب فور وصولها.

إذا فشل الدفع أو أُلغي أو انتهت مهلته، يعود العميل إلى الدفع مع رسالة SimplePay ومعرّف المعاملة، مثلًا Cancelled payment. You cancelled the payment أو Timeout. The time allowed to complete the payment has expired. يطلب الدفع الفاشل من العميل التحقق من البيانات التي أدخلها والتواصل مع البنك المُصدِر للبطاقة. يبقى الطلب بلا حالة، وتبقى السلة محفوظة، ويستطيع العميل المحاولة مرة أخرى. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order. أما OpenCart 4 فيحتفظ بطلب واحد للدفع ويحدّثه، فتدفع المحاولة التالية الطلب نفسه. وتحصل كل محاولة على مرجع SimplePay خاص بها: OC ورقم الطلب ورقم المحاولة، مثلًا OC123-1 ثم OC123-2. إذا كان طلب آخر من السلة نفسها مدفوعًا أو قيد المراجعة بالفعل، يذهب العميل مباشرة إلى صفحة النجاح بدلًا من الدفع مرة أخرى.

إذا تعذّر على SimplePay بدء الدفع، يبقى العميل في خطوة Confirm Order مع الرسالة The SimplePay payment could not be started. Please try again or choose another payment method. إذا لم يكن لعملة الطلب حساب تاجر، فالرسالة هي SimplePay is not available for the currency of this order. Please choose another payment method. يُكتب السبب التقني في السجل. ويعرض العائد الذي لا يمكن مطابقته بأي محاولة دفع الرسالة We could not match this payment to an order. If you were charged, please contact us.

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

تعمل IPN وعودة العميل أيضًا عندما يكون المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وفي OpenCart 4 تضيف الإضافة إجراء بدء التشغيل لهذه الطلبات.

تقبل الإضافة المدفوعات الفردية بالبطاقة فقط، والتي تُحصَّل في صفحة SimplePay. ليس فيها بطاقات محفوظة ولا دفع بنقرة واحدة، ولا اشتراكات ولا مدفوعات متكررة، ولا تفويض وتحصيل منفصلان.

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

حالات الطلب

No status (missing order): أُرسل العميل إلى SimplePay ولم يدفع، أو فشل الدفع، أو أُلغي، أو انتهت مهلته، أو لم تؤكد SimplePay الدفع بعد. في Sales > Orders لا تظهر هذه الطلبات إلا مع فلتر Order Status المضبوط على Missing Orders.

Paid Order Status or Complete Order Status: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تعرض ملاحظة معرّف معاملة SimplePay، وما إذا كانت IPN أو استعلام الحالة هو من أكد الدفع.

On Hold (Review) Status (default Pending): تغيّر إجمالي الطلب أو عملته بعد بدء الدفع، لذلك يختلف المبلغ المدفوع عن الطلب. تعرض الملاحظة المبلغين. تحقق من الطلب وأتمّه أو استرد الدفع في لوحة إدارة التجار في SimplePay. وإذا دُفعت محاولة أخرى من السلة نفسها بعد ذلك بالمبلغ الصحيح، يحصل طلب ذلك الدفع على حالة المدفوع.

Refunded Status (default Refunded): تم استرداد الدفع بالكامل عبر الإضافة.

لا يُعاد فتح الطلب المدفوع أو المسترد أو المكتمل بواسطة IPN متأخرة أبدًا. إذا نجح دفع ثانٍ لطلب مدفوع بالفعل، أو لطلب آخر من السلة نفسها، فلن يتغير الطلب المدفوع. تطلب منك الملاحظة التحقق من ذلك في لوحة إدارة SimplePay واسترداده إذا كان مكررًا.

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

VibeFox SimplePay Gateway tab

في Sales > Orders افتح طلبًا دُفع عبر SimplePay. في أسفل صفحة الطلب، بجانب History وAdditional، تعرض علامة التبويب VibeFox SimplePay Gateway الحقل Transaction ID مع الوسم Sandbox لمدفوعات sandbox، والحقل Order reference (orderRef)، وMerchant account والوضع، والحقل Status الخاص بـ SimplePay، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، والحقل Payment attempts of the cart (عندما تكون هناك أكثر من محاولة)، والملاحظات SimplePay notes الخاصة بالطلب. تظهر علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في علامة التبويب VibeFox SimplePay Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واختياريًا Reason (optional, order note only)، ثم اضغط Refund via SimplePay (OTP). أكّد السؤال Refund this amount via SimplePay? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). استردادات HUF يجب أن تكون مبالغ فورنت صحيحة. يُرسل الاسترداد للمعاملة في SimplePay التي دفعت الطلب، مع حساب التاجر والوضع (sandbox أو الإنتاج) لذلك الدفع، حتى لو بدّل المتجر الوضع إلى الآخر بعد ذلك؛ ويجب أن يبقى ذلك الحساب في الإعدادات. إذا لم تقبل SimplePay الاسترداد، تعرض علامة التبويب الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى السجل والملاحظات مع معاملة الاسترداد في SimplePay والسبب، إذا أدخلته. يضع الاسترداد الكامل الطلب على Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، كما هو الحال في تغيير الحالة يدويًا. لا يغيّر الاسترداد الجزئي الحالة. لا يمكن استرداد طلب قيد المراجعة بعد اختلاف في المبلغ من علامة التبويب: استرده في لوحة إدارة التجار في SimplePay.

لا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر SimplePay. لا تُزامَن الاستردادات التي تتم في لوحة إدارة التجار في SimplePay مع OpenCart. سجّلها يدويًا.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox SimplePay Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox SimplePay Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثلًا تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-simplepay والرابط 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.

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

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

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

لا تظهر SimplePay عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن عملة العميل هي HUF أو EUR أو USD، وأن لهذه العملة Merchant ID وSecret key في الوضع الحالي: حسابات sandbox طالما أن Sandbox mode مفعّل، وحسابات الإنتاج طالما أنه معطّل. تحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تم الدفع، لكن الطلب يبقى بلا حالة: لم تصل IPN إلى المتجر. في لوحة إدارة التجار في SimplePay، تحقق من IPN URL لحساب التاجر الذي تستخدمه (الإنتاج أو sandbox، وعملة الطلب). يجب أن يكون مطابقًا تمامًا للعنوان المعروض في الإعدادات، وأن يكون خادمك متاحًا من الإنترنت. يحصل الطلب على حالته أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

تجيب IPN بـ Invalid signature.: تشير IPN إلى حساب تاجر غير موجود في الإعدادات، أو أن Secret key الخاص به خاطئ، أو أنها موقّعة بحساب الوضع الآخر غير الذي تم فيه الدفع. أدخل MERCHANT وSECRET KEY تمامًا كما تعرضهما لوحة إدارة التجار في SimplePay. تعيد SimplePay إرسال IPN غير المؤكدة.

تجيب IPN بـ Order not found. أو Unknown transaction.: الـ IPN تخص دفعًا لم يبدأه هذا المتجر. لا يتغير شيء.

تجيب IPN بـ Busy, retry.: كانت السلة تُعالَج بطلب آخر في اللحظة نفسها، أو تعذّر تعيين حالة الطلب. تعيد SimplePay محاولة IPN. يُكتب السبب في السجل.

يرى العميل The SimplePay payment could not be started: راجع الحقل Log في صفحة الإضافة. المفتاح السري الخاطئ يعطي Invalid response signature from SimplePay. Check the secret key of the merchant account. تُسجَّل أخطاء SimplePay مع رموزها.

يرى العميل This payment method is not available.: لم تعد صفحة الدفع متوافقة مع الطلب، أو أن طريقة الدفع أُوقفت في هذه الأثناء. يعيد العميل تحميل صفحة الدفع.

بعد التبديل بين sandbox والإنتاج: تستخدم المدفوعات الجديدة حسابات الوضع الجديد. أما المدفوعات التي بدأت قبل ذلك فتحتفظ بحساب التاجر والوضع اللذين بدأت بهما: إذ تستخدم IPN الخاصة بها واستعلامات الحالة والاستردادات ذلك الحساب. احتفظ بحسابات الوضع القديم في الإعدادات طالما أن هناك مدفوعات مفتوحة أو قد تحتاج إلى استرداد.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في علامة التبويب VibeFox SimplePay Gateway. تغيّر إجمالي الطلب أو عملته بعد بدء الدفع. أتمّ الطلب أو استرد الدفع في لوحة إدارة التجار في SimplePay.

لا يوجد نموذج استرداد في علامة التبويب: تذكر علامة التبويب السبب: الطلب غير مدفوع بمعاملة SimplePay (مثلًا بعد اختلاف في المبلغ)، أو أنه مسترد بالكامل، أو أن مجموعة مستخدميك ليس لديها صلاحية تعديل الإضافة، أو أن حساب التاجر الخاص بالدفع غير موجود في الإعدادات.

يفشل الاسترداد: اقرأ الرسالة في علامة التبويب. تعني SimplePay refunds in HUF must be whole amounts. أن مبلغ HUF كان يحتوي على كسور. إذا كانت الرسالة تقول إن حساب التاجر لهذا الدفع غير مضبوط، فأعد إدخال الحساب (العملة والوضع) الذي تمّ به الدفع. وإذا استردت SimplePay مبلغًا مختلفًا، فالرسالة تطلب منك التحقق من الاسترداد في لوحة إدارة SimplePay.

للمطورين: قبل بدء الدفع تُطلق الإضافة حدث OpenCart باسم simplepay_op_payment_data مع بيانات الدفع والطلب. لا يمكن تغيير التاجر ومرجع الطلب والعملة والإجمالي وعنوان العودة هناك.

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

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

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

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