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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث. لفحص توقيع JWS للإشعارات تحتاج إلى إضافة OpenSSL وإلى اتصال HTTPS صادر إلى secure.tpay.com.

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

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

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

يبدأ التثبيت الجديد بطريقة الدفع معطّلة ووضع sandbox مفعّلًا.

Configuration

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

عند الحفظ، لا يمكن أن يكون Title فارغًا أو أطول من 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا (القيم السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من 0 أو يساويه، ويجب أن تكون حالات الطلب موجودة؛ وإلا فلن يُحفظ أي شيء. المفاتيح الناقصة لا تمنع الحفظ. تُزال المسافات الملصوقة مع Merchant ID أو Client ID، وتُقص المسافات في بداية القيم السرية ونهايتها.

Tpay

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

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

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

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

Sort Order: ترتيب Tpay بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا (القيم السالبة مسموحة).

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

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

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

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

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

Client ID: معرّف Client ID الخاص بـ Open API.

Client secret: المفتاح السري Client secret الخاص بـ Open API.

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

مفاتيح sandbox

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

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

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

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

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

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

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

Notification URL: تؤكد Tpay المدفوعات إلى العنوان المعروض هنا. في OpenCart 3 يبدو على النحو التالي: https://your-store/index.php?route=extension/payment/wcp_tpay_payment/notify، وفي OpenCart 4 يبدو على النحو التالي: https://your-store/index.php?route=extension/wcp_tpay_payment/payment/wcp_tpay_payment.notify، ويُبنى من عنوان الواجهة الأمامية لمتجر OpenCart الخاص بك. يُرسل العنوان تلقائيًا مع كل معاملة؛ ولا تحتاج إلى ضبط أي شيء في لوحة Tpay سوى رمز الأمان. لا يحصل الطلب على حالته إلا بعد إشعار بمجموع اختباري وتوقيع صالحين ومبلغ متطابق (أو بعد فحص حالة متطابق عندما يعود العميل). تكرر Tpay الإشعار حتى يقبله متجرك. ولا يحجب وضع الصيانة هذا العنوان (في OpenCart 4 تضيف الإضافة إجراء بدء تشغيل للإشعارات وعودة العميل).

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

الطلبات

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

Paid Order Status: الحالة بعد دفعة مؤكَّدة. الافتراضي: قيد المعالجة.

On Hold (Review) Status: الدفعة تحتاج إلى مراجعتك (راجع حالات الطلب). الافتراضي: قيد الانتظار، لأن OpenCart لا يحتوي على حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Cancelled Order Status: لا تضبط الإضافة هذه الحالة أبدًا. وتضع الدفعة لطلب في هذه الحالة الطلب في المراجعة بدلًا من إعادة فتحه بصمت. الافتراضي: ملغى.

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

متقدم

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

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

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

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

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

Import: الصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى Client secrets وSecurity codes المحفوظة كما هي.

صفحة الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Tpay). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to the secure Tpay page to complete the payment. وفي وضع sandbox يُعرض أيضًا Sandbox mode - no real money is charged. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

عندما ينقر العميل على Confirm Order، تنشئ الإضافة معاملة Tpay بإجمالي الطلب بالـ PLN، مع الوصف Order # ورقم الطلب، وتمرّر اسم العميل وبريده الإلكتروني وعنوان الدفع ورقم هاتفه، وترسله إلى صفحة الدفع الخاصة بـ Tpay. تُعرض الصفحة بالبولندية أو الإنجليزية أو الأوكرانية حسب لغة الطلب (وتحصل اللغات الأخرى على الإنجليزية). وهناك يختار العميل BLIK أو تحويلًا مصرفيًا أو بطاقة أو طريقة أخرى مفعّلة في حساب Tpay الخاص بك، ويدفع.

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

بعد الدفع يعود العميل إلى متجرك. ولا تُعلّم العودة وحدها أي شيء كمدفوع. إذا لم يصل الإشعار بعد، تطلب الإضافة من واجهة Tpay API حالة المعاملة (مرة كل 10 ثوانٍ على الأكثر) وتطبّق الفحوص نفسها. وعندما تُؤكَّد الدفعة، يرى العميل صفحة نجاح الطلب في OpenCart. وطالما لم تُؤكَّد، تعرض صفحة 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 الذي يعيد إلى صفحة الدفع. ويضبط الإشعار حالة الطلب فور وصوله. وإذا دخل الطلب المراجعة، تعرض صفحة النجاح أيضًا Your payment is being verified. We will contact you as soon as it is confirmed.

إذا أبلغت Tpay بفشل الدفعة، يعود العميل إلى صفحة الدفع مع الرسالة Tpay reports that the payment did not go through. Please try again or choose another payment method. وإذا فشلت الدفعة في صفحة Tpay، تعيد Tpay العميل إلى صفحة الدفع. وتُحفظ السلة في الحالتين.

ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيحتفظ بطلب واحد لصفحة الدفع ويحدّثه، فيبدأ Pay again محاولة دفع جديدة للطلب نفسه. ولكل محاولة دفع مرجع خاص بها. وعندما يدفع العميل مرة أخرى، تُلغى في Tpay معاملات Tpay السابقة غير المدفوعة لهذا الطلب ولطلبات أخرى من السلة نفسها؛ لكن الدفعة التي اكتملت بالفعل عبر رابط سابق تظل مقبولة. وإذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل، ينتقل العميل إلى صفحة النجاح بدلًا من بدء دفعة جديدة.

