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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

العملة: الراند جنوب الأفريقي (ZAR). تظهر طريقة الدفع فقط للسلال المقومة بالراند (ZAR). تحتسب Ozow المبالغ بالسنتات الكاملة، لذا يجب أن تستخدم العملة منزلتين عشريتين.

حساب Ozow: حساب تاجر في Ozow يتضمن Site Code وPrivate Key لموقعك في Ozow، ويُؤخذان من لوحة تحكم التاجر في Ozow. مفتاح API Key اختياري لكنه موصى به. تستخدم Ozow نفس Site Code والمفاتيح للمدفوعات التجريبية والفعلية.

موقع متاح: يجب أن يكون متجرك متاحًا من الإنترنت، دون حماية بكلمة مرور ودون جدار ناري يحجب Ozow، حتى تصل إشعارات Ozow. ويُقبل الإشعار حتى لو كان المتجر في وضع الصيانة.

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

التثبيت

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

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

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

4. أدخل Site Code وPrivate Key، ويُفضَّل أيضًا API Key، من لوحة تحكم التاجر في Ozow.

5. فعّل Enable/Disable وانقر على Save. أجرِ دفعة تجريبية مع تفعيل Test mode، ثم أوقف وضع الاختبار لقبول المدفوعات الفعلية.

عند التثبيت، تُنشئ الوحدة حالتين للطلب: Awaiting Ozow payment وOzow payment on hold. ويوفّر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ وهناك يجب السماح بالراند ZAR للوحدة. كما يجب تحديد أي دولة تُفعَّل لاحقًا للوحدة في المكان نفسه.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Ozow Pay > Configure. كل قسم يحتوي على زر Save يحفظ الصفحة كاملة. وفوق الحقول، تحذرك الصفحة عند غياب Site Code أو Private Key (فيُخفى Ozow حينئذٍ في صفحة الدفع)، وعند عدم كون عملة المتجر الافتراضية ZAR، وعند زيادة منازل العملة العشرية على 2 (اضبطها على 2 من International > Localization > Currencies)، وتعرض Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. ما دام وضع الاختبار مفعّلًا.

Ozow

Enable/Disable: Enable Ozow payments يفعّل طريقة الدفع أو يعطّلها. الافتراضي: off.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Instant EFT (Ozow).

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. وفي وضع الاختبار يُضاف أسفله السطر TEST MODE: no money will be charged. (فقط إذا لم يكن الوصف فارغًا).

بيانات اعتماد Ozow

انسخ Site Code وPrivate Key وAPI Key من لوحة تحكم التاجر في Ozow (Merchant details / Sites). ويحتوي هذا القسم على رابط لوثائق تكامل Ozow على hub.ozow.com.

Site Code: رمز موقع Ozow الذي يستقبل المدفوعات. تُرفض الردود الخاصة برمز موقع آخر.

Private Key: يوقّع كل طلب دفع ويتحقق من كل رد من Ozow. احتفظ به سريًا. وبدونه تُخفى طريقة الدفع ولا يُقبل أي رد من Ozow.

API Key (recommended): اختياري. مع API Key، يُؤكَّد كل دفع ناجح أيضًا عبر واجهة Ozow GetTransaction API قبل تعليم الطلب كمدفوع. ويجب أن تُبلغ الواجهة بأن الدفع مكتمل لهذه السلة، بالمبلغ والعملة وSite Code نفسها.

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

Clear saved secrets: ضع علامة على Private Key أو API Key واحفظ لحذف مفتاح محفوظ. والحقل الفارغ يُبقي القيمة المحفوظة.

Test mode: تستخدم Ozow نفس Site Code والمفاتيح للاختبارات: تُنشأ المدفوعات بالعلامة IsTest=true ولا تنتقل أي أموال. وتتلقى الطلبات المدفوعة في وضع الاختبار رسالة في الطلب؛ لا تشحنها. أوقف وضع الاختبار لقبول المدفوعات الفعلية. ولا تدفع المدفوعة التجريبية أي طلب في الوضع الفعلي. الافتراضي: on.

إشعارات الدفع

