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

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

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

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

التثبيت

1. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Datatrans Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالة الطلب Datatrans payment on hold. تفعّل PrestaShop وحدة الدفع الجديدة افتراضيًا لكل العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ ولا يظهر Datatrans إلا للعملات المسموح بها هناك.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. عندما تكون طريقة الدفع مفعّلة لكن البيئة الحالية لا تحتوي على Merchant ID أو كلمة مرور 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.

Datatrans

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via Datatrans.

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

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

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

Sandbox merchant ID: Merchant ID لحساب sandbox الخاص بك.

Sandbox API password: كلمة مرور API من خادم إلى خادم لحساب sandbox.

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

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

انسخها من Web Admin الخاص بالإنتاج لدى Datatrans (admin.datatrans.com).

Production merchant ID: Merchant ID لحساب الإنتاج الخاص بك.

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

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

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

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

عنوان Webhook

يعرض هذا القسم عنوان webhook لمتجرك. مع تفعيل الروابط الودية يكون بالشكل https://your-shop/module/wcp_datatrans_gateway/webhook، وقد يسبقه رمز لغة مثل /en/. ترسل الوحدة هذا العنوان إلى Datatrans مع كل معاملة، لذلك لا تحتاج إلى إدخاله في أي مكان. ويمكنك أيضًا إدخاله في إعدادات الـ webhooks في Web Admin الخاص بـ Datatrans لتلقي تحديثات عمليات التحصيل والإلغاء التي تُجرى هناك؛ انسخه تمامًا كما تعرضه الإعدادات. الاستردادات التي تتم في Web Admin الخاص بـ Datatrans لا تنعكس على الطلب.

يُبلغ الـ webhook عن حالة المعاملة. وتتصرف الوحدة وفق الحالات التالية:

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

معالجة الدفع

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

Order status after payment: حالة الطلب بعد تسوية الدفعة.

الدفعات المفوَّضة فقط وحالات عدم تطابق المبلغ أو العملة تذهب دائمًا إلى Datatrans payment on hold.

متقدم

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

Log: يعرض حجم السجل وأحدث إدخالاته، مع زر لمسحه.

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

إتمام الشراء

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Datatrans ذلك: عبر الـ webhook، أو عبر طلب من الخادم إلى واجهة حالة Datatrans عندما يعود العميل. يحمل عنوان العودة المفتاح الآمن للسلة، والعودة نفسها لا تُنشئ طلبًا أبدًا. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة 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؛ وينشئ الـ webhook الطلب فور وصوله.

إذا ألغى العميل في صفحة 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. تُحفظ السلة. ومحاولة جديدة تُنشئ معاملة Datatrans جديدة، كما تظل الدفعة المتأخرة لمحاولة سابقة معترفًا بها.

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

يعمل الـ webhook أثناء وضع الصيانة للمتجر، ولا يتأثر بقيود الدول في متجرك.

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

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Datatrans ولم يدفع، أو فشلت الدفعة أو أُلغيت، أو لم تؤكدها Datatrans بعد. لا توجد سوى السلة.

Payment accepted أو Delivered أو Datatrans payment on hold: تمت تسوية الدفعة. وتتبع الحالة Order status after payment. تُسجَّل الدفعة مع معرّف معاملة Datatrans، وتعرض ملاحظة المبلغ وطريقة الدفع والبيئة وطريقة التأكيد (webhook أو عودة).

Datatrans payment on hold بعد تفويض: Auto settle موقوف والدفعة مفوَّضة فقط. حصّلها أو ألغها من قسم الطلب.

Datatrans payment on hold بعد الدفع: أبلغت Datatrans عن مبلغ أو عملة مختلفة عن إجمالي السلة (مثلًا، عُدّلت السلة بعد بدء الدفع)، أو وصلت الدفعة بعد إلغاء الطلب. تشرح الملاحظة السبب. تحقق من المعاملة في Web Admin الخاص بـ Datatrans، ثم أنجز الطلب أو استرد الدفعة.

