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

المتطلبات

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

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

حساب Datatrans: تحتاج إلى معرّف التاجر (merchant ID) وكلمة مرور واجهة API بين الخادم والخادم، وموصى به مفتاح توقيع HMAC-SHA256 لـ webhooks. تأتي بيانات اعتماد بيئة الاختبار (sandbox) من Web Admin الخاصة ببيئة الاختبار في Datatrans (admin.sandbox.datatrans.com)، وتأتي بيانات اعتماد الإنتاج من Web Admin الإنتاجية (admin.datatrans.com). بيئة الاختبار والإنتاج حسابان منفصلان في Datatrans بمعرّفات تاجر ومفاتيح مختلفة.

متجر يمكن الوصول إليه: ترسل Datatrans الـ webhooks من خوادمها، لذلك يجب أن يكون متجرك متاحًا من الإنترنت.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل بيانات اعتماد بيئة الاختبار من Web Admin الخاصة ببيئة الاختبار في Datatrans (انظر الإعداد).

5. فعّل Enable/Disable وانقر على Save. أجرِ دفعة تجريبية في وضع sandbox. وعندما يعمل كل شيء، أدخل بيانات اعتماد الإنتاج وأوقف Sandbox mode.

OpenCart 4

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

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

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

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

يبدأ التثبيت الجديد وطريقة الدفع معطّلة ووضع sandbox مفعّلًا. يُرسل عنوان الـ webhook إلى Datatrans مع كل معاملة، لذلك لا تحتاج إلى إعداده بنفسك.

الإعداد

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Datatrans Gateway > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ زر Save أسفل القائمة الصفحة كاملةً. عندما تكون طريقة الدفع مفعّلة لكن البيئة الحالية لا تملك معرّف التاجر أو كلمة مرور API، تعرض الصفحة Datatrans is hidden at checkout until these settings are filled in: مع الحقول الناقصة. وطالما كان وضع sandbox مفعّلًا، تعرض الصفحة Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

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

Datatrans

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via Datatrans.

Sandbox mode: يستخدم بيئة sandbox الخاصة بـ Datatrans: دفعات تجريبية، دون أي أموال حقيقية. يبدّل هذا المفتاح كلًا من خوادم Datatrans وبيانات الاعتماد المستخدمة للمدفوعات الجديدة. الافتراضي: مفعّل. أوقفه لاستقبال مدفوعات حقيقية. وطالما كان مفعّلًا، يرى العملاء في خطوة Confirm Order العبارة Sandbox mode: no real payment is taken. وتستخدم الاستردادات والتحصيل دائمًا البيئة التي تمّ فيها الدفع، بصرف النظر عن هذا المفتاح.

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

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

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

بيانات اعتماد بيئة الاختبار

انسخها من Web Admin الخاصة ببيئة الاختبار في Datatrans (admin.sandbox.datatrans.com، وتتضمن الصفحة الرابط). يوجد مفتاح التوقيع في إعدادات الأمان هناك.

Sandbox merchant ID: معرّف التاجر لحساب بيئة الاختبار.

Sandbox API password: كلمة مرور واجهة API بين الخادم والخادم لحساب بيئة الاختبار.

Sandbox HMAC sign key: المفتاح السداسي العشري المستخدم للتحقق من الترويسة Datatrans-Signature في الـ webhooks. وبدونه يُعاد التحقق من كل webhook عبر واجهة حالة Datatrans.

بيانات اعتماد الإنتاج

انسخها من Web Admin الإنتاجية في Datatrans (admin.datatrans.com).

Production merchant ID: معرّف التاجر لحساب الإنتاج.

Production API password: كلمة مرور واجهة API بين الخادم والخادم لحساب الإنتاج.

Production HMAC sign key: المفتاح السداسي العشري المستخدم للتحقق من الترويسة Datatrans-Signature في webhooks الإنتاج. وبدونه يُعاد التحقق من كل webhook عبر واجهة حالة Datatrans.

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

