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

المتطلبات

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

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

عملة الطلب: AED أو BHD أو EGP أو EUR أو GBP أو JOD أو KWD أو OMR أو QAR أو SAR أو USD. بالنسبة إلى الطلبات بعملات أخرى، لا تظهر طريقة الدفع في صفحة الدفع.

وصول متجرك إلى الإنترنت: ترسل Tap نتيجة الدفع إلى webhook على متجرك، لذلك يجب أن يكون الموقع متاحًا من الإنترنت. يُرسل عنوان URL الخاص بالـ webhook مع كل دفعة، ولا حاجة إلى إعداد أي شيء في لوحة تحكم Tap.

حساب Tap: تحتاج إلى مفاتيح API من لوحة تحكم Tap (goSell، بيانات اعتماد API). تبدأ مفاتيح الاختبار بـ pk_test_ / sk_test_، وتبدأ المفاتيح الحية بـ pk_live_ / sk_live_. المفتاح السري مطلوب دائمًا؛ أما المفتاح القابل للنشر فيلزم فقط لنافذة الدفع المنبثقة. تُضبط طرق الدفع المعروضة (mada وKNET وBenefit وغيرها) والتحقق من نطاق Apple Pay في حساب Tap الخاص بك.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل مفاتيح Tap للاختبار والحية، واختر إجراء الدفع ونوع الدفع ولغة صفحة Tap (راجع Configuration).

5. فعّل Enable / Disable وانقر على Save. اختبر باستخدام بطاقات الاختبار الخاصة بـ Tap، ثم عطّل Test mode.

OpenCart 4

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

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

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

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

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

