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

المتطلبات

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

PHP: 8.0 أو أحدث.

العملة: EUR. لا تقبل Paytrail إلا اليورو. وللطلب بأي عملة أخرى تُخفى طريقة الدفع في صفحة الدفع. تُرسل المبالغ بالسنت.

اتصال متجرك بالإنترنت: تؤكد Paytrail كل دفعة عبر استدعاء راجع (callback) من خادم إلى خادم، لذلك يجب أن يكون متجرك متاحًا من الإنترنت. وبدون استدعاءات الرجوع تُؤكَّد الطلبات أيضًا عند عودة العميل من Paytrail.

حساب Paytrail: تحتاج إلى معرّف التاجر (merchant ID) والمفتاح السري، وهما معروضان في Merchant Panel لدى Paytrail (تفاصيل الحساب أو التكامل). للاختبار لا تحتاج إلى حساب: يستخدم وضع الاختبار حساب Paytrail التجريبي العام. أما طرق الدفع نفسها فتُفعَّل في حسابك لدى Paytrail.

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

التثبيت

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

OpenCart 3

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

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

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

4. لتجربة الإضافة أولًا، فعّل Test mode. وللمدفوعات الحقيقية، أوقفه وأدخل Merchant ID وSecret key الخاصين بك. لا حاجة إلى ضبط أي عنوان callback في Paytrail.

5. فعّل Enable/Disable ثم انقر على Save.

OpenCart 4

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

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

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

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

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

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Paytrail Gateway > Edit. تُعرض الأقسام على اليسار، ويحفظ الزر Save الموجود أسفل القائمة الصفحة كاملة. وفوق الإعدادات تعرض الصفحة الرسالة وضع الاختبار مفعّل. تستخدم المدفوعات حساب Paytrail التجريبي العام — لا يُخصم أي مبلغ حقيقي. ما دام وضع الاختبار مفعّلًا. وفي الوضع الحقيقي تحذّرك إذا كان معرّف التاجر أو المفتاح السري مفقودًا، أو إذا كان معرّف التاجر هو حساب الاختبار العام 375917؛ وفي هذه الحالات لا تظهر Paytrail في صفحة الدفع. وتحذّرك أيضًا إذا لم تكن العملة الافتراضية للمتجر هي EUR: فعندئذٍ تظهر Paytrail فقط عندما يدفع العميل باليورو. وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

Paytrail

يبدأ القسم بملاحظة قصيرة عن صفحة الدفع الخاصة بـ Paytrail، وبالقاعدة التي تقضي بأن الطلب لا يحصل على حالة إلا بعد أن تؤكد Paytrail الدفعة.

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

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

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد، بجوار أيقونة Paytrail. الافتراضي: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

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

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

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

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

يظهر معرّف التاجر والمفتاح السري في Merchant Panel لدى Paytrail (تفاصيل الحساب أو التكامل). يحتوي القسم على رابط إلى Paytrail. تُدعم المدفوعات باليورو فقط.

Test mode: يستخدم حساب Paytrail التجريبي العام (معرّف التاجر 375917) في الدفعات الجديدة بدلًا من بيانات اعتمادك الخاصة. لا يُخصم أي مبلغ حقيقي، ولا حاجة إلى مفاتيح. ويرى العملاء في خطوة Confirm Order الرسالة وضع الاختبار: لن تُجرى أي دفعة حقيقية. المفتاح السري لحساب الاختبار عام، لذلك يمكن لأي شخص محاكاة دفعة أُجريت في وضع الاختبار. لا تُبقِ وضع الاختبار مفعّلًا أبدًا في متجر حقيقي. الافتراضي: موقوف.

Merchant ID: معرّف التاجر الخاص بك في Paytrail (أرقام فقط). يُستخدم عندما يكون وضع الاختبار موقوفًا. وعلى عكس المفتاح السري، يُعرض على الصفحة بعد الحفظ.

Secret key: مفتاحك السري في Paytrail. يُستخدم عندما يكون وضع الاختبار موقوفًا. لا يُعرض المفتاح المحفوظ مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض الرسالة محفوظ — اتركه فارغًا للإبقاء عليه. اكتب قيمة جديدة فقط إذا أردت تغييرها. ولحذف المفتاح السري المحفوظ، ضع علامة على Clear saved secret key أسفل الحقل ثم انقر على Save.