عنوان الـ Webhook

يعرض القسم عنوان الـ webhook الخاص بمتجرك. وهو يبدو هكذا في OpenCart 3: https://your-store/index.php?route=extension/payment/wcp_datatrans_gateway/webhook، وفي OpenCart 4: https://your-store/index.php?route=extension/wcp_datatrans_gateway/payment/wcp_datatrans_gateway.webhook، ويُبنى من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. ترسل الإضافة هذا العنوان إلى Datatrans مع كل معاملة، لذلك لا تحتاج إلى إدخاله في أي مكان. ويمكنك أيضًا إدخاله في إعدادات الـ webhooks في Web Admin الخاصة بـ Datatrans لتلقي تحديثات عمليات التحصيل والإلغاء التي تُنفَّذ هناك؛ انسخه تمامًا كما تعرضه الإعدادات. ولا تنعكس الاستردادات المنفّذة في Web Admin الخاصة بـ Datatrans على الطلب.

يُبلغ الـ webhook بحالة المعاملة. وتتصرف الإضافة بناءً على هذه الحالات:

مع مفتاح توقيع HMAC، يُتحقق من كل webhook عبر ترويسته Datatrans-Signature بمفتاح التوقيع الخاص بالبيئة التي تمّ فيها الدفع. تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. وبدون مفتاح توقيع، لا تثق الإضافة بمحتوى الـ webhook، وتتحقق من كل webhook عبر واجهة حالة Datatrans. وبدون الـ webhook، لا يحصل الطلب على حالته إلا عندما يعود العميل إلى المتجر بعد الدفع.

معالجة الدفع

Auto settle: يحصّل المدفوعات (يُسوّيها) فورًا. وإذا كان معطّلًا، تُفوَّض المدفوعات فقط: يُوضع الطلب في حالة الانتظار، وتحصّله لاحقًا عبر Capture Datatrans payment في تبويب الطلب، أو تفرج عنه عبر Cancel Datatrans authorization. الافتراضي: مفعّل.

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تؤكد Datatrans الدفع. وتترك الدفعة الفاشلة أو الملغاة الطلب دون حالة، وتُحفظ سلة المشتريات. يسرد كل حقل من الحقول التالية حالات الطلبات في OpenCart لديك.

Order status after payment: حالة الطلب بعد تسوية الدفعة وتطابق مبلغها وعملتها. الافتراضي: Processing.

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

Authorization canceled: تُعيَّن عند الإفراج عن التفويض عبر Cancel Datatrans authorization أو في Web Admin الخاصة بـ Datatrans. الافتراضي: Canceled.

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

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات الوحدة والسجل. تبقى سجلات الدفع الخاصة بـ Datatrans للطلبات (المعاملات والاستردادات) محفوظة. الافتراضي: معطّل.

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

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

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

إتمام الطلب

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

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Datatrans الدفع: إما عبر الـ webhook، أو عبر طلب من جهة الخادم إلى واجهة حالة Datatrans عند عودة العميل. يحمل عنوان العودة رمزًا عشوائيًا لمحاولة الدفع، ولا يُوثق بالعنوان نفسه أبدًا. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع العبارة Your payment with Datatrans has been received. وفي الدفعة المفوَّضة فقط، تعرض الصفحة Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. وإذا لم تؤكد Datatrans الدفع بعد، تعرض صفحة Payment confirmation العبارة Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. مع الزرين Check again وBack to checkout؛ ويعيّن الـ webhook حالة الطلب فور وصوله. وفي OpenCart 4 لا يرسل المتصفح جلسة المتجر عندما ترجع Datatrans العميل، لذلك تعرض الإضافة أولًا صفحة قصيرة تفتح عنوان العودة نفسه من متجرك مرة أخرى: يحتفظ العميل بالسلة وبتسجيل الدخول.