Configuration

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Tap Payments > Edit. تُعرض الأقسام على اليسار؛ ويحفظ الزر Save أسفل القائمة الصفحة كاملةً. وفوق الإعدادات، تعرض الصفحة الرسالة Test mode is on: payments use your Tap test keys and no real money is charged. أو Live mode: real payments are accepted. كما تحذّرك عندما تكون مفاتيح الوضع الحالي مفقودة (وعندئذ لا تظهر طريقة الدفع في صفحة الدفع)، وعندما لا تكون عملة المتجر الافتراضية مدعومة في Tap. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا يمكن أن يكون Title فارغًا أو أطول من 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا (القيم السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من 0 أو يساويه، ويجب أن تكون حالات الطلب موجودة؛ وإلا فلن يُحفظ أي شيء. لا يُحفظ المفتاح الذي يحمل بادئة خاطئة لحقله: تبقى القيمة السابقة، وتُحفظ الإعدادات الأخرى، وتظهر رسالة مثل Test secret key was not saved: a Tap key for this field starts with "sk_test_".. على سبيل المثال، يُرفض مفتاح حي في حقل اختبار.

Tap Payments

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

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

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

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

مفاتيح Tap API

اعثر على مفاتيحك في لوحة تحكم Tap (goSell، بيانات اعتماد API). يحتوي هذا القسم على رابط لوثائق المطورين في Tap.

Test mode: يستخدم مفاتيح الاختبار، ولا يُخصم أي مبلغ حقيقي. تستخدم المدفوعات وفحوص الحالة والتحصيل والاسترداد دائمًا مفاتيح الوضع الذي تمت فيه الدفعة، لذلك تُفحص الدفعة التجريبية وتُسترد بمفتاح الاختبار حتى بعد التحويل إلى الوضع الحي. الافتراضي: مفعّل. وطالما هو مفعّل، يرى العملاء Test mode: no real payment will be made. في خطوة Confirm Order وفي صفحة الدفع المنبثقة.

Test publishable key: يبدأ بـ pk_test_. مطلوب للنافذة المنبثقة.

Test secret key: يبدأ بـ sk_test_.

Live publishable key: يبدأ بـ pk_live_. مطلوب للنافذة المنبثقة.

Live secret key: يبدأ بـ sk_live_.

Merchant ID: اختياري. هو معرّف التاجر الخاص بك في Tap، ولا يُحتاج إليه إلا إذا طلبت منك Tap توجيه المدفوعات إلى حساب تاجر محدد.

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. لحذف مفتاح محفوظ، فعّل Clear the saved value أسفل الحقل وانقر على Save. المفاتيح القابلة للنشر عامة، وتبقى ظاهرة.

الدفع

Payment action: ما الذي يحدث للأموال عندما يدفع العميل.

Checkout type: المكان الذي يدفع فيه العميل.

Tap page language: لغة صفحة الدفع في Tap والنافذة المنبثقة: English (الافتراضي) أو Arabic.

إشعارات الدفع (webhook)

ترسل Tap نتيجة الدفع إلى عنوان URL المعروض في Webhook URL في هذا القسم. في OpenCart 3 يبدو على النحو التالي: https://your-store/index.php?route=extension/payment/wcp_tap_payment_gateway/webhook، وفي OpenCart 4: https://your-store/index.php?route=extension/wcp_tap_payment_gateway/payment/wcp_tap_payment_gateway.webhook، ويُبنى من عنوان الواجهة الأمامية لمتجر OpenCart الخاص بك. يُرسل عنوان URL مع كل دفعة، لذلك لا حاجة إلى إعداد أي شيء في لوحة تحكم Tap. فقط تأكد من أنه متاح من الإنترنت (وغير محجوب بجدار ناري أو مصادقة HTTP)؛ ولا يحجبه وضع الصيانة (وفي OpenCart 4 يتيح إجراء بدء تشغيل خاص بالإضافة مرور الـ webhook وعودة العميل). يُتحقق من كل إشعار بتوقيع hashstring (HMAC-SHA256 بالمفتاح السري للوضع الذي تمت فيه الدفعة). تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. حتى الإشعار الموقّع لا يُعتمد عليه بذاته: إذ تعيد الإضافة قراءة الدفعة من واجهة Tap API قبل أن تُعدّل الطلب. ومن دون webhook يعمل، لا يحصل الطلب على حالته إلا عندما يعود العميل إلى المتجر بعد الدفع.

الطلبات

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

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

Authorized Status: Authorize only: الأموال محجوزة ولم تُحصَّل بعد. الافتراضي: قيد الانتظار.

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

Voided Status: تُضبط بعد أن يحرّر Void Tap authorization الأموال المحجوزة. الافتراضي: ملغى.

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

متقدم

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

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

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

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

Export: يحفظ Download JSON الإعدادات كملف JSON. لا تُصدَّر المفاتيح السرية.

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

صفحة الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Tap Payments). وفي خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. ثم ينقر العميل على Confirm Order. وفي OpenCart 4 يختار العميل طريقة الدفع بالزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

Tap payment page: تنشئ الإضافة عملية خصم في Tap (أو تفويضًا في وضع Authorize only) بمبلغ إجمالي الطلب بعملة الطلب، مع الوصف Order # ورقم الطلب، وترسل العميل إلى صفحة الدفع الخاصة بـ Tap. يُمرَّر اسم العميل وبريده الإلكتروني ورقم هاتفه إلى Tap. هناك يختار العميل بطاقة أو mada أو KNET أو Benefit أو Apple Pay أو Google Pay (حسب ما هو مفعّل في حساب Tap الخاص بك) ويدفع. إذا تعذر على Tap بدء الدفع، يبقى العميل في خطوة Confirm Order مع الرسالة The Tap payment could not be started. Please try again or choose another payment method.، ويُسجَّل السبب في السجل.