تُرسل روابط الإشعار والنجاح والإلغاء والخطأ إلى Ozow مع كل دفعة، لذلك لا يلزم ضبط شيء في لوحة Ozow، إلا إذا كان موقعك في Ozow مضبوطًا على روابط ثابتة. ويعرض القسم الروابط الأربعة: Notification URL وSuccess URL وCancel URL وError URL. وهي روابط وحدة في متجرك (المتحكمات notify وreturn). وإذا كان موقع Ozow لديك يستخدم روابط ثابتة، فانسخها تمامًا كما تعرضها الإعدادات.

متقدم

Debug log: يسجّل طلبات الدفع وردود Ozow في logs/ozow_p_debug.log.php داخل مجلد الوحدة (لا يمكن قراءته من الويب). وتُسجَّل الأخطاء والتحذيرات دائمًا. ولا تُسجَّل المفاتيح والتجزئات والرموز ومدونات العملاء أبدًا. الافتراضي: off.

Log: يعرض الحجم الحالي ونهاية السجل، مع زر Clear log.

Delete data on uninstall: يحذف إعدادات هذه الوحدة وسجلاتها عند إلغاء تثبيتها (تبقى بيانات Ozow المحفوظة في الطلبات). الافتراضي: off.

صفحة الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا Instant EFT (Ozow)) ويؤكد الطلب. تُرسل الوحدة العميل إلى صفحة الدفع المستضافة لدى Ozow مع طلب موقّع لإجمالي السلة بالراند ZAR. والمرجع في كشف الحساب المصرفي هو Cart مع رقم السلة (حتى 20 حرفًا لاتينيًا وأرقامًا ومسافات وشرطات). ويُمرَّر اسم العميل إلى Ozow. لا يوجد طلب في هذه المرحلة. وفي صفحة Ozow يختار العميل بنكًا من جنوب أفريقيا ويعتمد الدفع في تطبيق البنك.

ثم تُبلغ Ozow المتجر وتعيد العميل. ويحمل الاثنان الرد الموقّع نفسه ويُعالَجان بالطريقة نفسها، فيُنشأ الطلب حتى إن فُقد أحدهما. ولا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Ozow: يجب أن تتحقق التجزئة بمفتاحك Private Key، وأن يكون Site Code لك، وأن ينتمي الرد إلى محاولة الدفع هذه للسلة، وأن يتطابق المبلغ والعملة مع السلة. ومع API Key يُتحقق من الدفع أيضًا عبر واجهة GetTransaction API.

بعد الدفع الناجح، يرى العميل صفحة تأكيد الطلب المعتادة. وإذا كانت Ozow أو البنك ما زال يدقق في الدفع، تقول الصفحة We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. وإذا كان الطلب معلقًا، تقول Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. وإذا فشل دفع قيد التدقيق لاحقًا أو أُلغي الطلب غير المدفوع، تقول Your Ozow payment was not completed. Please contact us about this order. وإذا لم تكن Ozow قد أكدت الدفع عند عودة العميل، تعرض الصفحة نص الانتظار مع الزرين Check again وBack to checkout.

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

إذا لم تكن السلة مقومة بالراند ZAR، يرى العميل Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

تقبل الوحدة مدفوعات لمرة واحدة بالراند (ZAR) فقط. ولا تدعم استردادات من PrestaShop، ولا الاشتراكات، ولا حفظ الحسابات المصرفية أو الترميز، ولا إرسال روابط الدفع من الواجهة الخلفية.

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

حالات الطلب

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

Payment accepted: تم تأكيد الدفع. تعرض رسالة الطلب المبلغ ومعرّف معاملة Ozow، وما إذا كان الدفع قد أُكد عبر GetTransaction API. ومعرّف المعاملة لدفعة الطلب هو TransactionId في Ozow. وتتلقى المدفوعة التجريبية الرسالة TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: تدقق Ozow أو البنك في الدفع. ويُحدَّث الطلب عندما ترسل Ozow الحالة النهائية.