تستخدم الاستدعاءات الراجعة والاستردادات دائمًا بيانات اعتماد الوضع الذي تمت فيه الدفعة، لذلك لا يؤدي التبديل بين الاختبار والوضع الحقيقي إلى كسر الطلبات السابقة.

الطلبات

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

Callback URL: يعرض العنوان الذي تؤكد عليه Paytrail كل دفعة من خادم إلى خادم. في OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_paytrail_gateway/callback، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_paytrail_gateway/payment/wcp_paytrail_gateway.callback. يُرسل مع كل دفعة، لذلك لا يلزم ضبط شيء في لوحة Paytrail، لكن يجب أن يكون المتجر متاحًا من الإنترنت.

Order status after payment: حالة الطلب المدفوع. الافتراضي: Processing. اختر Complete إذا أردت إكمال كل طلب مدفوع فورًا.

Awaiting payment status: تُبلغ Paytrail بأن الدفعة معلّقة أو متأخرة (فاتورة أو تقسيط في انتظار موافقة المزوّد). يُحدَّث الطلب تلقائيًا عندما تؤكد Paytrail الدفعة أو ترفضها. الافتراضي: Pending.

Payment on hold status: تحتاج الدفعة إلى انتباهك (راجع حالات الطلبات). الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment failed status: تُضبط عندما تفشل دفعة Paytrail معلّقة. الافتراضي: Failed.

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

متقدم

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

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Paytrail). وفي خطوة Confirm Order يرى العميل أيقونة Paytrail ووصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. عندما ينقر العميل على Confirm Order، تنشئ الإضافة دفعة Paytrail بمبلغ الطلب الإجمالي باليورو، مع رقم الطلب كمرجع، وترسل معها بنود الطلب: المنتجات مع خياراتها وضرائبها، وبطاقات الهدايا التي اشتُريت، والشحن والرسوم الأخرى. تُوزَّع القسائم ورصيد المتجر ونقاط المكافآت وبطاقات الهدايا المستخدمة على البنود. ومجموع البنود يساوي دائمًا مبلغ الدفع؛ ويُضاف فرق التقريب إلى أحد البنود أو يُرسل كبند Rounding. تُرسل بيانات الاتصال بالعميل، وعناوين الفوترة والتوصيل فقط عندما تكون كاملة. ولغة صفحة الدفع هي الفنلندية أو السويدية أو الإنجليزية، حسب لغة العميل.

يُوجَّه العميل إلى صفحة الدفع الخاصة بـ Paytrail، فيختار طريقة دفع مفعّلة في حسابك لدى Paytrail ويدفع. ثم تؤكد Paytrail الدفعة مرتين: تعيد العميل إلى متجرك، وتستدعي عنوان callback من خادم إلى خادم. ولا يُقبل أي من التأكيدين إلا بتوقيع صالح مُنشأ ببيانات اعتماد محاولة الدفع تلك، ولمحاولة أُنشئت لهذا الطلب فقط. ويُقارن المبلغ المدفوع بإجمالي الطلب. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Paytrail ذلك بهذه الطريقة، ثم يحصل على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد المعتادة للطلب وتحديث المخزون. تتعامل الإضافة مع حالات Paytrail التالية:

بعد دفعة ناجحة يرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة تم استلام دفعتك عبر Paytrail. وبالنسبة إلى دفعة معلّقة تعرض الصفحة دفعتك عبر Paytrail بانتظار تأكيد مزوّد الدفع. سيُحدَّث الطلب تلقائيًا — يرجى عدم الدفع مرة أخرى. وإذا كان الاستدعاء الراجع يسجّل الدفعة في اللحظة نفسها، تطلب صفحة Payment confirmation من العميل عدم الدفع مرة أخرى، وتعرض الزر Check again.

بعد دفعة ملغاة أو فاشلة يعود العميل إلى صفحة الدفع مع الرسالة تم إلغاء دفعة Paytrail أو فشلت. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وإذا لم تكتمل الدفعة بعد، تكون الرسالة لم تكتمل دفعة Paytrail بعد. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وتُحفظ السلة. وفي OpenCart 4 تُعرض هذه الرسائل أعلى صفحة الدفع. ويعرض أي رجوع لا يمكن التحقق منه صفحة Payment Error مع الرسالة Payment verification failed. دون أن يغيّر شيئًا.

