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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

عملة المتجر: 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. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند اكتمال الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Tap Payments في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالتين للطلب، هما Tap payment authorized وTap payment on hold. تُتيح PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

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

عند الحفظ، لا يُحفظ المفتاح الذي يحمل بادئة خاطئة لحقله: تبقى القيمة السابقة، وتُحفظ بقية الإعدادات، وتظهر رسالة مثل Test secret key was not saved: a Tap key for this field starts with "sk_test_".. فمثلًا يُرفض مفتاح الإنتاج إذا أُدخل في حقل الاختبار. ولا يُقبل Title فارغ: تعرض الصفحة Enter a title for the payment method. ولا يُحفظ شيء.

Tap Payments

يعرض عنوان القسم أيضًا TEST أو LIVE للوضع الحالي.

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

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 saved secrets: حدّد مفتاحًا سريًا وانقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع

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

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

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

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

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

متقدم

Debug log: يسجّل أحداث الدفع في logs/tap_p_debug.log.php داخل مجلد الوحدة. ولا يمكن قراءة الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا؛ فعّل هذا الخيار لتسجيل كل حدث دفع أيضًا. ولا يحتوي السجل أبدًا على مفاتيح أو بيانات بطاقات أو عملاء. الافتراضي: مُوقَف.

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

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

إتمام الطلب

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Tap Payments) ويؤكد الطلب. لا يوجد طلب في هذه المرحلة بعد.

Tap payment page: تُنشئ الوحدة عملية تحصيل في Tap (أو تفويضًا في وضع Authorize only) بإجمالي السلة بعملة السلة، مع الوصف Cart # ورقم السلة، وترسل العميل إلى صفحة دفع Tap. تُمرَّر اسم العميل وبريده الإلكتروني ورقم هاتفه إلى 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 payment في الوحدة، حيث تُفتح استمارة دفع Tap. تعرض الصفحة أيضًا الرابط Pay on the Tap payment page instead. وإذا أُغلقت النافذة، يعيد زر Pay now فتحها. وإذا تعذّر تحميل الاستمارة، يُطلب من العميل استخدام صفحة دفع Tap. وإعادة تحميل الصفحة تُعيد استخدام محاولة الدفع نفسها.

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Tap ذلك: تقرأ الوحدة الدفعة من واجهة Tap البرمجية باستخدام مفتاح وضع الدفعة، وتتحقق من أنها تشير إلى هذه السلة وأن إتمام الطلب الخاص بها هو من بدأها، وتقارن المبلغ والعملة بالسلة. ولا ينشئ معرّف Tap الموجود في عنوان العودة وحده طلبًا أبدًا. ويجري الـ webhook الفحص نفسه في الخلفية. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية. وفي حالة الدفعة المفوَّضة تعرض الصفحة 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. وتبقى السلة محفوظة ويمكن دفعها مرة أخرى.

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

يعمل الـ webhook أثناء وضع الصيانة في المتجر، ولا يتأثر بقيود الدول في متجرك.

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

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

حالات الطلب

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

Payment accepted: أكدت Tap دفعة محصّلة. تُسجَّل الدفعة بمعرّف عملية التحصيل في Tap (chg_...) كمعرّف معاملة، وتعرض ملاحظة المبلغ ومعرّف التحصيل وطريقة الدفع، وأنها دفعة اختبار (في وضع الاختبار).

Tap payment authorized: الدفعة مفوَّضة فقط، وتنتظر التحصيل أو الإلغاء.

Tap payment on hold: المبلغ المدفوع أو العملة كانا مختلفين عن السلة (Tap: amount/currency mismatch — manual review required.)، أو وصلت دفعة بعد إلغاء الطلب. وتوضح الملاحظة السبب. تحقق من الطلب وأكمله، أو استرد الدفعة.

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

Refunded: استُرد المبلغ كاملًا من خلال الوحدة.

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

كتلة الدفع في Tap

تعرض صفحة الطلب كتلة Tap payment تتضمن معرّف Tap والتفويض والتحصيل، والوضع (شارة Test mode لدفعات الاختبار)، وحالة الدفع وطريقته، وCharged / refunded، وسجل الاستردادات، ومحاولات الدفع للسلة، وPayment notes الخاصة بالطلب. وتعمل أزرار الكتلة في صفحة الطلب نفسها؛ وتحتاج إلى صلاحية تعديل الطلبات، لا إلى الوصول إلى إعدادات الوحدة.

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

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

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة. ولا تعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر Tap. ولا تظهر الاستردادات التي تتم من لوحة Tap في PrestaShop.

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

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

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

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

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

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

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

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

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

Webhook answers verification failed: تعذّر الوصول إلى واجهة Tap البرمجية للتحقق من الدفعة. ستعيد 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 في صفحة الوحدة. يُسجَّل هناك مفتاح خاطئ أو طلب مرفوض.

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

الطلب في حالة Tap payment on hold: اقرأ الملاحظات في كتلة Tap payment. المبلغ المدفوع أو العملة لم يطابقا السلة، أو وصلت الدفعة بعد إلغاء الطلب.

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

الخطافات (hooks) للمطوّرين: تتيح الخطافات actionWcpTapChargePayload وactionWcpTapSupportedCurrencies وactionWcpTapCurrencyDecimals للمطوّر تعديل طلب الدفع والعملات المدعومة وخانات العشرية للعملات.

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

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

Tap Payments علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Tap Payments ولا معتمدة منها.