VibeFox Viva Wallet for PrestaShop — المساعدة

المتطلبات

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

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

حساب Viva: حساب تاجر لدى Viva. يمكنك استخدام حساب تجريبي (demo.vivapayments.com) للاختبارات، وحساب حقيقي (www.vivapayments.com) للمدفوعات الفعلية. لكل حساب بيانات اعتماد خاصة به. للمدفوعات تحتاج إلى بيانات اعتماد Smart Checkout (Client ID وClient Secret) وSource Code لمصدر الدفع. أما Merchant ID وAPI Key فاختياريان: يُستخدمان فقط للإجابة على التحقق من عنوان URL الخاص بـ webhook من Viva.

العملة: EUR أو GBP أو PLN أو RON أو BGN أو CZK أو HUF أو DKK أو SEK أو NOK أو CHF. وبالعملات الأخرى تُخفى طريقة الدفع عند إتمام الشراء.

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

التثبيت

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

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

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

4. أدخل بيانات اعتماد حساب Viva التجريبي و/أو الحقيقي، ثم اضبط مصدر الدفع وwebhook في حسابك لدى Viva (انظر الإعدادات).

5. فعّل Enable/Disable وانقر على Save. نفّذ دفعة تجريبية ببطاقة Viva التجريبية والوضع Test Mode مفعّل، ثم أوقف Test Mode للانتقال إلى الوضع الفعلي.

عند التثبيت، تنشئ الوحدة حالة الطلب Viva Wallet payment on hold. تُعرض الوحدة للدول المفعّلة وقت التثبيت. يمكنك تغيير العملات والدول ومجموعات العملاء من Payment > Preferences، ويمكن إضافة دول جديدة هناك لاحقًا.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذّرك الصفحة إذا لم يكن في الوضع الحالي Client ID أو Client Secret أو Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered.، أو Live في الوضع الحقيقي)، وإذا لم تكن العملة الافتراضية للمتجر مدعومة. وعند تفعيل وضع الاختبار تعرض Test mode is on: payments go to the Viva demo environment. يؤدي حفظ الإعدادات إلى حذف رموز الوصول المخزنة مؤقتًا لدى Viva، فتُستخدم بيانات الاعتماد الجديدة فورًا.

Viva Wallet

Enable/Disable: Enable Viva Wallet payment gateway يفعّل طريقة الدفع أو يوقفها. الافتراضي: معطّل.

Title: اسم طريقة الدفع الذي يراه العملاء عند إتمام الشراء. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Viva Wallet. مطلوب: لا يُحفظ العنوان الفارغ، وتعرض الصفحة Enter a title for the payment method.

Description: النص الذي يظهر أسفل طريقة الدفع عند إتمام الشراء. الافتراضي: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: يستخدم بيئة Viva التجريبية (demo.vivapayments.com). تستخدم المدفوعات الجديدة واستدعاءات API بيانات اعتماد الحساب التجريبي. لا يُخصم أي مبلغ حقيقي، ويرى العملاء عند إتمام الشراء (Test mode: use Viva demo cards, no real money is charged.) الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية عبر الحساب الحقيقي. وتظل المدفوعات التي تمت من قبل تُتحقَّق وتُسترد في البيئة التي تمت فيها.

الحساب التجريبي (وضع الاختبار) والحساب الحقيقي

لكلا القسمين الحقول نفسها: مجموعة للحساب التجريبي وأخرى للحساب الحقيقي. في حسابك لدى Viva افتح Settings > API Access وانسخ بيانات اعتماد Smart Checkout (Client ID وClient Secret) وMerchant ID وAPI Key. يوجد Source Code في Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): معرّف OAuth 2.0 Client ID الخاص بـ Smart Checkout للحساب. مطلوب للمدفوعات.

Client Secret (Demo) / Client Secret (Live): سر OAuth 2.0 Client Secret الخاص بـ Smart Checkout للحساب. مطلوب للمدفوعات.

