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

المتطلبات

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

PHP: 8.0 أو أحدث.

حساب finby (TrustPay): يلزم وجود مشروع في finby Merchant Portal مع Project ID وSecret key الخاصين به. وللمدفوعات التجريبية يلزم مشروع اختبار منفصل (playground) له Project ID وSecret key خاصان به. لا تُطلب مفاتيح أخرى: يُستخدم Secret key للحصول على وصول واجهة API وللتحقق من توقيع إشعارات الدفع معًا.

عنوان URL للإشعارات متاح: يجب أن تتمكن finby من الوصول إلى متجرك عبر الإنترنت. فالجدار الناري أو تسجيل الدخول للصيانة أو مصادقة HTTP أمام المتجر تمنع إشعارات الدفع.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل Project ID وSecret key لمشروع الاختبار الخاص بك، وكذلك لمشروع الإنتاج عند تنفيذ المدفوعات الفعلية (راجع الإعدادات). يُرسل عنوان URL للإشعارات مع كل دفعة، لذا لا حاجة إلى أي إعداد في Merchant Portal.

5. فعّل Enable / Disable وانقر على Save. نفّذ دفعة تجريبية مع تفعيل Test mode، ثم أوقف Test mode لاستقبال المدفوعات الفعلية.

OpenCart 4

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

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

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

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

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

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox TrustPay Gateway > Edit. تُعرض الأقسام في الجهة اليسرى، ويحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات، تحذّرك الصفحة عندما تكون طريقة الدفع مفعّلة لكن Project ID أو Secret key للوضع الحالي فارغ، وعندما لا تكون العملة الافتراضية للمتجر مدعومة. وفي الحالتين تُخفى طريقة الدفع عند الدفع. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب ألّا يكون Title فارغًا أو أطول من 128 حرفًا، ويجب أن يكون Sort order عددًا صحيحًا (القيم السالبة مسموح بها)، ويجب أن يكون Minimum total رقمًا يساوي 0 أو أكبر، ويجب أن تكون المنطقة الجغرافية وحالات الطلب المختارة موجودة. وإلا فلن يُحفظ أي شيء وستعرض الصفحة الرسالة. يجب أن يحتوي Project ID على أرقام فقط: فإذا حفظت قيمة أخرى، تعرض الصفحة must contain digits only — the previous value was kept. وتُحفظ الحقول الأخرى.

TrustPay / finby

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

Title: اسم طريقة الدفع الذي يراه العميل عند الدفع، وهو أيضًا الاسم المحفوظ في الطلب. الافتراضي: Card payment (TrustPay). حقل مطلوب، بحد أقصى 128 حرفًا.

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

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

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

Minimum total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب حتى تُعرض طريقة الدفع. اتركه فارغًا إذا لم يكن هناك حد أدنى.

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

انسخ Project ID وSecret key لمشروعك من finby (TrustPay) Merchant Portal. يحتوي القسم على رابط إلى Merchant Portal. تستخدم المدفوعات التجريبية مشروع اختبار منفصلًا (playground) له Project ID وSecret key خاصان به. لا يُخصم أي مبلغ حقيقي هناك.

Test mode: يستخدم مشروع الاختبار (دون مدفوعات حقيقية). تستخدم المدفوعات والمبالغ المستردة الجديدة بيانات اعتماد الاختبار. تُرسل المبالغ المستردة لأي طلب دائمًا إلى المشروع الذي دُفع من خلاله الطلب. الافتراضي: مفعّل. وطالما هو مفعّل يرى العملاء في خطوة Confirm Order الرسالة Test mode: no real payment will be taken.

Live Project ID: معرّف Project ID الرقمي لمشروع الإنتاج الخاص بك.

Live Secret key: مفتاح Secret key لمشروع الإنتاج. يُستخدم للحصول على رموز الوصول إلى API وللتحقق من إشعارات الدفع.

Test Project ID: معرّف Project ID الرقمي لمشروع الاختبار (playground) الخاص بك.

Test Secret key: مفتاح Secret key لمشروع الاختبار.

