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

المتطلبات

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

PHP: ‏8.0 أو أحدث.

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

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

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل بيانات اعتماد الحساب التجريبي و/أو الحساب الحي في Viva، ثم أعدّ مصدر الدفع والإشعار الفوري في حساب Viva (انظر Configuration).

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

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص وبيانات اعتماد Viva ومصدر الدفع والإشعار الفوري كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. العناوين الخاصة بحساب Viva فقط مختلفة (انظر Configuration).

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit. تُعرض الأقسام على اليسار؛ وزر 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. وإذا لم تكن لديك صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

عند الحفظ، لا يمكن أن يكون Title فارغًا، ويجب ألا يتجاوز 128 حرفًا (Enter a title for the payment method (at most 128 characters).)، ويجب أن يكون Sort Order عددًا صحيحًا (Sort Order must be a whole number.)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0 (Total: enter a number, 0 or greater.)، ويجب أن تكون المنطقة الجغرافية وحالات الطلب المختارة موجودة؛ وإلا فلن يُحفظ شيء وتعرض الصفحة الخطأ. يؤدي حفظ الإعدادات إلى حذف رموز الوصول المخزّنة مؤقتًا لـ Viva، فتُستخدم بيانات الاعتماد الجديدة فورًا.

Viva Wallet

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

Title: اسم طريقة الدفع الذي يراه العميل في الخطوة الأخيرة من الشراء، وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الإعداد الافتراضي: Viva Wallet. حقل إلزامي، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الإعداد الافتراضي: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

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

Sort Order: موضع Viva Wallet بين طرق الدفع عند الخروج. اتركه فارغًا أو أدخل عددًا صحيحًا؛ الأعداد السالبة مسموحة.

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

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

Demo account (test mode) and Live account

يحتوي القسمان على الحقول نفسها: مجموعة للحساب التجريبي وأخرى للحساب الحي. في حساب 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 للإشعار الفوري من Viva.

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

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

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

Return URLs and webhook

Addresses for the Viva account: يعرض هذا الحقل العناوين الثلاثة لمتجرك التي يجب إدخالها في حساب Viva. تُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart الخاص بك، وعلى OpenCart 3 تبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_viva_gateway/success& وhttps://your-store/index.php?route=extension/payment/wcp_viva_gateway/fail& وhttps://your-store/index.php?route=extension/payment/wcp_viva_gateway/webhook على OpenCart 3، وعلى OpenCart 4 تبدو هكذا: https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.success& وhttps://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.fail& وhttps://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.webhook. انسخها تمامًا كما تعرضها الإعدادات. علامة & في نهاية عنواني النجاح والفشل ضرورية: تضيف Viva معرّف المعاملة إلى العنوان، وبدونها يرد OpenCart بصفحة غير موجودة.

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

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

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

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

Order statuses

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). يحصل الطلب على حالة فقط بعد التحقق من دفعة Viva. تسرد حقول الحالة حالات طلبات OpenCart الخاصة بك.

Order Status After Payment: الحالة التي يحصل عليها الطلب المدفوع. تُعيَّن فورًا، بتغيير واحد للحالة.

Processing Status: حالة الطلب المدفوع لخيارَي Default وProcessing. الافتراضي: Processing.

Complete Status: حالة الطلب المدفوع لخيار Completed. الافتراضي: Complete.

On Hold Status: حالة الطلب المدفوع لخيار On Hold، وحالة الطلب الذي لا يتطابق فيه مبلغ دفعة Viva أو عملتها مع الطلب (يُحتجز للمراجعة، ولا يُعتبر مدفوعًا؛ وتوضح الملاحظة السبب). الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالة خاصة بك في System > Localisation > Order Statuses واختيارها هنا.

Cancelled Order Status: لا تعيد دفعة Viva المستلمة لطلب في هذه الحالة فتح الطلب أبدًا؛ وتطلب منك ملاحظة استعادة الطلب أو استرداد الدفعة. لا تعيّن الإضافة هذه الحالة أبدًا. الافتراضي: Canceled.

Refunded Status: تُعيَّن بعد استرداد الدفعة كاملةً من علامة تبويب الطلب. ولا تعيد دفعة لاحقة فتح مثل هذا الطلب أيضًا. الافتراضي: Refunded.

Advanced Settings

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: يكتب طلبات الواجهة البرمجية في viva_wp_debug.log.php داخل مجلد سجلات OpenCart (storage/logs، وعلى OpenCart 4 في system/storage/logs). لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح والرموز وبيانات العملاء. تُسجَّل الأخطاء دائمًا حتى عندما يكون هذا الخيار متوقفًا. الافتراضي: off.

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

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

Import / Export

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

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