في OpenCart 4، إذا أغلق المتجر طلب الدفع في هذه الأثناء، أو كان الطلب مدفوعًا بالفعل لكن السلة تغيّرت منذ ذلك، بما في ذلك تغيير الكمية، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order.. أما الطلب الذي ألغاه المتجر قبل أي دفعة، فالرسالة هي Order #… was cancelled by the store before the payment was completed. No Tpay payment was received for it. Please place a new order or contact us.. ويدفع Confirm Order التالي طلبًا جديدًا. وفي OpenCart 4 تظهر هذه الرسائل، ورسالة الدفع الفاشل، والرسالة We could not match this payment to an order. If you were charged, please contact us. فوق صفحة الدفع.

إذا تعذّر على Tpay بدء الدفع، يبقى العميل في خطوة Confirm Order مع الرسالة The Tpay payment could not be started. Please try again or choose another payment method. ويُسجَّل السبب في السجل (عندما يكون Debug log مفعّلًا). رسائل أخرى: Tpay accepts payments in Polish złoty (PLN) only. Please choose another payment method. وThe order total must be greater than zero.

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

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

حالات الطلب

لا توجد حالة (طلب مفقود): أُرسل العميل إلى Tpay ولم يدفع، أو لم تؤكد Tpay الدفعة بعد. كما أن الدفعة الفاشلة تترك الطلب بلا حالة. وفي Sales > Orders لا تظهر هذه الطلبات إلا مع تعيين فلتر Order Status إلى Missing Orders.

Paid Order Status (default Processing): أكدت Tpay الدفعة. تعرض ملاحظة عنوان معاملة Tpay (TR-...)، والمبلغ المدفوع، وما إذا كانت التأكيد جاء بالإشعار أو بفحص الحالة، والبيئة، وأي دفعة زائدة.

On Hold (Review) Status (default Pending): وصلت دفعة، لكن عملة الطلب ليست PLN، أو اختلف مبلغها عن المبلغ المطلوب أو عن إجمالي الطلب (مثلًا تغيّر الطلب بعد بدء الدفع)، أو دُفع جزء فقط، أو وصلت الدفعة لطلب في Cancelled Order Status. تشرح الملاحظة ذلك. تحقّق من الدفعة في لوحة Tpay ثم أنجز الطلب أو استرد الدفعة. وإذا دفع العميل المبلغ الصحيح في محاولة أخرى، ينتقل الطلب إلى Paid Order Status.

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

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

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

تبويب VibeFox Tpay Payment

في Sales > Orders افتح طلبًا مدفوعًا عبر Tpay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Tpay Payment عنوان Tpay transaction وTransaction ID، ومرجع الدفع (CRC)، وEnvironment (تسمية Sandbox للمدفوعات التجريبية)، وStatus الدفعة وكيفية تأكيدها، والمبلغ المدفوع، وOrder total / refunded، وRefundable (paid through Tpay) عندما يختلف عن إجمالي الطلب، ونموذج الاسترداد، وسجل الاسترداد، وPayment attempts الخاصة بالطلب (مع link cancelled للروابط الملغاة)، وPayment notes. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

في التبويب، أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional, kept in the note)، ثم انقر على Refund via Tpay. أكّد السؤال Refund this amount through Tpay? This cannot be undone. يُدعم الاسترداد الكامل والجزئي للطلبات التي وصلتها دفعة عبر Tpay، بما في ذلك الطلبات قيد المراجعة. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يمكنك الاسترداد حتى المبلغ الذي حصّلته معاملة Tpay التي أجرت الدفع، وبحد أقصى إجمالي الطلب. يُرسل الاسترداد إلى البيئة (sandbox أو الإنتاج) التي دُفع فيها الطلب، لذلك يجب ضبط مفاتيح تلك البيئة. ولا يُعتبر الاسترداد منجزًا إلا عندما تؤكده Tpay؛ فالاسترداد الذي ترفضه Tpay أو لا تؤكده يظهر كخطأ ولا يُسجَّل. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع السبب الذي أدخلته (لا يُرسل السبب إلى Tpay). ويؤدي استرداد كامل المبلغ القابل للاسترداد إلى ضبط الطلب على Refunded Status من دون إخطار العميل ومن دون إعادة المنتجات إلى المخزون، كتغيير الحالة اليدوي. ولا يغيّر الاسترداد الجزئي الحالة.

لا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Tpay. ولا تُضاف عمليات الاسترداد التي تتم في لوحة التاجر في Tpay إلى OpenCart تلقائيًا.

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

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

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

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

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

لا تظهر Tpay في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفاتيح الأربعة للوضع الحالي مُدخلة (Merchant ID وClient ID وClient secret وSecurity code). تحقق من أن العميل يدفع بالـ PLN، ومن أن عنوان الدفع داخل Geo Zone المختارة، ومن أن الطلب يبلغ Total المضبوط في الإعدادات. تعرض صفحة الإعدادات تحذيرًا للمفاتيح المفقودة وعملة متجر غير 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 أو FALSE - order could not be updated: كانت السلة تُعالج من طلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. وتكرر Tpay الإشعار تلقائيًا. فعّل Debug log لرؤية السبب.

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

الطلب في حالة المراجعة: اقرأ الملاحظات في تبويب VibeFox Tpay Payment (راجع حالات الطلب)، وتحقق من الدفعة في لوحة Tpay، ثم أنجز الطلب أو استرد الدفعة.

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

رأى العميل This payment method is not available: لم تعد جلسة الدفع تطابق الطلب، أو عُطّلت طريقة الدفع أو فقدت مفاتيحها في الأثناء. يعيد العميل تحميل صفحة الدفع.

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

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

للمطورين: قبل إنشاء معاملة Tpay، تُطلق الإضافة حدث OpenCart المسمى wc_tp_transaction_data مع بيانات المعاملة والطلب والبيئة.

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

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

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

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