تُحفظ مفاتيح Secret key كما أُدخلت، وتُزال المسافات في البداية والنهاية فقط. لا تُعرض مفاتيح Secret key المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عند الرغبة في تغييرها. كما يؤدي حفظ الإعدادات إلى حذف رموز وصول API المخزنة مؤقتًا، فتُستخدم بيانات الاعتماد الجديدة فورًا.

Clear saved secrets: ضع علامة على مفتاح Secret key ثم انقر على Save لحذفه. يحتفظ الحقل الفارغ بالقيمة المحفوظة.

حالات الطلب

ينشئ OpenCart الطلب في خطوة Confirm Order بلا حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تؤكده finby بإشعار موقّع. يسرد كل حقل أدناه حالات طلبات OpenCart لديك. لا يملك OpenCart حالات خاصة به للدفعة المعلّقة أو المحجوزة من TrustPay، لذلك تستخدم الحالتان "قيد الانتظار" افتراضيًا؛ وتميّز ملاحظات الطلب وتبويب الطلب بينهما. يمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Order status after payment: حالة الطلب المدفوع. الافتراضي: قيد المعالجة. اختر مكتمل إذا كان يجب إكمال الطلبات المدفوعة فورًا. تُعيَّن الحالة في خطوة واحدة، لذا يتلقى العميل بريدًا إلكترونيًا واحدًا.

Awaiting TrustPay payment: أبلغت finby أن آخر دفعة قيد الانتظار؛ ينتقل الطلب إلى حالة الدفع عندما تؤكدها finby. الافتراضي: قيد الانتظار.

TrustPay payment on hold: الدفعة اعتُمدت فقط ولم تُحصَّل (يجب تحصيلها في Merchant Portal)، أو أن المبلغ المدفوع أو العملة يختلفان عن طلب الدفع أو إجمالي الطلب. الافتراضي: قيد الانتظار.

Payment error: رفضت finby آخر دفعة لطلب كان ينتظر. ومع ذلك فإن الدفعة المؤكدة لاحقًا تنقل الطلب إلى حالة الدفع. الافتراضي: فشل.

Cancelled order status: لا تعيّنها الإضافة. لا يُعاد فتح الطلب الذي في هذه الحالة بدفعة متأخرة؛ وتُضاف ملاحظة. الافتراضي: ملغى.

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

إشعارات الدفع

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

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

Advanced

Debug logging: يضيف طلبات API والإشعارات إلى الملف trustpay_p_debug.log.php في مجلد سجلات OpenCart (storage/logs، وفي OpenCart 4 system/storage/logs). لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائمًا، حتى عندما يكون هذا الخيار معطّلًا. ولا يتضمن السجل مفاتيح أو رموزًا أو بيانات بطاقات أو تفاصيل عملاء. الافتراضي: معطّل.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعداداتها وسجلها. تُحفظ بيانات الطلبات: الطلبات وسجلات الدفع في TrustPay والمبالغ المستردة. الافتراضي: معطّل.

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Card payment (TrustPay)). لا تُعرض هذه الطريقة إلا إذا كانت عملة العميل إحدى العملات المدعومة: EUR وCZK وHUF وGBP وPLN وNOK وSEK وDKK وBGN وRON وCHF وUSD. وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the secure TrustPay / finby payment page to pay by card. وينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