إذا تعذر على Paytrail بدء الدفعة، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل تعذّر الاتصال بـ Paytrail. يرجى المحاولة بعد لحظات.، أو Paytrail غير متاح مؤقتًا. يرجى اختيار طريقة دفع أخرى. (بيانات اعتماد غير صحيحة)، أو تعذّر على Paytrail بدء الدفعة. يرجى التحقق من بيانات الفوترة والمحاولة مرة أخرى، أو اختيار طريقة دفع أخرى. ويُكتب السبب التقني في السجل. وإذا كان إجمالي الطلب خارج حدود Paytrail تظهر الرسالة لا يمكن دفع إجمالي هذا الطلب عبر Paytrail. يرجى اختيار طريقة دفع أخرى.

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

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

يعمل الاستدعاء الراجع أيضًا والمتجر في وضع الصيانة، لأن OpenCart يسمح بمرور طلبات إضافات الدفع (في OpenCart 4 تضيف الإضافة إجراء بدء التشغيل الخاص بها لهذا الغرض، وهو يسمح أيضًا بعودة العميل من Paytrail).

يختار العميل طريقة الدفع في صفحة Paytrail، لا في صفحة الدفع لديك. ولا تتضمن الإضافة ترميز البطاقات أو البطاقات المحفوظة، ولا اشتراكات، ولا shop-in-shop، ولا تفعيلًا يدويًا للفواتير، ولا تقارير تسوية.

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

حالات الطلبات

بلا حالة (طلب مفقود): أُرسل العميل إلى Paytrail ولم يدفع، أو فشلت الدفعة، أو لم تؤكد Paytrail الدفعة بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط عامل التصفية Order Status على Missing Orders.

Order status after payment (الافتراضي Processing): تم تأكيد الدفعة. تعرض ملاحظة معاملة Paytrail وطريقة الدفع المستخدمة فيها والمبلغ، مع العبارة TEST mode — no real money. في المدفوعات التجريبية.

Awaiting payment status (الافتراضي Pending): الدفعة معلّقة لدى المزوّد (فاتورة أو دفعة متأخرة). ينتقل الطلب إلى حالة المدفوع عندما تؤكد Paytrail الدفعة، أو إلى حالة الفشل عندما تفشل الدفعة.

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

Payment failed status (الافتراضي Failed): فشلت دفعة Paytrail معلّقة أو أُلغيت.

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

تُطبَّق الاستدعاءات الراجعة المتكررة أو المتزامنة مرة واحدة فقط، دون ملاحظات مكررة. ولا يُعاد فتح طلب مدفوع أو مسترد أو مكتمل باستدعاء راجع لاحق. وإذا دُفعت محاولة ثانية لطلب أو سلة مدفوعة بالفعل، فلن يتغيّر الطلب؛ وتطلب منك ملاحظة Duplicate payment استرداده في Merchant Panel لدى Paytrail.

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

تبويب VibeFox Paytrail Gateway

في Sales > Orders افتح طلبًا دُفع عبر Paytrail. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Paytrail Gateway محاولات الدفع الخاصة بالطلب (التاريخ، ومعاملة Paytrail والختم مع التسمية Test للمدفوعات التجريبية، والمبلغ، وطريقة الدفع، وحالة Paytrail ونتيجتها)، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، والملاحظات Paytrail notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox Paytrail Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا سببًا لملاحظة الطلب، ثم انقر على Refund via Paytrail. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Paytrail؟ لا يمكن التراجع عن هذا الإجراء. الاستردادات الكاملة والجزئية مدعومة، وبالمبالغ فقط. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يمكنك الاسترداد حتى المبلغ الذي حصّلته Paytrail فعلًا، لذلك بعد اختلاف في المبلغ يكون الحد هو ما دفعه العميل، لا إجمالي الطلب. يستخدم الاسترداد بيانات اعتماد الوضع الذي تمت فيه الدفعة، لذلك يجب ضبط بيانات الاعتماد الحقيقية للدفعة الحقيقية. وتصبح الاستردادات متاحة بعد أن تؤكد Paytrail الدفعة.