إذا ألغى العميل في صفحة Datatrans، يعود إلى صفحة الدفع مع The payment was canceled. You can try again or choose another payment method. وإذا فشلت الدفعة، تكون الرسالة The payment was not completed. Please try again or choose another payment method. وفي OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع. تُحفظ سلة المشتريات. وينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، بينما يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، وتكون المحاولة الجديدة معاملة Datatrans جديدة للطلب نفسه. وقبل بدء دفعة جديدة، تُفحص معاملات Datatrans المفتوحة للطلبات السابقة من السلة نفسها: تُؤكَّد المعاملة المدفوعة أو المفوَّضة بدلًا من بدء دفعة جديدة، وتُلغى المعاملة المفتوحة في Datatrans. تُدفع السلة مرة واحدة فقط: إذا كان طلب آخر من السلة نفسها مدفوعًا أو مفوَّضًا بالفعل، فلا تُبدأ أي دفعة جديدة، وينتقل العميل إلى صفحة النجاح. وإذا وصلت دفعة لطلب آخر من سلة مدفوعة، يبقى ذلك الطلب دون حالة، ويتلقى الطلب المدفوع ملاحظة تطلب منك التحقق من النسخة المكررة واستردادها في Datatrans.

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

إذا تعذّر على Datatrans بدء الدفعة، يبقى العميل في خطوة Confirm Order مع The payment could not be started. Please try again or choose another payment method. ويُكتب السبب التقني في السجل.

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

تقبل الإضافة المدفوعات لمرة واحدة في صفحة الدفع الخاصة بـ Datatrans. ولا تتضمن بطاقات أو أسماء مستعارة محفوظة، ولا اشتراكات، ولا Lightbox أو Secure Fields على موقعك، ولا اختيار طرق الدفع في الإعدادات، ولا تحصيلًا جزئيًا لتفويض.

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

حالات الطلب

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

Order status after payment (default Processing): تمت تسوية الدفعة. تعرض الملاحظة المبلغ وطريقة الدفع ومعرّف معاملة Datatrans والبيئة وكيفية التأكيد (عبر الـ webhook أو العودة).

Datatrans payment on hold after an authorization (default Pending): Auto settle معطّل والدفعة مفوَّضة فقط. حصّلها أو ألغها من تبويب الطلب.

Datatrans payment on hold after payment: أبلغت Datatrans عن مبلغ أو عملة مختلفين عن إجمالي الطلب، أو وصلت الدفعة بعد إلغاء الطلب. توضح الملاحظة ذلك. تحقق من المعاملة في Web Admin الخاصة بـ Datatrans، ثم أكمل الطلب أو استرد الدفعة.

Authorization canceled (default Canceled): أُفرج عن التفويض، في تبويب الطلب أو في Web Admin الخاصة بـ Datatrans.

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

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

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

تبويب VibeFox Datatrans Gateway

في Sales > Orders افتح طلبًا دُفع عبر Datatrans. وفي أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Datatrans Gateway الحقل Transaction ID مع وسم Sandbox للمدفوعات في بيئة الاختبار، وStatus الخاص بـ Datatrans، وPayment method، وAmount، والمبالغ Paid / refunded، وأزرار التحصيل والإلغاء أو نموذج الاسترداد، وسجل الاسترداد، وDatatrans notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة. وتتطلب إجراءاته صلاحية تعديل الإضافة (تُحدَّد في System > Users > User Groups).

التحصيل والإلغاء

بالنسبة إلى دفعة مفوَّضة فقط، يعرض التبويب Capture Datatrans payment وCancel Datatrans authorization. يسوّي التحصيل الدفعة بإجمالي الطلب الحالي، ولا يمكن أن يتجاوز المبلغ المُفوَّض؛ ثم ينتقل الطلب إلى Order status after payment. يُفرج الإلغاء عن التفويض ويضع الطلب في Authorization canceled. وكلاهما يذهب إلى بيئة الدفع. وإذا رفضت Datatrans، يعرض التبويب الخطأ وتُضاف ملاحظة.