عندما ينقر العميل على Confirm Order، تنشئ الإضافة لدى finby طلب دفع بالبطاقة لإجمالي الطلب بعملة الطلب. تُرسل المبالغ بعملة HUF بدون كسور عشرية. ويُرسل اسم العميل وعنوانه وبريده الإلكتروني من أجل 3-D Secure، ويُرسل رقم طلب OpenCart بوصفه مرجعًا. تحتاج المدفوعات بالبطاقة إلى عنوان: إذا كان الشارع أو المدينة أو الرمز البريدي أو البلد مفقودًا، يرى العميل Please enter your billing address (street, city, postcode and country) — it is required for card payments. وفي OpenCart 4، الذي لا يطلب عنوان دفع افتراضيًا، تُؤخذ الحقول الناقصة من عنوان الشحن. ويُنقل العميل إلى صفحة الدفع لدى finby ويدفع بالبطاقة هناك. تُفتح الصفحة بلغة واجهة المتجر عندما تدعمها finby، وإلا فبالإنجليزية.

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده finby بالإشعار الموقّع. ولا تغيّر العودة نفسها حالة الدفع أبدًا. فإذا وصل الإشعار بالفعل، يرى العميل صفحة نجاح الطلب في OpenCart. وإذا لم يصل، تعرض صفحة Payment confirmation الرسالة TrustPay / finby is confirming your card payment. Your order is confirmed as soon as the payment is confirmed, and you will receive an e-mail — there is no need to pay again. وتحتوي الصفحة على زر Check again وزر Back to checkout. وبينما يكون الطلب في حالة الانتظار أو المحجوز، تعرض صفحة النجاح الرسالة Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. وعندما يُدفع طلب في حالة الانتظار أو المحجوز لاحقًا، أو ترفض finby دفعته، يتلقى العميل بريدًا إلكترونيًا بشأن الحالة الجديدة للطلب. وإذا رفضت finby الدفعة أو أُلغي الطلب غير المدفوع، تعرض صفحة النجاح الرسالة Your card payment was not completed. Please contact us about this order. وفي OpenCart 4، عندما يعود العميل من صفحة الدفع لدى finby، تُعيد صفحة وسيطة قصيرة فتح عنوان العودة في متجرك، فيُحتفظ بالسلة وتسجيل دخول العميل.

إذا ألغى العميل في صفحة الدفع، يعود إلى الدفع مع الرسالة The card payment was cancelled. You can try again or choose another payment method. وإذا أعادت صفحة الدفع خطأ، أو رفضت finby الدفعة من قبل، تكون الرسالة The card payment was not completed. Please try again or choose another payment method. تبقى السلة محفوظة ويمكن للعميل الدفع مجددًا. وفي OpenCart 4 تُعرض هذه الرسائل أعلى صفحة الدفع.

ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، بينما ينشئ OpenCart 4 الطلب ثم يحدّثه أثناء الدفع. تُدفع السلة الواحدة بطلب واحد فقط: فبمجرد أن يحصل أحد طلبات السلة على حالة TrustPay، تؤدي إعادة تأكيد السلة إلى صفحة النجاح بدلًا من دفعة ثانية. وأي تغيير في السلة، بما في ذلك تغيير الكمية، يُعامَل كسلة جديدة تحتاج إلى دفعة خاصة بها.

يحتفظ OpenCart 4 بالطلب في خطوة الدفع حتى تُعرض صفحة النجاح. وبعد دفعة أُلغيت أو فشلت، يدفع العميل الطلب نفسه بطلب دفع جديد من finby. فإذا أُغلق ذلك الطلب في غضون ذلك، يعود العميل إلى الدفع، وتدفع خطوة Confirm Order التالية طلبًا جديدًا: بعد دفعة مرفوضة أو طلب غير مدفوع أُلغي، تظهر الرسالة The card payment was not completed. Please try again or choose another payment method.؛ وفي غير ذلك (مثلًا إذا ألغى المتجر الطلب أو استرده) تظهر الرسالة Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.

إذا تعذّر على finby بدء الدفع، يبقى العميل في خطوة Confirm Order ويرى فوق الزر الرسالة We could not start the card payment. Please try again in a moment or choose another payment method. ويُكتب السبب التقني في السجل.

تقبل الإضافة المدفوعات بالبطاقات فقط، بوصفها عملية شراء من خطوة واحدة في صفحة finby. ولا تتضمن تحويلات بنكية أو طرق دفع أخرى من finby، ولا أزرار Apple Pay أو Google Pay على موقعك، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا تفويض وتحصيل منفصلين، ولا استطلاع دوري للحالة.

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

حالات الطلب

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

