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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم. يلزم امتداد 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). تأتي مفاتيح بيئة sandbox من حساب sandbox منفصل لدى Tpay.

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

التثبيت

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

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

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

4. أدخل مفاتيح Sandbox ومفاتيح Production (راجع Configuration). لا يلزم ضبط أي شيء في لوحة Tpay عدا رمز الأمان: يُرسل عنوان الإشعار مع كل معاملة.

5. فعّل Enable/Disable وانقر على Save. اختبر دفعة في وضع sandbox، ثم أوقف Sandbox mode لقبول المدفوعات الحقيقية.

عند التثبيت، تُنشئ الوحدة حالة الطلب Tpay payment on hold. تعرض PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها في Payment > Preferences؛ ويجب أن تبقى العملة PLN مسموحة للوحدة.

Configuration

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

Tpay

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

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

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

Sandbox mode: يستخدم بيئة sandbox لدى Tpay (مدفوعات تجريبية دون أموال حقيقية) مع مفاتيح Sandbox وعنوان openapi.sandbox.tpay.com. أوقفه لقبول المدفوعات الحقيقية بمفاتيح Production. تُرسل الاستردادات دائمًا إلى البيئة التي دُفع فيها الطلب. الافتراضي: مفعّل.

Production keys

أين تجدها: في لوحة التاجر لدى 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.

Sandbox keys

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

Sandbox Merchant ID: Merchant ID لحساب sandbox.

Sandbox Client ID: Open API Client ID لحساب sandbox.

Sandbox Client secret: Open API Client secret لحساب sandbox.

Sandbox Security code: رمز أمان الإشعارات لحساب sandbox.

لا تُعرض الأسرار المحفوظة (Client secret وSecurity code لكلتا البيئتين) مرة أخرى. يبقى الحقل فارغًا ويعرض Saved - leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved secrets: ضع علامة على سر ثم انقر على Save لإزالته. يحتفظ الحقل الفارغ بالقيمة المحفوظة.

Payment notifications

Notification URL: تؤكد Tpay المدفوعات على العنوان المعروض هنا. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_tpay_payment/notify، وقد يتضمن رمز لغة مثل /en/. يُرسل العنوان تلقائيًا مع كل معاملة؛ ولا يلزم ضبط شيء في لوحة Tpay عدا رمز الأمان. لا يُنشأ الطلب إلا بعد إشعار بمجموع اختباري وتوقيع صحيحين ومبلغ مطابق (أو بعد فحص حالة مطابق عندما يعود العميل). تكرر Tpay الإشعار حتى يقبله متجرك.

JWS signature: يتحقق أيضًا من X-JWS-Signature للإشعارات باستخدام شهادة Tpay (موصى به). يتطلب امتداد OpenSSL في PHP واتصال HTTPS صادرًا إلى secure.tpay.com. تُخزَّن الشهادات مؤقتًا ليوم واحد. يُتحقق دائمًا من المجموع الاختباري MD5. الافتراضي: مفعّل.

Advanced

Debug log: يسجّل أحداث الدفع: أحداث تقنية فقط (لا مفاتيح، ولا بيانات عملاء) في الملف logs/wc_tp_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. الافتراضي: معطّل. لا يُكتب أي شيء طالما هو معطّل، بما في ذلك الأخطاء؛ لذا فعّله قبل البحث عن سبب مشكلة.

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

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

صفحة الدفع

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

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

بعد الدفع يعود العميل إلى متجرك. مجرد العودة لا يُعلّم أي شيء كمدفوع. إذا لم يصل الإشعار بعد، تطلب الوحدة من واجهة Tpay API حالة المعاملة (مرة واحدة كحد أقصى كل 10 ثوانٍ) وتطبّق عليها الفحوصات نفسها. ما دام الدفع غير مؤكد، تعرض صفحة Payment confirmation الرسالة 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: مع زر Refresh وزر Pay again الذي يعيد إلى صفحة الدفع. ينشئ الإشعار الطلب فور وصوله.

إذا أبلغت Tpay بفشل الدفع، يعود العميل إلى صفحة الدفع مع الرسالة Tpay reports that the payment did not go through. Please try again or choose another payment method. إذا فشل الدفع في صفحة Tpay، تعيد Tpay العميل إلى صفحة الدفع. تبقى السلة محفوظة في الحالتين. إذا انتقل الطلب إلى حالة الانتظار، تعرض صفحة التأكيد الرسالة Your payment is being verified. We will contact you as soon as it is confirmed.

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

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

يعمل عنوان الإشعار حتى عندما يكون المتجر في وضع الصيانة، ولا يتأثر بقيود الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Tpay ولم يدفع، أو لم تؤكد Tpay الدفع بعد. توجد السلة فقط. لا ينشئ الدفع الفاشل طلبًا أيضًا.

Payment accepted: أكدت Tpay الدفع. يُسجَّل الدفع باستخدام عنوان معاملة Tpay (TR-...) كمعرّف للمعاملة. تبيّن ملاحظة ما إذا كان الدفع قد أُكد بالإشعار أو بفحص الحالة، والبيئة، وأي دفع زائد.

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

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

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

كتلة دفع Tpay

تعرض صفحة الطلب كتلة Tpay payment تتضمن عنوان معاملة Tpay ومعرّفها، ومرجع الدفع (CRC)، والبيئة (مع شارة Sandbox لمدفوعات sandbox)، وحالة الدفع وكيفية تأكيده، والمبلغ المدفوع، ومجموع الطلب والمبلغ المسترد، وسجل الاستردادات، وجميع Payment attempts الخاصة بالسلة، وPayment notes الخاصة بالطلب.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة (credit slips). لا ترسل أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب أي أموال عبر Tpay. ولا تُضاف عمليات الاسترداد التي تُجرى في لوحة التاجر لدى Tpay إلى PrestaShop تلقائيًا.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Tpay Payment هي أول كتلة في صفحة Modules > Module Manager > VibeFox Tpay Payment > Configure، فوق الإعدادات. الصق المفتاح في License key ثم انقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها السطر Product: presta-payment-tpay والرابط 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.

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

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

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

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

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

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

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

Notification answered FALSE - busy, retry later or FALSE - order could not be created: كانت السلة قيد المعالجة بطلب آخر في الوقت نفسه، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). تعيد Tpay الإشعار تلقائيًا. فعّل Debug log لمعرفة السبب.

يعرض عنوان الإشعار FALSE - POST only in the browser: هذا طبيعي. لا يقبل العنوان إلا الإشعارات الصادرة من Tpay.

الطلب في Tpay payment on hold: اقرأ الملاحظات في كتلة Tpay payment (راجع حالات الطلب)، وتحقّق من الدفعة في لوحة Tpay، ثم نفّذ الطلب أو استرد الدفعة.

رأى العميل The Tpay payment could not be started: مفاتيح الوضع الحالي خاطئة أو رفضت Tpay الطلب. فعّل Debug log؛ ويعرض السجل خطأ Tpay.

رأى العميل We could not match this payment to an order: لم ينتمِ رابط العودة إلى سلة العميل. إذا خُصم المبلغ من العميل، فسينشئ الإشعار الطلب مع ذلك؛ تحقّق من لوحة Tpay.

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

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

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

Tpay علامة تجارية مسجلة لمالكها. هذه الوحدة غير تابعة لـ Tpay ولا معتمدة من قبلها.