الاسترداد

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

تتوفر عمليات الاسترداد بعد أن تسوّي Datatrans الدفعة. أما الدفعة المفوَّضة فقط فتُحصَّل أو تُلغى بدلًا من ذلك، ولا يمكن استرداد تفويض بمبلغ غير متطابق إلا بعد تسويته.

لا ترد المرتجعات في Sales > Returns أموالًا عبر Datatrans. ولا تُسجَّل في OpenCart عمليات الاسترداد المنفّذة في Web Admin الخاصة بـ Datatrans.

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

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

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

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

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

لا يظهر Datatrans عند إتمام الطلب: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة الحالية لديها معرّف التاجر وكلمة مرور API: حقول بيئة الاختبار في وضع sandbox، وحقول الإنتاج في غير ذلك. تسرد صفحة الإعدادات الحقول الناقصة. وتحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمّ الدفع، لكن الطلب بقي دون حالة: لم تستطع Datatrans الوصول إلى عنوان الـ webhook، ولم يعد العميل إلى المتجر. تحقق من أن المتجر متاح من الإنترنت، وأن لا جدار ناري يحجب الطلبات الموجهة إلى عنوان الـ webhook. وتحقق من أن مفتاح التوقيع في الإعدادات يتبع بيئة الدفع. انظر إلى الحقل Log في صفحة الإضافة.

يرد الـ webhook بـ Invalid signature: مفتاح توقيع HMAC في الإعدادات لا يطابق المفتاح الموجود في Web Admin الخاصة بـ Datatrans، أو أنه يتبع البيئة الأخرى. انسخ المفتاح مجددًا.

يرد الـ webhook بـ Not configured أو Verification failed: كان يجب التحقق من الـ webhook عبر واجهة حالة Datatrans، لكن بيانات اعتماد تلك البيئة مفقودة، أو لم ترد Datatrans. ستعيد Datatrans إرسال الـ webhook.

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

يعرض عنوان الـ webhook Method not allowed في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Datatrans فقط.

مفتاح توقيع HMAC لا يُحفظ: يجب أن يكون المفتاح سلسلة سداسية عشرية. انسخه مجددًا من Web Admin الخاصة بـ Datatrans.

يرى العميل Datatrans payments are not configured yet: معرّف التاجر أو كلمة مرور API للبيئة الحالية مفقودة.

يرى العميل The payment could not be started: انظر إلى الحقل Log. معرّف تاجر أو كلمة مرور API خاطئان، أو بيانات اعتماد لبيئة خاطئة، هما السببان المعتادان.

يرى العميل We could not verify the payment: عنوان العودة لم يطابق أي محاولة دفع للطلب. وإذا خُصم المبلغ، فإن الـ webhook يعيّن حالة الطلب على كل حال.

الطلب في حالة الانتظار بعد الدفع: اقرأ Datatrans notes في تبويب الطلب (انظر حالات الطلب)، ثم أكمل الطلب أو استرد الدفعة.

التحصيل مرفوض: إجمالي الطلب أكبر من المبلغ المُفوَّض. لا تستطيع Datatrans تسوية أكثر مما فُوِّض.

لا توجد أزرار تحصيل أو نموذج استرداد في التبويب: يوضح التبويب السبب: الدفعة لم تُسوَّ بعد، أو استُردت بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة، أو بيانات اعتماد بيئة الدفع مفقودة.

يفشل الاسترداد أو التحصيل برسالة تتعلق ببيانات اعتماد مفقودة: تم الدفع في البيئة الأخرى، ومعرّف التاجر أو كلمة مرور API لتلك البيئة غير مُعيّنين. أدخلهما ثم أعد المحاولة.

للمطورين: قبل إنشاء معاملة Datatrans، تُطلق الإضافة حدث OpenCart datatrans_p_init_request مع نص الطلب والطلب نفسه.

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

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

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

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