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

المتطلبات

WordPress: الإصدار 6.0 أو أحدث.

WooCommerce: الإصدار 7.0 أو أحدث، مثبّت ومفعّل.

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

HTTPS: يجب أن يكون موقعك متاحًا من الإنترنت عبر HTTPS حتى تتمكن Datatrans من تسليم الـ webhooks.

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

العملة: يجب أن تكون عملة المتجر (أو عملة الطلب في إضافة تعدد العملات لديك) مفعّلة لحساب التاجر لديك في Datatrans.

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

التثبيت

1. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر Install Now. يمكنك أيضًا رفع المجلد wcp_datatrans_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate. يجب أن يكون WooCommerce مفعّلًا.

3. افتح الإعدادات: WooCommerce > Settings > Payments > Datatrans > Manage، أو انقر Settings أسفل اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة وانقر Activate.

5. أدخل بيانات اعتماد بيئة الاختبار، وللمدفوعات الحقيقية أدخل بيانات اعتماد الإنتاج (انظر الإعداد).

6. فعّل Enable/Disable. أبقِ Sandbox mode مفعّلًا أثناء الاختبار، ثم أزل علامة التحديد لقبول المدفوعات الحقيقية.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Datatrans. عندما تكون البوابة مفعّلة ولكن Merchant ID أو كلمة مرور API للبيئة الحالية مفقودة، تعرض الصفحة Datatrans is hidden at checkout until these settings are filled in: مع قائمة بالحقول الناقصة. وما دام وضع الاختبار مفعّلًا، تعرض Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Webhook

يظهر Webhook URL أعلى الإعدادات. ويبدو هكذا: https://your-site/wc-api/datatrans_payment_callback/. ترسل الإضافة هذا العنوان إلى Datatrans مع كل معاملة، فلا حاجة لإدخاله في أي مكان. ويمكنك أيضًا إدخاله في إعدادات webhook في Datatrans Web Admin لتلقي تحديثات عمليات التحصيل والإلغاء التي تُجرى هناك.

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

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

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Datatrans.

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

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). يبدّل مضيفي API وصفحة الدفع وبيانات الاعتماد الواردة أدناه. تستخدم الاستردادات والتحصيل دائمًا البيئة التي تم فيها الدفع. الافتراضي: مفعّل. أزل علامة التحديد لقبول المدفوعات الحقيقية.

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

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

Sandbox merchant ID: Merchant ID لحساب بيئة الاختبار لديك.

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

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

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

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

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

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

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

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

معالجة الدفع

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

Order status after payment: حالة الطلب التي تُعيَّن بعد تسوية الدفعة. تُعيَّن الحالة فورًا، دون تغيير ثانٍ للحالة.

متقدم

Logging: يكتب Log payment events and API calls التفاصيل في WooCommerce > Status > Logs، والمصدر wcp_datatrans_gateway. تُسجَّل الأخطاء دائمًا. لا تُكتب أي مفاتيح أو بيانات بطاقات أو بيانات عملاء. الافتراضي: متوقف.

Delete data on uninstall: Remove the plugin settings when the plugin is deleted. الافتراضي: متوقف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Datatrans) ويُتم الطلب. تنشئ الإضافة معاملة في Datatrans بإجمالي الطلب وبعملة الطلب، مع معرّف الطلب كمرجع، وتحوّل العميل إلى صفحة الدفع الخاصة بـ Datatrans. هناك يدفع العميل بأي طريقة مفعّلة في حسابك لدى Datatrans، مثل البطاقة أو TWINT أو PostFinance. تُفتح صفحة الدفع بالألمانية أو الإنجليزية أو الفرنسية أو الإيطالية عندما يستخدم موقعك إحدى هذه اللغات؛ وإلا تختار Datatrans اللغة.

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Datatrans ذلك: عبر الـ webhook أو عبر طلب من جهة الخادم إلى واجهة حالة Datatrans البرمجية (API) عند عودة العميل. يحمل عنوان العودة مفتاح الطلب، والعودة نفسها لا تُعلّم الطلب كمدفوع أبدًا.

إذا ألغى العميل في صفحة الدفع، ينتقل إلى صفحة Pay for order مع الرسالة 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 من بدء الدفع، يرى العميل The payment could not be started. Please try again or choose another payment method. ويُكتب السبب في السجل.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع High-Performance Order Storage (HPOS) في WooCommerce.

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

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

حالات الطلب

Pending payment: حُوِّل العميل إلى Datatrans ولم يدفع بعد، أو ألغى في صفحة الدفع، أو لم تؤكد Datatrans الدفعة بعد. تُدوَّن كل معاملة جديدة في الطلب مع معرّفها وبيئتها.