Source Code (Demo) / Source Code (Live): الرمز المكوّن من 4 أرقام لمصدر دفع الحساب. يجب أن يشير Success URL وFailure URL الخاصان به إلى هذا المتجر (انظر أدناه). مطلوب للمدفوعات.

Merchant ID (Demo) / Merchant ID (Live): اختياري. يُستخدم فقط للإجابة على التحقق من عنوان URL الخاص بـ webhook من Viva.

API Key (Demo) / API Key (Live): اختياري. يُستخدم فقط للإجابة على التحقق من عنوان URL الخاص بـ webhook من Viva.

لا تُعرض مرة أخرى الأسرار Client Secret ومفاتيح API المحفوظة. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

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

عناوين الرجوع وwebhook

Addresses for the Viva account: يعرض هذا الحقل عناوين المتجر الثلاثة التي يجب إدخالها في حساب Viva. مع الروابط الودية تبدو هكذا: https://your-shop/module/wcp_viva_gateway/success وhttps://your-shop/module/wcp_viva_gateway/fail وhttps://your-shop/module/wcp_viva_gateway/webhook، وربما مع رمز لغة مثل /en/. انسخها تمامًا كما تعرضها الإعدادات.

Payment source: في Sales > Online payments > Websites / apps أنشئ مصدر دفع لنطاق متجرك، في كل حساب تستخدمه. وفي Success URL وFailure URL أدخل المسار الذي يأتي بعد النطاق في عنواني النجاح والفشل.

Webhook: في Settings > API Access > Webhooks أضف عنوان webhook لهذه الأحداث:

يتحقق Viva من العنوان قبل حفظه. تجيب الوحدة بمفتاح التحقق الخاص بحسابك: فهي تجلبه باستخدام Merchant ID وAPI Key للوضع الحالي، أو تستخدم المفتاح المدخل أدناه. تؤكد webhooks المدفوعات حتى عندما يغلق العميل المتصفح. ولا تُوقَّع webhooks الخاصة بـ Viva، لذا لا تثق الوحدة بالـ webhook وحده أبدًا: يُتحقق من كل دفعة عبر واجهة Viva API قبل إنشاء الطلب. وبدون webhook لا يُنشأ الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

Webhook Verification Key: اختياري. اتركه فارغًا لجلب المفتاح تلقائيًا باستخدام Merchant ID وAPI Key للوضع الحالي، أو الصق هنا مفتاح التحقق من حسابك لدى Viva.

الإعدادات المتقدمة

Order Status After Payment: حالة الطلب التي تُعيَّن بعد الدفع الناجح. تُعيَّن الحالة فورًا دون تغيير ثانٍ للحالة.

Brand Color: رمز لون HEX مكوّن من 6 خانات لصفحة الدفع لدى Viva، مثل 0000ff. تُحذف علامة # في البداية. اتركه فارغًا للون الافتراضي. أي قيمة أخرى لا تُحفظ: تعرض الصفحة Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.

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

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات وسجلات الوحدة. لا تُحذف الطلبات وبيانات الدفع الخاصة بها (محاولات الدفع لدى Viva، والاستردادات، وحالة الطلب) أبدًا. الافتراضي: معطّل.

إتمام الشراء

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Viva Wallet) ويرى الملاحظة You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). بعد التأكيد تنشئ الوحدة طلب دفع في Viva بإجمالي السلة وبعملة السلة، وتُرسل العميل إلى صفحة Viva Smart Checkout. هناك يدفع العميل بإحدى الطرق المفعّلة في حسابك لدى Viva. تُمرَّر إلى Viva بيانات العميل: البريد الإلكتروني والاسم والهاتف والدولة، وتُفتح الصفحة بلغة السلة إذا كانت Viva تدعمها. يظهر الدفع في Viva باسم Cart # ورقم السلة واسم متجرك. تنتهي صلاحية طلب الدفع في Viva بعد 30 دقيقة. ولا يوجد طلب في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Viva: تعيد الوحدة قراءة المعاملة من واجهة Viva API عند عودة العميل وعبر webhook. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية. وإذا لم يُؤكَّد الدفع بعد، تعرض صفحة Payment confirmation الرسالة We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. مع الزرين Check again وBack to checkout؛ وينشئ webhook الطلب فور تأكيد Viva للدفع.