Ozow payment on hold: تبيّن رسالة الطلب السبب: المبلغ أو العملة المدفوعة تختلف عن السلة؛ أو وصلت دفعة لطلب سبق إلغاؤه؛ أو، مع API Key، لم تستطع واجهة GetTransaction API تأكيد الدفع بعد أو أنها تناقضه. تحقق من الدفع في لوحة Ozow وغيّر حالة الطلب. وإذا لم تستجب الواجهة، فإن الإشعار التالي من Ozow يكمل الطلب.

خطأ في الدفع: دفعة كانت قيد التدقيق أُلغيت أو هُجرت أو فشلت. ورد Ozow الناجح اللاحق لها ما زال يعلّم الطلب كمدفوع.

لا يُعاد الطلب المدفوع إلى حالة غير مدفوعة أبدًا، ولا يُعاد فتح الطلب الملغى أو المسترد أبدًا. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، تطلب منك رسالة استرداد النسخة المكررة من لوحة Ozow. وإذا كان الطلب معلقًا لسبب آخر، مثل تعيينه من قِبلك، فإن الدفعة اللاحقة تضيف رسالة فقط، وتضبط أنت الطلب على Payment accepted بنفسك.

كتلة دفع Ozow

تعرض صفحة الطلب كتلة Ozow payment تتضمن مرجع المعاملة ومحاولتها، ومعرّف معاملة Ozow، والحالة، والمبلغ المطلوب، والمبلغ الذي أبلغت عنه Ozow، ورسالة Ozow، وعلامة TEST MODE للمدفوعات التجريبية.

الاستردادات

لا تُدعم الاستردادات من PrestaShop. استرد الدفعة من لوحة تحكم التاجر في Ozow، ثم سجّل الاسترداد يدويًا في PrestaShop.

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

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

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

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

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

لا يظهر Ozow في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Site Code وPrivate Key مملوءان، وأن عملة السلة هي ZAR. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها للراند ZAR ولدولة العميل ولمجموعة العميل. وتعرض صفحة الإعدادات تحذيرًا عند غياب أي شيء.

تمت عملية الدفع لكن لم يُنشأ أي طلب: لم يصل إشعار Ozow إلى المتجر ولم يعد العميل. تحقق من أن متجرك متاح من الإنترنت (دون حماية بكلمة مرور أو جدار ناري يحجب Ozow). وإذا كان موقع Ozow مضبوطًا على روابط ثابتة، فتحقق من أنها مطابقة تمامًا للروابط الظاهرة في Payment notifications. فعّل Debug log واقرأ السجل في صفحة Configure.

يرد الإشعار بـ Invalid hash: Private Key في الإعدادات لا يخص موقع Ozow الذي أرسل الرد. انسخه مرة أخرى من لوحة تحكم التاجر في Ozow. ولا يتغير شيء.

يرد الإشعار بـ Unknown site: جاء الرد من موقع Ozow آخر. تحقق من Site Code.

يرد الإشعار بـ Order mismatch أو Order not found: الرد لا يخص دفعة بدأت في هذا المتجر. ولا يتغير شيء.

يرد الإشعار بـ Gateway not configured: Site Code أو Private Key مفقود. أكمله؛ وقد تعيد Ozow المحاولة.

يرد الإشعار بـ Payment not confirmed yet: تعذّر تطبيق الرد بعد. ومع API Key لم تستطع واجهة GetTransaction API تأكيد الدفع (الطلب معلّق والإشعار التالي يكمله؛ وإذا بقي معلقًا، تحقق من API Key ومن الدفع في لوحة Ozow). وهذا هو الرد أيضًا عندما كانت عودة العميل تُعالَج للسلة نفسها في اللحظة ذاتها، أو عندما تعذّر إنشاء الطلب؛ راجع السجل.

لم تدفع المدفوعة التجريبية الطلب: الوحدة في الوضع الفعلي. لا تدفع المدفوعات التجريبية أي طلب في الوضع الفعلي؛ ورسالة الطلب أو السجل يوضحان ذلك.

الطلب في حالة Ozow payment on hold بعد الدفع: اقرأ رسالة الطلب وتحقق من الدفع في لوحة Ozow، ثم اضبط الطلب على Payment accepted أو استرد الدفعة في Ozow.

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

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

Ozow علامة تجارية تخص مالكها. هذه الوحدة غير تابعة لـ Ozow ولا تحظى بتأييدها.