الخروج من الشراء (Checkout)

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Viva Wallet). في خطوة Confirm Order يرى العميل وصفك وملاحظة You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، ثم ينقر على Confirm Order في أسفل صفحة الدفع. عندما يضغط العميل Confirm Order، تنشئ الإضافة طلب دفع في Viva بمجموع الطلب بعملة الطلب، وتنقل العميل إلى صفحة Viva Smart Checkout، بلون Brand Color إذا كان محددًا. هناك يدفع العميل بإحدى الطرق المفعّلة في حساب Viva الخاص بك. يُمرَّر البريد الإلكتروني للعميل واسمه وهاتفه وبلده ولغة المتجر إلى Viva. يظهر الدفع في Viva باسم OpenCart # ورقم الطلب، ويُوصف للعميل بأنه Order ورقم الطلب وat واسم متجرك. تنتهي صلاحية طلب الدفع في Viva بعد 30 دقيقة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Viva: تعيد الإضافة قراءة المعاملة من واجهة Viva البرمجية عند عودة العميل وعند وصول الإشعار الفوري. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. إذا لم يتم تأكيد الدفعة بعد، تعرض صفحة 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. تبقى السلة محفوظة حتى يُؤكَّد الدفع؛ ويعيّن الإشعار الفوري حالة الطلب بمجرد أن تؤكد Viva ذلك. في OpenCart 4، عند عودة العميل من صفحة 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. تُدفع السلة مرة واحدة فقط: إذا كانت السلة مدفوعة بالفعل بطلب آخر من عملية الدفع نفسها، ينتقل العميل مباشرة إلى صفحة النجاح. وفي OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع. يُنشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويحدّث OpenCart 4 طلب الدفع، ويُعد تغيير السلة، بما في ذلك الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

يُبقي OpenCart 4 الطلب في صفحة الدفع حتى تُعرض صفحة النجاح. بعد دفعة فاشلة أو ملغاة يدفع العميل الطلب نفسه مرة أخرى بطلب دفع جديد في Viva. وإذا أُغلق ذلك الطلب في الأثناء (مثلًا ألغيته أنت)، أو كان قد دُفع لسلة تغيّرت منذ ذلك الحين، يُعاد العميل إلى صفحة الدفع مع This order can no longer be paid. Please confirm your order again.، وتدفع الخطوة التالية Confirm Order طلبًا جديدًا.

إذا لم تتمكن Viva من بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة فوق الزر: 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. ويُكتب السبب التقني في السجل.

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

يعمل الإشعار الفوري أيضًا أثناء وضع الصيانة في المتجر، لأن OpenCart يسمح بطلبات إضافات الدفع.

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

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

Order statuses

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

Order Status After Payment (الافتراضي Processing): تم تأكيد الدفع. تعرض ملاحظة المبلغ والمعاملة ورمز طلب Viva والبيئة (تجريبية أو حية) وكيفية التأكيد (إشعار فوري أو عودة العميل).

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

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

الملاحظات إدخالات في History الطلب لا يراها العميل. لا تُبلغ تغييرات الحالة العميل بذاتها؛ يرسل OpenCart رسالة الطلب المعتادة عندما يحصل طلب مدفوع على حالته لأول مرة.

VibeFox Viva Wallet Gateway tab

في Sales > Orders افتح طلبًا دُفع عبر Viva Wallet. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Viva Wallet Gateway الخانات التالية: Viva order code، وTransaction ID مع تسمية Demo للمدفوعات التجريبية، وEnvironment / Source Code، وViva status، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد، وViva payment attempts للطلب (عند وجود أكثر من محاولة)، وViva Wallet notes الخاصة بالطلب. تُعرض علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

Refunds

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

لا تُعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Viva. لا تُستورد المبالغ المستردة المنفذة من لوحة Viva. حدّث الطلب يدويًا عند الحاجة.

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

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

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

عند انتهاء صلاحية الترخيص تستمر الإضافة في العمل، لكن التحديثات والدعم تحتاج إلى تجديد. تُعاد مراجعة الحالة تلقائيًا عند فتح Dashboard الإدارة أو صفحة Edit: مرة واحدة يوميًا خلال أول 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. تحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد في الإعدادات. تعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد.

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

يعود العميل إلى صفحة غير موجودة: لا ينتهي Success URL أو Failure URL لمصدر الدفع بعلامة &. انسخ المسارات تمامًا كما تعرضها الإعدادات.

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

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

يرى العميل خطأ بعد Confirm Order: انظر إلى حقل Log في صفحة الإضافة. يؤدي Client ID أو Client Secret خاطئ إلى رسالة بأن مدفوعات Viva Wallet غير متاحة. إذا تعذر الوصول إلى Viva أو رفضت طلب الدفع، مثلًا لأن Source Code يتبع حسابًا آخر، يتلقى العميل رسالة بأن المتجر لم يتمكن من الاتصال بـ Viva Wallet. تعني This payment method is not available. أن جلسة الدفع لم تعد تطابق الطلب: يعيد العميل تحميل صفحة الدفع.

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

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في علامة التبويب VibeFox Viva Wallet Gateway (انظر Order statuses)، ثم نفّذ الطلب أو استرد الدفعة.

لا يوجد نموذج استرداد في علامة التبويب: تذكر علامة التبويب السبب: ليس للطلب دفعة Viva مؤكدة (Transaction ID not found. Cannot process refund.)، أو تم استرداده بالكامل، أو بيانات اعتماد حساب الدفعة مفقودة، أو ليس لمجموعة المستخدمين لديك صلاحية تعديل الإضافة.

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

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

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

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

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