إذا فشل الدفع أو ألغى العميل في صفحة Viva، فلا يُنشأ أي طلب وتُحفظ السلة. يعود العميل إلى إتمام الشراء مع الرسالة The Viva Wallet payment was not completed. Please try again or choose another payment method. أو The Viva Wallet payment was cancelled. You can try again or choose another payment method. ويمكنه الدفع مرة أخرى.

إذا تعذّر على Viva بدء الدفع، يبقى العميل عند إتمام الشراء مع الرسالة Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (بيانات اعتماد مفقودة أو خاطئة)، أو We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. ويُكتب السبب التقني في السجل.

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

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

تقبل الوحدة المدفوعات لمرة واحدة فقط، وتُحصَّل فورًا في صفحة Viva. لا تتضمن التفويض المسبق والتحصيل، أو الدفع بالتقسيط، أو البطاقات المحفوظة، أو الاشتراكات، أو Viva Native Checkout (حقول البطاقة في صفحتك الخاصة)، أو أجهزة نقاط البيع (POS). عندما يبدأ العميل محاولة جديدة، لا يُلغى طلب الدفع القديم غير المدفوع في Viva؛ بل تُنهي Viva صلاحيته بعد 30 دقيقة.

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Viva ولم يدفع، أو فشل الدفع أو أُلغي، أو لم تُنهِ Viva الدفع بعد. لا توجد إلا السلة، ويمكن للعميل الدفع مرة أخرى.

Payment accepted أو Delivered أو Viva Wallet payment on hold: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. يُسجَّل الدفع برقم معاملة Viva، وتعرض ملاحظة المبلغ والمعاملة ورمز طلب Viva والبيئة (تجريبية أو حقيقية) وكيفية التأكيد (webhook أو عودة العميل).

Viva Wallet payment on hold بعد عدم تطابق: أبلغت Viva عن مبلغ أو عملة يختلفان عن إجمالي السلة، مثل تعديل السلة بعد أن بدأ العميل الدفع. يُنشأ الطلب دون تسجيل دفعة، وتوضح الملاحظة Viva Wallet payment held for review السبب. يرى العميل صفحة تأكيد الطلب القياسية دون وعد بتأكيد من Viva. قارن الدفعة في لوحة Viva بالطلب، ثم نفّذ الطلب أو استرد المبلغ يدويًا. إذا وصلت لاحقًا دفعة مطابقة للسلة نفسها، ينتقل الطلب إلى حالة مدفوع.

لا تغيّر الدفعة التي تصل لطلب ملغى أو مسترد حالة الطلب؛ وتطلب منك ملاحظة استعادة الطلب أو استرداد الدفعة من لوحة Viva. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، لا يتغير الطلب؛ وتطلب منك ملاحظة استرداد الدفعة المكررة من لوحة Viva.

كتلة Viva Wallet payment

تعرض صفحة الطلب كتلة Viva Wallet payment تضم رمز طلب Viva، ورقم المعاملة، والبيئة وSource Code، وحالة Viva، والمبالغ المدفوعة والمستردة، وشارة Demo للمدفوعات التجريبية، وسجل الاستردادات، ومحاولات دفع السلة (عند وجود أكثر من محاولة)، وViva Wallet notes الخاصة بالطلب.

الاستردادات

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

لا تُنشئ الوحدة إشعارات ائتمان. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر Viva. ولا تُستورد الاستردادات التي تُجرى من لوحة تحكم Viva. حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

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