حالة الطلب بعد الدفع (الافتراضي قيد المعالجة): أكدت finby الدفع، ويتطابق المبلغ والعملة مع طلب الدفع وإجمالي الطلب. تعرض ملاحظة المبلغ وطلب الدفع والمشروع (اختبار أو إنتاج).

دفعة TrustPay قيد الانتظار (الافتراضي قيد الانتظار): أبلغت finby أن آخر دفعة قيد الانتظار. ينتقل الطلب إلى حالة الدفع عندما تؤكد finby الدفعة.

دفعة TrustPay محجوزة (الافتراضي قيد الانتظار): تُعيَّن في حالتين. اعتُمدت الدفعة فقط ولم تُحصَّل: حصّلها أو ألغها في finby Merchant Portal، ثم حدّث الطلب. أو أن المبلغ المدفوع أو العملة يختلفان عن طلب الدفع أو إجمالي الطلب: تحقق من الدفعة قبل الشحن. توضح الملاحظة الحالة. وقد استُلم المال، لذلك يتوفر الاسترداد.

خطأ في الدفع (الافتراضي فشل): رفضت finby آخر دفعة لطلب كان ينتظر. تعرض الملاحظة السبب عندما ترسله finby. ومع ذلك فإن الدفعة المؤكدة لاحقًا تنقل الطلب إلى حالة الدفع.

حالة الطلب المسترد (الافتراضي مسترد): استُرد الدفع بالكامل عبر الإضافة.

لا يُعاد فتح الطلبات الملغاة أو المستردة بدفعة متأخرة أبدًا. تطلب ملاحظة منك استعادة الطلب أو استرداد الدفع في Merchant Portal. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، أو لطلب آخر في سلة تحتوي على طلب مدفوع، فلا يُغيَّر الطلب وتطلب ملاحظة منك استرداد الدفعة المكررة في Merchant Portal. وتُضاف عمليات الاسترداد القسري (chargebacks) والنزاعات التي تبلغ عنها finby كملاحظات.

الملاحظات إدخالات في History الطلب لا يراها العميل. وتُكتب بلغة المتجر الافتراضية.

VibeFox TrustPay Gateway tab

في Sales > Orders افتح طلبًا دُفع عبر TrustPay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox TrustPay Gateway الحقول Payment request ID وPayment ID وProject مع شارة Test project للمدفوعات التجريبية وStatus والمبالغ Requested / paid وPaid / refunded ونموذج الاسترداد وسجل الاسترداد وPayment requests of this order وTrustPay notes. يظهر التبويب للمستخدمين الذين لديهم حق الوصول إلى الإضافة.

الاسترداد

في تبويب VibeFox TrustPay Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via TrustPay. أكّد السؤال Refund this amount through TrustPay? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). تتم المبالغ المستردة بالمبلغ والعملة اللذين أبلغت عنهما finby للدفعة، لذلك بعد وجود فرق في المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب. ويجب أن تكون المبالغ المستردة بعملة HUF أعدادًا صحيحة.

يذهب الاسترداد إلى المشروع الذي دُفع من خلاله الطلب (اختبار أو إنتاج)، حتى لو غيّرت الوضع منذ ذلك الحين. يجب أن يكون Project ID وSecret key لذلك المشروع مضبوطين، ويجب ألّا يكون Project ID قد تغيّر. لا يُسجَّل الاسترداد إلا إذا قبلته finby. وإلا يعرض التبويب TrustPay refused the refund: مع السبب، ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات. ويضع الاسترداد الكامل الطلب على Refunded order status دون إخطار العميل ودون إعادة المنتجات إلى المخزون، كما في تغيير الحالة يدويًا. أما الاسترداد الجزئي فلا يغيّر الحالة.

لا ترجع مرتجعات المنتجات في Sales > Returns أي أموال عبر finby. ولا تُسجَّل المبالغ المستردة التي أُجريت في finby Merchant Portal كعمليات استرداد. وإذا أرسلت finby إشعارًا بشأنها، فيُضاف كملاحظة ولا تتغير حالة الطلب.

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

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

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

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

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