Tap checkout popup: ينتقل العميل إلى صفحة Tap payment الخاصة بالإضافة، حيث يُفتح نموذج الدفع الخاص بـ Tap. تعرض الصفحة أيضًا الرابط Pay on the Tap payment page instead. إذا أُغلقت النافذة، يعيد الزر Pay now فتحها. إذا تعذّر تحميل النموذج، يُطلب من العميل استخدام صفحة الدفع الخاصة بـ Tap. وإعادة تحميل الصفحة تُعيد استخدام محاولة الدفع نفسها.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Tap الدفعة: تعيد الإضافة قراءة الدفعة من واجهة Tap API بمفتاح وضع الدفع، وتتحقق من أنها تخص هذا الطلب وأنها بدأت من صفحة دفعه، وتقارن المبلغ والعملة بالطلب. ولا يغيّر معرّف Tap الموجود في عنوان العودة الطلب وحده أبدًا. ويجري الـ webhook الفحص نفسه في الخلفية. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وفي OpenCart 4، عند عودة العميل من صفحة الدفع في Tap، تُعيد صفحة وسيطة قصيرة فتح عنوان العودة في متجرك، فتبقى السلة وتسجيل دخول العميل محفوظين. وبالنسبة إلى دفعة مفوّضة، تعرض الصفحة أيضًا Your payment has been authorized. We will process the order as soon as the payment is captured. وبالنسبة إلى دفعة قيد المراجعة، تعرض Your payment is being reviewed. We will contact you if anything else is needed.

إذا لم تؤكد Tap الدفعة بعد عند عودة العميل، تعرض صفحة Payment confirmation الرسالة We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. مع الزرين Check again وBack to checkout. ويضبط الـ webhook حالة الطلب فور وصوله.

إذا رُفضت الدفعة أو أُهملت أو أُلغيت، يبقى الطلب بلا حالة. يعود العميل إلى صفحة الدفع مع الرسالة Your payment was not completed. Please try again or choose another payment method. (ومع سبب من Tap عندما تقدّم سببًا). وتعرض الدفعة غير المكتملة الرسالة The payment was not completed. You can try again or choose another payment method. ويُحفظ السلة ويمكن دفعها مرة أخرى. وفي OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع.

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

يُبقي OpenCart 4 الطلب ضمن صفحة الدفع حتى تُعرض صفحة النجاح. بعد دفعة مرفوضة أو ملغاة، يبدأ Confirm Order التالي دفعة Tap جديدة للطلب نفسه. وإذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا ألغيته أو أُلغي تفويضه)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.، ويدفع Confirm Order التالي طلبًا جديدًا.

رسائل أخرى في صفحة الدفع: Tap does not accept payments in متبوعةً بالعملة، عندما لا تكون عملة الطلب مدعومة، وThe order total must be greater than zero to pay with Tap.

لا تحتوي الإضافة على بطاقات محفوظة أو ترميز أو اشتراكات أو حقول بطاقات مضمّنة في صفحة الدفع الخاصة بك. تُحصّل Capture Tap payment دائمًا إجمالي الطلب؛ ولا يُدعم التحصيل الجزئي.

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

حالات الطلب

لا توجد حالة (طلب مفقود): أُرسل العميل إلى Tap ولم يدفع، أو لم تؤكد Tap الدفعة بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا مع تعيين فلتر Order Status إلى Missing Orders. وفي OpenCart 4.1 قد تحمل مثل هذه الطلبات الحالة Voided أيضًا، وهي حالة يضبطها OpenCart عند عرض خطوة التأكيد من جديد؛ وتعدّها الإضافة طلبًا بلا حالة.

Paid Order Status (default Processing): أكدت Tap دفعة محصّلة. تعرض ملاحظة المبلغ، ومعرّف عملية الخصم في Tap (chg_...)، وطريقة الدفع، و(في وضع الاختبار) أن الدفعة تجريبية.

Authorized Status (default Pending): الدفعة مفوّضة فقط وتنتظر التحصيل أو الإلغاء.

On Hold (Review) Status (default Pending): المبلغ أو العملة المدفوعة لا يطابقان الطلب (Tap: amount/currency mismatch — manual review required.)، أو وصلت دفعة بعد إلغاء الطلب. تشرح الملاحظة ذلك. تحقق من الطلب وأنجزه، أو استرد الدفعة.

Voided Status (default Canceled): أُلغي التفويض باستخدام Void Tap authorization، فتحررت الأموال المحجوزة.

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

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

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

تبويب VibeFox Tap Payments