Canceled: أُفكّ التفويض، في قسم الطلب أو في Web Admin الخاص بـ Datatrans.

Refunded: استُرِدّت الدفعة بالكامل عبر الوحدة.

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

كتلة Datatrans payment

تعرض صفحة الطلب كتلة Datatrans payment تحتوي على معرّف المعاملة وحالة Datatrans وطريقة الدفع والمبلغ والمبالغ المدفوعة والمستردة، وشارة Sandbox للدفعات التجريبية، وسجل الاستردادات وDatatrans notes الخاصة بالطلب. تتطلب إجراءات الكتلة صلاحية تعديل الطلبات؛ ولا تحتاج إلى صلاحية الوصول إلى صفحات الوحدات.

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

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

الاستردادات

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

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

لا تنشئ الوحدة إشعارات دائنة (credit slips). أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر Datatrans. والاستردادات التي تتم في Web Admin الخاص بـ Datatrans لا تُسجَّل في PrestaShop.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Datatrans Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox Datatrans Gateway > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. تحتها يظهر السطر Product: presta-payment-datatrans والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

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

يعمل المفتاح الواحد على نطاق واحد: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. لا يؤدي حذف المفتاح من المتجر إلى تحرير خانة النطاق. حرّر الخانة من حسابك في vibefox.net.

من دون مفتاح نشط لا يظهر Datatrans للعملاء عند الدفع. إذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. لا تعرف واجهة المتجر في PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها في خطوة الدفع. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: المدفوعات التي بدأت بالفعل ما زالت تُؤكَّد، والاستردادات تعمل.

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

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

Datatrans does not appear at checkout: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة الحالية تحتوي على Merchant ID وكلمة مرور API: حقول sandbox في وضع sandbox، وحقول الإنتاج في غير ذلك. تعرض صفحة الإعدادات الحقول الناقصة. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ودولة العميل ومجموعة العميل.

The payment went through, but no order was created: لم تتمكن Datatrans من الوصول إلى عنوان الـ webhook، ولم يعد العميل إلى المتجر. تحقق من أن المتجر قابل للوصول من الإنترنت، وأن جدار الحماية لا يحجب الطلبات إلى عنوان الـ webhook. تحقق من أن مفتاح التوقيع في الإعدادات يعود إلى بيئة الدفع. راجع حقل Log في صفحة الوحدة.

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

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

Webhook answers Busy, retry: كان الطلب يُؤكَّد في الوقت نفسه بطلب آخر، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد Datatrans إرسال الـ webhook. ويعرض السجل السبب.

The webhook URL shows Method not allowed in the browser: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Datatrans فقط.

The HMAC sign key is not saved: يجب أن يكون المفتاح سلسلة سداسية عشرية. انسخه مرة أخرى من Web Admin الخاص بـ Datatrans.

The customer sees Datatrans payments are not configured yet: Merchant ID أو كلمة مرور API للبيئة الحالية مفقودة.

The customer sees The payment could not be started: راجع حقل Log. الأسباب المعتادة هي Merchant ID أو كلمة مرور API غير صحيحة، أو بيانات اعتماد تخص بيئة خاطئة.

Order is Datatrans payment on hold after payment: اقرأ Datatrans notes في كتلة الطلب (انظر حالات الطلب)، ثم أنجز الطلب أو استرد الدفعة.

Capture is refused: إجمالي الطلب أعلى من المبلغ المفوَّض. لا تستطيع Datatrans تسوية أكثر مما فُوّض.

Refund or capture fails with a message about missing credentials: تمت الدفعة في البيئة الأخرى، ولم يُضبط Merchant ID أو كلمة مرور API الخاصة بها. أدخلهما وأعد المحاولة.

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Datatrans Gateway، واختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Delete data on uninstall مفعّلًا تُحذف إعدادات الوحدة والسجل. وإذا كان موقوفًا تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تبقى معاملات Datatrans واستردادها وحالة الطلب Datatrans payment on hold محفوظة دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا أو تحصيلها بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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