Processing, Completed or On Hold: سُوِّيت الدفعة. تتبع الحالة إعداد Order status after payment. تعرض ملاحظة الطلب المبلغ وطريقة الدفع ومعرّف معاملة Datatrans والبيئة (اختبار أو إنتاج). ويُحفظ معرّف المعاملة في الطلب.

On hold, authorized: عند إيقاف Auto settle، فُوِّضت الدفعة ولكن لم تُحصَّل. افتح الطلب واختر Capture Datatrans payment أو Cancel Datatrans authorization من إجراءات الطلب. يستخدم التحصيل إجمالي الطلب الحالي، الذي يجب ألا يتجاوز المبلغ المفوَّض. وإذا تجاوزه، أو رفضت Datatrans التحصيل أو الإلغاء، يُضاف السبب إلى ملاحظات الطلب.

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

Failed: فشلت الدفعة أو رُفضت. يمكن للعميل المحاولة مرة أخرى.

Cancelled: أُفرج عن التفويض، بإجراء على الطلب أو في Datatrans Web Admin.

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

الاستردادات

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

بالنسبة إلى دفعة مفوَّضة فقط، يؤدي استرداد المبلغ كاملًا إلى إلغاء التفويض. ولا يمكن الاسترداد الجزئي إلى أن تُحصَّل الدفعة.

لا تُسجَّل الاستردادات التي تُجرى في Datatrans Web Admin في WooCommerce. وعند الحاجة، أنشئ استردادًا يدويًا في WooCommerce دون Refund via Datatrans.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. توجد كتلة الترخيص أعلى WooCommerce > Settings > Payments > Datatrans. الصق المفتاح في License key وانقر Activate. تعرض الكتلة الحالة، مثل التاريخ الذي يظل الترخيص فعّالًا حتى نهايته، ونطاقك. استخدم Check now لفحص الحالة مرة أخرى، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك في vibefox.net.

يعمل المفتاح الواحد على نطاق واحد. وإزالة المفتاح من موقع لا تحرر مكان نطاقه. حرّر المكان من حسابك في vibefox.net.

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

عندما ينتهي الترخيص، تواصل الإضافة العمل، لكن التحديثات والدعم تتطلب التجديد. وتُفحص الحالة مجددًا تلقائيًا في الخلفية.

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

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

تمت الدفعة لكن الطلب يبقى بانتظار الدفع: لم تتمكن Datatrans من الوصول إلى عنوان webhook ولم يعد العميل إلى المتجر. تحقق من أن الموقع متاح من الإنترنت عبر HTTPS ومن أن أي إضافة أمان أو جدار حماية لا يحجب الطلبات إلى /wc-api/datatrans_payment_callback/. تحقق من أن مفتاح التوقيع في الإعدادات يخص بيئة الدفعة. فعّل Logging وانظر في WooCommerce > Status > Logs، والمصدر wcp_datatrans_gateway.

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

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

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

يرى العميل The payment could not be started: Merchant ID أو كلمة مرور API خاطئة، أو تخص البيئة الأخرى، أو أن العملة غير مفعّلة في حسابك لدى Datatrans. فعّل Logging لمعرفة السبب.

الطلب قيد الانتظار بعد الدفع: اقرأ ملاحظة الطلب. إما أن المبلغ المدفوع أو العملة اختلفا عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب، أو أن الدفعة مفوَّضة فقط وتنتظر التحصيل.

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

يفشل الاسترداد برسالة عن بيانات الاعتماد: تم الدفع في البيئة الأخرى وبيانات اعتمادها غير مضبوطة. أدخلها وحاول مرة أخرى. وبالنسبة إلى دفعة مفوَّضة، استرد المبلغ كاملًا أو حصّله أولًا.

تعرض كتلة الترخيص خطأً: اتبع الرسالة في الكتلة. فمثلًا، إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، فحرّر مكانًا في حسابك في vibefox.net وانقر Check now. وإذا تغيّر عنوان الموقع، فانقر Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

للمطورين، يذكر ملف readme الفلتر wcp_datatrans_gateway_init_request، مثلًا لتقييد طرق الدفع المعروضة في صفحة Datatrans.

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

يؤدي تعطيل الإضافة إلى الاحتفاظ بجميع البيانات. ولإزالتها، عطّلها واحذفها من صفحة Plugins. يُزال مفتاح ترخيص هذه الإضافة وحالة الترخيص دائمًا. أما إعدادات البوابة فلا تُزال إلا إذا كان Delete data on uninstall مفعّلًا. وإلا فتبقى لإعادة تثبيت لاحقة. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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