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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب 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. وبالعملات الأخرى تُخفى طريقة الدفع في صفحة الدفع.

موقع HTTPS عام: لكي تعمل webhooks، يجب أن يكون موقعك متاحًا من الإنترنت عبر HTTPS.

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعِّل Enable/Disable. أجرِ دفعة تجريبية ببطاقة Viva التجريبية والخيار Test Mode مفعّل، ثم ألغِ تحديد Test Mode للانتقال إلى الوضع الحقيقي.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Viva Wallet. وفوق الحقول تعرض الصفحة تحذيرًا إذا لم يكن الوضع الحالي يحتوي على 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 Wallet بأنها بحاجة إلى إعداد حتى يحتوي الوضع الحالي على هذه القيم الثلاث.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Viva Wallet.

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

Test Mode: Use the Viva demo environment (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 الخاص بـ Smart Checkout للحساب. مطلوب.

Client Secret (Demo) / Client Secret (Live): السر OAuth 2.0 الخاص بـ 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.

عناوين URL للعودة وwebhook

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

Webhook: في Settings > API Access > Webhooks أضف عنوان URL المعروض في الإعدادات، والذي يبدو كالتالي: https://your-site/wp-json/wc-viva-gateway/v1/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. تُزال علامة # في البداية. اتركه فارغًا لاستخدام اللون الافتراضي. وأي قيمة أخرى تُرفض عند الحفظ وتبقى القيمة السابقة كما هي.

Debug Logging: Enable logging يكتب طلبات API في WooCommerce > Status > Logs، بالمصدر wcp_viva_gateway. لا تُسجَّل المفاتيح وبيانات العملاء. وتُسجَّل الأخطاء دائمًا حتى لو كان هذا الخيار معطّلًا. الافتراضي: معطّل.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. عند تفعيله، يؤدي حذف الإضافة إلى إزالة الإعدادات وجدول محاولات الدفع وسجلات الإضافة. وتبقى ملاحظات الطلبات وبياناتها. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Viva Wallet) ويقدّم الطلب. تنشئ الإضافة طلب دفع في Viva بإجمالي الطلب وبعملة الطلب، وتنقل العميل إلى صفحة Viva Smart Checkout. هناك يدفع العميل بإحدى الطرق المفعّلة في حسابك لدى Viva، مثل البطاقات أو Apple Pay أو Google Pay. وتُمرَّر إلى Viva بيانات العميل من بريد إلكتروني واسم وهاتف ودولة، وتُفتح الصفحة بلغة موقعك إن كانت Viva تدعمها، وإلا فبالإنجليزية. ويظهر الدفع في Viva باسم WooCommerce # ورقم الطلب. وينتهي صلاحية طلب الدفع في Viva بعد 30 دقيقة.

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

إذا فشل الدفع أو ألغى العميل في صفحة Viva، فلا تتغير حالة الطلب. يُنقل العميل إلى صفحة Pay for order مع الرسالة 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. ويُكتب السبب التقني في السجل.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة Checkout، وفي صفحة Pay for order حيث تُتحقق عملة ذلك الطلب. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

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

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

Order statuses

Pending payment: أُرسل العميل إلى Viva ولم يدفع بعد، أو لم يُؤكَّد الدفع بعد، أو فشل الدفع أو أُلغي. تعرض ملاحظة طلب الدفع في Viva والبيئة (تجريبية أو حقيقية). وتُضاف المحاولات الفاشلة والملغاة إلى ملاحظات الطلب، ويمكن للعميل الدفع مجددًا.

Processing, Completed or On Hold: تم تأكيد الدفع. وتتبع الحالة Order Status After Payment. وتعرض ملاحظة الطلب المبلغ، ومعرّف معاملة Viva، والبيئة، وكيفية التأكيد (webhook أو عودة العميل).

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

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

الاسترداد

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Viva Wallet. وتُدعم الاستردادات الكاملة والجزئية للطلبات التي لها معاملة Viva مؤكدة. يُرسل الاسترداد إلى الحساب الذي تمت به الدفعة (تجريبي أو حقيقي) وبعملة الدفعة، لذلك يجب إدخال Client ID وClient Secret لذلك الحساب. وإذا لم تقبل Viva الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معاملة الاسترداد في Viva.

لا تُستورد الاستردادات التي تُجرى من لوحة تحكم Viva. وإن لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Viva Wallet.

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

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

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

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

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

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

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

تم الدفع لكن الطلب ما زال Pending payment: الـ webhook لا يعمل. في Viva تحقّق من وجود الـ webhook في الحساب الذي تستخدمه (تجريبي أو حقيقي)، وأن عنوانه مطابق تمامًا للعنوان المعروض في الإعدادات، وأن Transaction Payment Created محدد. وتأكد من بقاء Client ID وClient Secret للحساب الخاص بذلك الدفع مُدخلَين، فالإضافة تحتاجهما للتحقق من الدفعة. وتفاصيل ذلك في WooCommerce > Status > Logs، بالمصدر wcp_viva_gateway.

لا تستطيع 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.

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

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. كان المبلغ المدفوع أو عملته مختلفًا عن الطلب. أكمل الطلب أو استرد الدفعة.

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

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

للمطوّرين: يفعّل الفلتر viva_wp_supported_currencies عملات إضافية يدعمها حسابك في Viva، ويعدّل viva_wp_create_order_payload طلب طلب الدفع (يجب أن تبقى قيم المبلغ والعملة وSource Code كما هي)، ويغيّر viva_wp_icon أيقونة الدفع.

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

يُبقي إلغاء تفعيل الإضافة على كل البيانات؛ ولا تُحذف إلا رموز الوصول المخزنة مؤقتًا لدى Viva. ولحذفها نهائيًا، ألغِ تفعيلها ثم احذفها من صفحة Plugins. ويُحذف دائمًا مفتاح الترخيص وحالته، وكذلك الرموز المخزنة مؤقتًا ومفاتيح webhook. أما الإعدادات وجدول محاولات الدفع وسجلات الإضافة (ملفات السجل بما فيها المؤرشفة، وإدخالات قاعدة البيانات) فتُحذف فقط إذا كان Delete Data on Uninstall مفعّلًا، وإلا تبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

Viva Wallet علامة تجارية تعود لمالكها. هذه الإضافة غير تابعة لـ Viva Wallet ولا معتمدة من قِبلها.