إذا لم تدعم طريقة الدفع الاستردادات المباشرة، تبدأ الإضافة تلقائيًا استردادًا عبر البريد الإلكتروني: ترسل Paytrail بريدًا إلى العميل ليُدخل حسابًا مصرفيًا. ويتطلب ذلك وجود البريد الإلكتروني للعميل في الطلب. وتوضح الملاحظة نوع الاسترداد الذي بدأ.

قد يكتمل الاسترداد فورًا أو يُعالَج لاحقًا. وتُضاف تأكيدات Paytrail اللاحقة كملاحظة. وإذا تعذّر على Paytrail إكمال الاسترداد، توضح ملاحظة أن المال لم يُعَد إلى العميل، ولم يعد الاسترداد محسوبًا على أنه مسترد؛ فأعد المبلغ للعميل بوسيلة أخرى. وإذا رفضت Paytrail الاسترداد فورًا، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويضبط الاسترداد الكامل الطلب على Refunded status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا مثل تغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة.

لا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر Paytrail. ولا تُزامَن مع OpenCart الاستردادات التي تُجرى في Merchant Panel لدى Paytrail.

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

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

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

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

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

لا تظهر Paytrail في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Test mode مفعّل أو أن Merchant ID وSecret key مملوءان (وليس حساب الاختبار العام 375917). وتحقق من أن العميل يدفع باليورو، ومن أن عنوان الدفع يقع ضمن Geo Zone المحدد، ومن أن الطلب يبلغ Total المضبوط في الإعدادات. تعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد أو عند كون عملة المتجر غير اليورو.

تمت الدفعة، لكن الطلب يبقى بلا حالة: لا يستطيع الاستدعاء الراجع الوصول إلى متجرك، ولم يعد العميل إلى المتجر. يجب أن يكون Callback URL المعروض في قسم Orders متاحًا من الإنترنت (دون مصادقة أساسية أو جدار حماية يعترض الطريق).

يرد الاستدعاء الراجع أو الرجوع بـ Payment verification failed.: التوقيع غير صالح، أو أن الدفعة لا تنتمي إلى أي محاولة دفع للطلب. لا يتغيّر شيء. تحقق من أن Secret key صحيح وأنه تابع لـ Merchant ID.

يرد الاستدعاء الراجع بـ Temporarily unavailable: كان الطلب يُؤكَّد بطلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. تعيد Paytrail الاستدعاء. انظر إلى الحقل Log لمعرفة السبب.

يرى العميل خطأ بعد Confirm Order: انظر إلى الحقل Log في صفحة الإضافة. فمثلًا Paytrail API error (401) يعني بيانات اعتماد خاطئة. فعّل Debug log لمزيد من التفاصيل. أما This payment method is not available. Please reload the checkout page. فتعني أن طريقة الدفع أُوقفت في الأثناء، أو أن صفحة الدفع لم تعد تطابق الطلب.

لا يُحفظ معرّف التاجر: يجب أن يحتوي على أرقام فقط. انسخه من جديد من Merchant Panel لدى Paytrail.

الطلب في حالة الانتظار (on hold): اقرأ الملاحظات في تبويب VibeFox Paytrail Gateway. والسبب قد يكون مبلغًا مدفوعًا مختلفًا، أو دفعة وصلت بعد تغيير الحالة، أو دفعة تجريبية في الوضع الحقيقي.

يفشل الاسترداد: اقرأ الرسالة. This order has no confirmed Paytrail payment. Refund it manually. تعني أنه لا توجد دفعة Paytrail مؤكَّدة لاستردادها. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. تعني أن الدفعة تمت في الوضع الحقيقي وأن بيانات الاعتماد الحقيقية غير مضبوطة. Invalid refund amount: at most … تعني أن المبلغ أكبر مما تبقّى للاسترداد. This payment method supports only e-mail refunds, but the order has no billing e-mail. تعني أن الطلب يحتاج إلى البريد الإلكتروني للعميل.

للمطورين: قبل أن يُوقَّع طلب الدفع ويُرسل، تُطلق الإضافة حدث OpenCart ptg_payment_request مع الطلب والطلب نفسه.

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

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

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

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