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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث. يلزم امتداد OpenSSL والاتصال الصادر بـ HTTPS إلى secure.tpay.com للتحقق من توقيع JWS في الإشعارات.

عملة المتجر: الزلوتي البولندي (PLN) فقط. تُسوّي Tpay المدفوعات بعملة PLN ولا يحتوي Open API الخاص بها على حقل للعملة، لذلك تُخفى طريقة الدفع عندما يستخدم المتجر (أو الطلب المراد دفعه) عملة أخرى.

وصول الموقع إلى الإنترنت: ترسل Tpay إشعارات الدفع إلى متجرك، لذا يجب أن يكون عنوان الإشعار قابلًا للوصول من الإنترنت (غير محجوب بوضع الصيانة أو بجدار الحماية أو بالمصادقة عبر HTTP).

حساب Tpay: تحتاج هذه القيم من لوحة التاجر في Tpay: Merchant ID (معرّف حسابك في Tpay)، ومفتاحا Open API هما Client ID وClient secret (Integration، API)، ورمز الأمان (Settings، Notifications). وتأتي مفاتيح بيئة الاختبار من حساب منفصل لبيئة الاختبار في Tpay.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل مفاتيح بيئة الاختبار ومفاتيح الإنتاج (راجع قسم الإعداد). لا يلزم ضبط أي شيء في لوحة Tpay سوى رمز الأمان: يُرسل عنوان الإشعار مع كل معاملة.

6. فعّل Enable/Disable، واختبر دفعة في وضع بيئة الاختبار، ثم ألغِ تحديد Sandbox mode لقبول المدفوعات الحقيقية.

الإعداد

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Tpay. وتعرض الصفحة فوق الحقول الرسالة Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. ما دام وضع بيئة الاختبار مفعّلًا. كما تحذّرك عندما تكون مفاتيح الوضع الحالي غير مكتملة (فلا يظهر Tpay حينها في الدفع)، وعندما لا تكون عملة المتجر PLN، وعندما يكون امتداد OpenSSL في PHP مفقودًا والتحقق من JWS مفعّلًا (فلن تُؤكَّد المدفوعات حينها). وفي قائمة طرق الدفع يُعلَّم Tpay بأنه يحتاج إلى إعداد حتى تُدخل مفاتيح الوضع الحالي. تُحذف المسافات الملصوقة مع Merchant ID أو Client ID عند الحفظ.

عام

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

Title: عنوان طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: Tpay.

Description: وصف طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: Pay with BLIK, online bank transfer or card on the secure Tpay page.

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

مفاتيح الإنتاج

أين تجدها: في لوحة التاجر في Tpay ضمن Integration، API (مفاتيح Open API: Client ID وSecret)؛ وMerchant ID هو معرّف حسابك في Tpay؛ ورمز الأمان موجود ضمن Settings، Notifications.

Merchant ID: معرّف حسابك في Tpay (أرقام). ترسله Tpay مع كل إشعار.

Client ID: معرّف Open API Client ID.

Client secret: سر Open API Client secret.

Security code: يُستخدم للتحقق من المجموع الاختباري MD5 لإشعارات Tpay.

مفاتيح بيئة الاختبار

بيئة الاختبار هي حساب Tpay تجريبي منفصل له مفاتيحه الخاصة (راجع توثيق Tpay API). وتُستخدم فقط ما دام Sandbox mode مفعّلًا.

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

Sandbox Client ID: Open API Client ID لحساب بيئة الاختبار.

Sandbox Client secret: Open API Client secret لحساب بيئة الاختبار.

Sandbox Security code: رمز أمان الإشعارات لحساب بيئة الاختبار.

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

تؤكد Tpay المدفوعات إلى العنوان المعروض في هذا القسم. وهو بالشكل التالي: https://your-site/wc-api/wc_tp_payment/. يُرسل العنوان تلقائيًا مع كل معاملة؛ ولا يلزم ضبط أي شيء في لوحة Tpay سوى رمز الأمان. لا يُعلَّم الطلب كمدفوع إلا بعد إشعار بمجموع اختباري وتوقيع صالحين ومبلغ مطابق. وتعيد Tpay إرسال الإشعار حتى يقبله متجرك.

توقيع JWS: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). يتطلب امتداد OpenSSL في PHP والاتصال الصادر بـ HTTPS إلى secure.tpay.com. ويُتحقق دائمًا من المجموع الاختباري MD5. الافتراضي: مفعّل.

متقدم

Debug log: Log payment events. أحداث تقنية فقط (دون مفاتيح أو بيانات عملاء) في WooCommerce > Status > Logs، والمصدر wcp_tpay_payment. الافتراضي: معطّل.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. إلغاء التفعيل لا يحذف أي شيء. وتُحفظ الطلبات وبيانات الدفع الخاصة بها في Tpay دائمًا. الافتراضي: معطّل.

تُنقل إعدادات الإصدار 1.0 تلقائيًا: المفاتيح المستخدمة مع تفعيل وضع الاختبار تصبح مفاتيح Sandbox.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Tpay) ويقدّم الطلب. في وضع بيئة الاختبار تعرض صفحة الدفع Sandbox mode — no real money is charged. وينشئ الإضافة معاملة Tpay بإجمالي الطلب بعملة PLN مع الوصف Order # ورقم الطلب، ويمرر اسم العميل وبريده الإلكتروني وعنوانه ورقم هاتفه، ثم يُحوّل العميل إلى صفحة الدفع في Tpay. تُعرض الصفحة باللغة البولندية أو الإنجليزية أو الأوكرانية وفق لغة الموقع (وتُعرض الإنجليزية للغات الأخرى). وهناك يختار العميل BLIK أو تحويلًا مصرفيًا أو بطاقة أو طريقة أخرى مفعّلة في حسابك لدى Tpay، ويدفع.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Tpay. ترسل Tpay إشعارًا إلى متجرك؛ وتتحقق الإضافة من المجموع الاختباري MD5 باستخدام رمز الأمان وMerchant ID، ومن توقيع JWS (إذا كان مفعّلًا)، ثم من المبلغ: يجب أن يساوي المبلغ المطلوب لمحاولة الدفع هذه وإجمالي الطلب، ولا يجوز أن يكون المبلغ المدفوع أقل. وتُرفض الإشعارات التي لا تحمل مجموعًا اختباريًا أو توقيعًا صالحين.