في Sales > Orders افتح طلبًا مدفوعًا عبر Tap. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Tap Payments الحقول Tap ID وAuthorization وCharge، وMode (تسمية Test للمدفوعات التجريبية)، وStatus الدفعة وطريقتها، وCharged / refunded، ونموذج الاسترداد، وسجل الاسترداد، وPayment attempts الخاصة بالطلب، وTap notes. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة؛ وتتطلب عمليات التحصيل والإلغاء والاسترداد صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups).

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

في وضع Authorize only، افتح الطلب المفوّض. تحصّل Capture Tap payment (مع إجمالي الطلب على الزر) إجمالي الطلب بعد السؤال Capture the reserved funds of this order through Tap?؛ ثم يحصل الطلب على Paid Order Status. يسأل Void Tap authorization Release the reserved funds? The order will be canceled.، ويحرر الأموال ويضبط Voided Status. يُمنع النقر الثاني على التحصيل خلال دقيقتين. إذا رفضت Tap الإجراء، يظهر خطأ في التبويب ويُضاف إلى الملاحظات. تتم تغييرات الحالة هذه من دون إخطار العميل ومن دون تغيير المخزون، كما في تغيير الحالة اليدوي. وإذا حُصّل التفويض مباشرة في لوحة تحكم Tap، يعلّم الـ webhook الطلب كمدفوع؛ ويجب إجراء استرداد هذه الدفعة في لوحة تحكم Tap.

الاسترداد

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

لا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Tap. ولا تظهر في OpenCart عمليات الاسترداد التي تتم في لوحة تحكم Tap.

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

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

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

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

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

لا تظهر Tap Payments في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على مفتاح سري (وعلى مفتاح قابل للنشر عندما يكون Checkout type هو النافذة المنبثقة). تحقق من أن عملة الطلب إحدى العملات AED أو BHD أو EGP أو EUR أو GBP أو JOD أو KWD أو OMR أو QAR أو SAR أو USD، ومن أن عنوان الدفع داخل Geo Zone المختارة، ومن أن الطلب يبلغ Total المضبوط في الإعدادات. تعرض صفحة الإعدادات تحذيرًا للمفاتيح المفقودة وعملة المتجر غير المدعومة.

تمت الدفعة لكن الطلب بقي بلا حالة: لا يستطيع الـ webhook الوصول إلى متجرك. تحقق من أن عنوان URL المعروض في Webhook URL متاح من الإنترنت (من دون جدار ناري أو مصادقة HTTP)، وفعّل Debug log لرؤية الردود في الحقل Log. يحصل الطلب أيضًا على حالته عندما يعود العميل من Tap.

Webhook answers invalid signature: لم يُوقَّع الإشعار بالمفتاح السري لوضع الدفعة. تحقق من المفاتيح السرية في الإعدادات.

Webhook answers gateway not configured: المفتاح السري لوضع الدفعة (الاختبار أو الحي) فارغ. أدخله.

Webhook answers verification failed: تعذّر الوصول إلى واجهة Tap API للتحقق من الدفعة. ستعيد Tap محاولة الـ webhook لاحقًا.

Webhook answers order not found: يشير الإشعار إلى طلب ليست له أي محاولة دفع من Tap في هذا المتجر.

Webhook answers busy, retry later or order could not be updated, retry later: كان الطلب يُؤكَّد من طلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. ستعيد Tap محاولة الـ webhook. انظر إلى الحقل Log لمعرفة السبب.

لا يُحفظ مفتاح: يجب أن يبدأ المفتاح ببادئة حقله: pk_test_ أو sk_test_ أو pk_live_ أو sk_live_.

يرى العميل The Tap payment could not be started: انظر إلى الحقل Log في صفحة الإضافة. يُسجَّل فيه المفتاح الخاطئ أو الطلب المرفوض.

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

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

الطلب في حالة المراجعة: اقرأ الملاحظات في تبويب VibeFox Tap Payments. لم يطابق المبلغ أو العملة المدفوعان الطلب، أو وصلت الدفعة بعد إلغاء الطلب.

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

للمطورين: تتيح أحداث OpenCart tap_p_charge_payload وtap_p_supported_currencies وtap_p_currency_decimals تغيير طلب الدفع والعملات المدعومة والمنازل العشرية للعملات.

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

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

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

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