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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر Activate.

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

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

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

6. فعّل Enable / Disable واحفظ. اختبر ببطاقات Tap التجريبية، ثم ألغِ تحديد Test mode.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Tap Payments. وتعرض الصفحة فوق الحقول الرسالة Test mode is on: payments use your Tap test keys and no real money is charged. طالما كان وضع الاختبار مفعّلًا. كما تُظهر تنبيهًا عندما تكون مفاتيح الوضع الحالي مفقودة (وعندها لا تظهر البوابة في صفحة الدفع)، وعندما لا تكون عملة المتجر مدعومة من Tap. وفي قائمة وسائل الدفع، يظهر Tap Payments على أنه بحاجة إلى إعداد حتى يحتوي الوضع الحالي على مفتاح سري (وللنافذة المنبثقة مفتاح قابل للنشر أيضًا).

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

عام

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

Title: اسم وسيلة الدفع الذي يظهر في صفحة الدفع. الافتراضي: Tap Payments.

Description: النص الذي يظهر أسفل وسيلة الدفع في صفحة الدفع. الافتراضي: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

مفاتيح Tap API

اعثر على مفاتيحك في لوحة تحكم Tap (goSell، بيانات اعتماد API). تبدأ مفاتيح الاختبار بـ pk_test_ / sk_test_، وتبدأ مفاتيح الإنتاج بـ pk_live_ / sk_live_.

Test mode: Use the test keys (no real money is charged). تستخدم المدفوعات وفحوصات الحالة والاستردادات دائمًا مفاتيح الوضع الذي تمت فيه الدفعة؛ لذلك تبقى الدفعة التجريبية تُفحص وتُسترد بمفتاح الاختبار حتى بعد التبديل إلى الإنتاج. الافتراضي: مفعّل.

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

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

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

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

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

الدفع

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

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

Tap page language: English (الافتراضي) أو Arabic.

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

ترسل Tap نتيجة الدفع إلى العنوان الظاهر في هذا القسم. وهو بالشكل https://your-site/wc-api/tap_p_webhook/. يُرسل هذا العنوان مع كل دفعة، لذلك لا يلزم إعداد أي شيء في لوحة تحكم Tap. فقط تأكد من أنه متاح من الإنترنت (وألا تحجبه جدار حماية أو وضع الصيانة أو المصادقة عبر HTTP). يُتحقق من كل إشعار بتوقيع hashstring (HMAC-SHA256 بالمفتاح السري لوضع الدفعة). وتُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. وحتى الإشعار الموقَّع لا يُعتمد بذاته: إذ تقرأ الإضافة الدفعة مرة أخرى من واجهة Tap البرمجية قبل تعديل الطلب. ومن دون webhook يعمل، لا يُحدَّث الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

متقدم

Debug log: Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). تُسجَّل الأخطاء دائمًا. ولا يتضمن السجل أي مفاتيح أو بيانات بطاقة أو عميل. الافتراضي: معطّل.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment records are kept). الافتراضي: معطّل.

صفحة الدفع

يختار العميل وسيلة الدفع (الافتراضية Tap Payments) ثم يقدّم الطلب. وفي وضع الاختبار تعرض صفحة الدفع Test mode: no real payment will be made.

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

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

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

إذا لم تُؤكَّد الدفعة بعد، تعرض صفحة استلام الطلب الرسالة 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.. وبالنسبة للدفعة المفوَّضة تعرض Your payment has been authorized. We will process the order as soon as the payment is captured.

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

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Tap ولم يدفع بعد، أو لم تؤكد Tap الدفعة بعد.

Processing: أكدت Tap دفعة محصّلة. وهذه هي حالة WooCommerce القياسية بعد الدفع (الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط تصبح مكتملة مباشرة). وتعرض ملاحظة الطلب المبلغ ومعرّف خصم Tap (chg_...) وطريقة الدفع، وفي وضع الاختبار تُظهر أن الدفعة تجريبية. ومعرّف المعاملة هو معرّف خصم Tap.

On hold: الدفعة مفوَّضة فقط وتنتظر التحصيل؛ أو أن المبلغ المدفوع أو العملة لم يطابقا الطلب (Tap: amount/currency mismatch — manual review required.)؛ أو وصلت دفعة بعد إلغاء الطلب. وتوضح ملاحظة الطلب ذلك.

Failed: رُفضت الدفعة أو تُخلّي عنها العميل أو أُلغيت أو انتهت مهلتها. ولا يُعلَّم بأنه فاشل إلا الطلب الذي ما زال بانتظار الدفع؛ ولا تغيّر المحاولة الفاشلة أبدًا طلبًا مدفوعًا أو مفوَّضًا أو ملغى. ويمكن للعميل الدفع مرة أخرى.

Cancelled: أُلغي التفويض باستخدام Void Tap authorization، فأُفرجت الأموال المحجوزة.

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

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

في وضع Authorize only، افتح الطلب المعلّق واختر من Order actions: Capture Tap payment يحصّل إجمالي الطلب، فيصبح الطلب مدفوعًا بعد ذلك. وVoid Tap authorization يحرّر الأموال ويلغي الطلب. وإذا رفضت Tap الإجراء، يظهر خطأ ويُضاف إلى ملاحظات الطلب. وإذا حُصّل التفويض مباشرة من لوحة تحكم Tap، فإن الـ webhook يعلّم الطلب كمدفوع؛ ويجب إجراء استردادات هذه الدفعة من لوحة تحكم Tap.

الاستردادات

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

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

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

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

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

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

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

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

تمت الدفعة لكن الطلب ما زال Pending payment: لا يستطيع الـ webhook الوصول إلى موقعك. تحقّق من أن العنوان الظاهر في الإعدادات (/wc-api/tap_p_webhook/) متاح من الإنترنت (من دون جدار حماية أو وضع صيانة أو مصادقة HTTP)، وراجع WooCommerce > Status > Logs، المصدر wcp_tap_payment_gateway. ويُحدَّث الطلب أيضًا عندما يعود العميل من Tap.

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

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

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

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

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

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

خطافات المطورين: المرشحات tap_p_supported_currencies وtap_p_currency_decimals وtap_p_charge_payload وtap_p_icon وtap_p_checkout_sdk_url وtap_p_payment_page_hosts متاحة.

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

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

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

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