بعد الدفع يعود العميل إلى صفحة استلام الطلب. والعودة وحدها لا تُعلّم الطلب كمدفوع. وإذا لم يصل الإشعار بعد، تطلب الصفحة من واجهة Tpay API حالة المعاملة (بحد أقصى مرة كل 10 ثوانٍ) وتطبّق الفحوصات نفسها. وما دام الدفع غير مؤكد، تعرض الصفحة Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: مع رابط Pay again. وعندما تُبلغ Tpay بفشل الدفع، تعرض الصفحة Tpay reports that the payment did not go through. You can try again: مع الرابط نفسه. وإذا فشل الدفع في صفحة Tpay، تُعيد Tpay العميل إلى صفحة Pay for order للطلب نفسه.

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

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

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

تعمل الإضافة بعملة PLN فقط. لا يوجد في المتجر اختيار للبنك أو لرمز BLIK (يختار العميل في صفحة Tpay)، ولا بطاقات محفوظة، ولا اشتراكات، ولا أزرار Apple Pay أو Google Pay في المتجر، ولا حاسبات تقسيط.

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

حالات الطلب

Pending payment: أُنشئت معاملة Tpay ولم يُؤكَّد الدفع بعد. وتعرض ملاحظة الطلب معاملة Tpay والبيئة.

Processing: أكدت Tpay الدفع. وهذه هي الحالة القياسية لـ WooCommerce بعد الدفع (تنتقل الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى «مكتمل»). وتوضح الملاحظة ما إذا كان الدفع قد أُكّد عبر الإشعار أو عبر فحص الحالة، وتعرض أي دفعة زائدة. ومعرّف المعاملة هو عنوان معاملة Tpay (TR-...).

On hold: وصلت دفعة، لكن مبلغها اختلف عن المبلغ المطلوب أو عن إجمالي الطلب، أو دُفع جزء منه فقط، أو كان الطلب قد أُلغي. وتشرح ملاحظة الطلب ذلك. تحقّق من الدفعة في لوحة Tpay ثم أكمل الطلب أو استرده.

Failed: أبلغت Tpay بفشل الدفع. ولا يُعلَّم بـ «فشل» إلا الطلب الذي كان بانتظار الدفع. ويمكن للعميل أن يدفع مرة أخرى.

إذا أبلغت Tpay بدفعة أخرى لطلب مدفوع أو مُسترد بالفعل، فلن يتغيّر الطلب؛ وستطلب منك ملاحظة استرداد الدفعة الزائدة من لوحة Tpay عند الحاجة. وتُضيف عملية الاسترجاع (chargeback) التي تبلغ عنها Tpay ملاحظة.

الاستردادات

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

لا تُضاف الاستردادات التي تُجرى في لوحة التاجر لدى Tpay إلى WooCommerce تلقائيًا.

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

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

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

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

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

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

لا يظهر Tpay عند الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن المفاتيح الأربعة للوضع الحالي مُدخلة (Merchant ID وClient ID وClient secret وSecurity code). وتحقّق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي PLN. وتعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات.

تم الدفع لكن الطلب ما زال في Pending payment: لم تتمكن Tpay من تسليم الإشعار أو رُفض. فعّل Debug log وراجع WooCommerce > Status > Logs ومصدر wcp_tpay_payment. من الأسباب الشائعة: رمز أمان أو Merchant ID خاطئ للوضع الحالي، أو عنوان إشعار محجوب (وضع الصيانة، جدار الحماية، المصادقة عبر HTTP)، أو خادم بلا OpenSSL أو بلا اتصال HTTPS صادر للتحقق من JWS. وتتحقق صفحة استلام الطلب من الحالة أيضًا عندما يعود العميل.

Notification answered FALSE - invalid checksum: إن Merchant ID أو رمز الأمان في الإعدادات لا يطابق حساب Tpay (الاختبار أو الإنتاج) الذي تنتمي إليه الدفعة.

Notification answered FALSE - invalid JWS signature: تعذّر التحقق من التوقيع، مثلًا لأن OpenSSL مفقود أو لأن شهادة Tpay تعذّر تنزيلها. أصلح الخادم أو أوقف JWS signature عند الحاجة؛ فالمجموع الاختباري MD5 ما زال يُتحقق منه.

الطلب في حالة On hold: اقرأ ملاحظة الطلب. المبلغ المدفوع لم يطابق الطلب، أو وصلت الدفعة لطلب مُلغى. تحقّق من الدفعة في لوحة Tpay ثم أكمل الطلب أو استرده.

رأى العميل الرسالة The Tpay payment could not be started: مفاتيح الوضع الحالي غير صحيحة، أو رفضت Tpay الطلب. يعرض السجل خطأ Tpay.

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

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

الإلغاء والحذف

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

Tpay علامة تجارية مسجّلة لصاحبها. هذه الإضافة غير تابعة لـ Tpay ولم تعتمدها Tpay.