لا تظهر Card payment (TrustPay) عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يملك Project ID وSecret key الخاصين به: Test Project ID وTest Secret key في وضع الاختبار، وLive Project ID وLive Secret key في وضع الإنتاج. يجب أن تكون عملة العميل إحدى العملات المدعومة. وتعرض صفحة الإعدادات تحذيرًا عندما تكون بيانات الاعتماد مفقودة أو عندما لا تكون العملة الافتراضية مدعومة. تحقق أيضًا من أن عنوان الدفع ضمن Geo zone المختارة، وأن الطلب يبلغ Minimum total.

تمت عملية الدفع لكن الطلب بقي بلا حالة: لم يصل الإشعار إلى متجرك. تحقق من أن عنوان URL المعروض تحت Notification URL متاح من الإنترنت (بدون جدار ناري أو تسجيل دخول للصيانة أو مصادقة HTTP). تعيد finby إرسال الإشعار، ويحصل الطلب على حالته عند وصوله. تُكتب الأخطاء دائمًا في السجل؛ راجع حقل Log في صفحة الإضافة.

يعرض السجل Notification rejected: invalid signature or unknown project: جاء الإشعار من مشروع لا يوجد Project ID الخاص به في الإعدادات، أو أن Secret key لذلك المشروع غير صحيح. يردّ المتجر بـ Invalid signature ولا يتغير شيء. تحقق من Project ID وSecret key للوضع الذي تمت فيه الدفعة.

يعرض السجل Notification ignored: ينتمي الإشعار إلى طلب دفع لم ينشئه هذا المتجر لذلك الطلب، أو إلى مشروع أو وضع مختلف عن الذي بدأت به الدفعة. لا يتغير شيء.

يتلقى الإشعار الرد Busy, retry later أو Temporary error: كانت السلة تُحدَّث بإشعار آخر في اللحظة نفسها، أو تعذّر تعيين حالة الطلب. ستعيد finby المحاولة. يعرض السجل السبب.

يرى العميل الرسالة We could not start the card payment: افتح السجل. يؤدي Project ID أو Secret key خاطئ إلى رسالة تفيد بأن finby رفضت بيانات اعتماد المشروع. تحقق من إدخال بيانات الاختبار في حقول الاختبار، وبيانات الإنتاج في حقول الإنتاج.

Card payment is temporarily unavailable: يرى العميل هذه الرسالة عندما لا يحتوي الوضع الحالي على Project ID أو Secret key. أدخلهما واحفظ.

الطلب في حالة المحجوز: اقرأ الملاحظات في تبويب VibeFox TrustPay Gateway (راجع حالات الطلب). تحقق من الدفعة في Merchant Portal قبل الشحن، ثم أكمل الطلب أو استرد الدفعة.

يفشل الاسترداد برسالة تتعلق بالمشروع: دُفع الطلب عبر مشروع الاختبار أو الإنتاج، ولم يُضبط Project ID أو Secret key لذلك الوضع، أو أن Project ID آخر مخزَّن هناك الآن. أدخل بيانات اعتماد ذلك المشروع، أو استرد الدفعة في finby Merchant Portal.

Invalid refund amount: at most … can be refunded: المبلغ أكبر من المبلغ المدفوع مطروحًا منه الاستردادات التي تمت بالفعل عبر الإضافة.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox TrustPay Gateway. تُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. ويحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable / Disable وSort order وGeo zone وMinimum total وحالات الطلب، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما تُحذف أحداث OpenCart الخاصة بالإضافة ورموز وصول API المخزنة مؤقتًا (وفي OpenCart 4 أيضًا أحداثها وإجراء بدء التشغيل الذي يسمح بمرور الإشعار وعودة العميل في وضع الصيانة). وإذا كان Delete data on uninstall مفعّلًا، تُحذف الإعدادات الأخرى (العنوان، والوصف، ووضع الاختبار، وProject ID، وSecret key، وتسجيل الدخول) والسجل. وإذا كان معطّلًا، فتُحفظ لإعادة التثبيت لاحقًا. وتُحفظ سجلات الدفع في TrustPay والمبالغ المستردة دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا حتى بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

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

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