لا يظهر Viva Wallet عند إتمام الشراء: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على Client ID وClient Secret وSource Code (حقول Demo في وضع الاختبار، وحقول Live في الوضع الحقيقي). يجب أن تكون عملة السلة واحدة من EUR أو GBP أو PLN أو RON أو BGN أو CZK أو HUF أو DKK أو SEK أو NOK أو CHF. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل. وتعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد.

تمت عملية الدفع، لكن لم يُنشأ أي طلب: webhook لا يعمل. في Viva تحقّق من وجود webhook في الحساب الذي تستخدمه (تجريبي أو حقيقي)، ومن أن عنوانه مطابق تمامًا للعنوان الظاهر في الإعدادات، ومن تحديد Transaction Payment Created. وتحقّق من أن Client ID وClient Secret لحساب تلك الدفعة ما زالا مدخلين: فالوحدة تحتاجهما للتحقق من الدفعة. فعّل Debug Logging وراجع حقل Log. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

لا تستطيع Viva التحقق من عنوان webhook: أدخل Merchant ID وAPI Key للوضع الحالي (أو مفتاح التحقق نفسه في Webhook Verification Key)، واحفظ، ثم تحقّق مرة أخرى في Viva. وللتحقق من webhook الحساب الآخر، بدّل Test Mode أولًا أو أدخل مفتاح ذلك الحساب.

يرد webhook برسالة خطأ: تعرض Viva ردّ متجرك وتعيد محاولة webhooks الفاشلة. يعني verification_failed (HTTP 500) أنه تعذّر الوصول إلى واجهة Viva API للتحقق من الدفعة، أو تعذّر إنشاء الطلب (مثلًا إذا كانت الوحدة معطّلة). ويعني busy (HTTP 503) أن الطلب كان يُعالَج من طلب آخر في اللحظة نفسها. ويعني transaction_not_found (HTTP 404) أن المعاملة غير موجودة في حساب تلك الدفعة، مثلًا بسبب بيانات اعتماد خاطئة. وتتلقى الأحداث الخاصة بدفعات متاجر أخرى على حساب Viva نفسه الرد ignored.

يرى العميل خطأ عند اختيار Viva Wallet: راجع حقل Log في صفحة الوحدة. يعرض Client ID أو Client Secret خاطئ رسالة بأن مدفوعات Viva Wallet غير متاحة. وإذا تعذّر الوصول إلى Viva أو رفضت طلب الدفع، مثلًا لأن Source Code يتبع حسابًا آخر، يتلقى العميل رسالة بأن المتجر لم يتمكن من الاتصال بـ Viva Wallet.

يعود العميل فيرى We could not find your order. If you were charged, please contact us.: رمز طلب Viva في عنوان العودة ليس دفعة لهذا المتجر، مثلًا لأن مصدر الدفع الخاص بمتجر آخر يشير إلى هنا. تحقّق من Success URL وFailure URL لمصدر الدفع.

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

يفشل الاسترداد برسالة This payment was made in the Viva demo (or live) environment: لم يُدخل Client ID وClient Secret للحساب الذي تمت فيه الدفعة. أدخلهما وأعد المحاولة. وتعرض أخطاء الاسترداد الأخرى رمز HTTP ورسالة Viva.

تقول الكتلة Transaction ID not found. Cannot process refund.: ليس للطلب دفعة Viva مؤكدة، مثلًا بعد عدم تطابق المبلغ. استرد الدفعة من لوحة Viva عند الحاجة.

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

تعطيل الوحدة يُبقي جميع البيانات؛ ولا يُحذف إلا رموز الوصول المخزنة مؤقتًا لدى Viva. ولإزالة الوحدة، انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Viva Wallet Gateway، واختر Uninstall. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. تُحذف رموز الوصول المخزنة مؤقتًا ومفاتيح webhook دائمًا. وإذا كان Delete Data on Uninstall مفعّلًا، تُحذف الإعدادات والسجل. وإذا كان معطّلًا، تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ محاولات الدفع والاستردادات لدى Viva وحالة الطلب Viva Wallet payment on hold دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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