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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعدادات

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

عام

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

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.

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

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

تُرسل روابط الإشعار والنجاح والإلغاء والخطأ إلى Ozow مع كل دفعة، لذلك لا حاجة إلى إعداد أي شيء في لوحة Ozow، ما لم يكن موقعك في Ozow مضبوطًا على روابط ثابتة. يعرض القسم رابط الإشعار، وهو بالشكل التالي: https://your-site/wc-api/ozow_pay/?ozow_notify=1. وإن كان موقعك في Ozow يستخدم روابط ثابتة، فانسخ الرابط تمامًا كما تعرضه الإعدادات.

متقدم

Debug log: Log payment requests and Ozow responses يكتب التفاصيل في WooCommerce > Status > Logs، بالمصدر wcp_ozow_pay. وتُسجَّل الأخطاء والتحذيرات دائمًا. ولا تُسجَّل المفاتيح والتجزئات وبيانات العملاء أبدًا. الافتراضي: معطّل.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept). الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Instant EFT (Ozow)) ويُتم الطلب. تُرسل الإضافة العميل إلى صفحة الدفع المستضافة لدى Ozow مع طلب موقَّع بإجمالي الطلب بالراند (ZAR). والمرجع الظاهر في الكشف البنكي هو Order مع رقم الطلب (حتى 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.

إن ألغى العميل في صفحة Ozow أو فشل الدفع، يُوضع الطلب في حالة Failed ويعود العميل إلى صفحة Pay for order مع الرسالة 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. ويمكن للعميل أن يدفع الطلب نفسه مرة أخرى.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة Checkout، وفي صفحة Pay for order (للطلبات بالراند فقط). وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى Ozow ولم يدفع بعد، أو لم تؤكد Ozow الدفع بعد.

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

On hold: تشرح ملاحظة الطلب السبب. إما أن Ozow أو البنك يراجع الدفع (يُحدَّث الطلب عندما ترسل Ozow الحالة النهائية)، أو أن المبلغ أو العملة المدفوعة يختلف عن الطلب، أو وصلت دفعة لطلب سبق إلغاؤه، أو أنه مع API Key لم تستطع GetTransaction API تأكيد الدفع بعد أو أنه يتعارض معه. تحقق من الدفع في لوحة Ozow وغيّر حالة الطلب. وإن لم تستطع الواجهة الرد، فإن الإشعار التالي من Ozow يُكمل الطلب.

Failed: ألغى العميل الدفع، أو تُرك الدفع دون إكمال، أو أبلغت Ozow عن خطأ. ويمكن للعميل أن يدفع مرة أخرى من الطلب.

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

الاستردادات

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

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

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

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

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

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

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

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

تمّ الدفع لكن الطلب ما زال في Pending payment: لم يصل إشعار Ozow إلى المتجر ولم يعد العميل. تحقق من أن موقعك متاح من الإنترنت (دون وضع الصيانة أو حماية بكلمة مرور أو جدار حماية يمنع Ozow). وإن كان موقعك في Ozow مضبوطًا على روابط ثابتة، فتحقق من أن رابط الإشعار مطابق تمامًا للرابط الظاهر في الإعدادات. فعِّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_ozow_pay.

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

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

يرد الإشعار بـ Order mismatch أو Order not found: الرد لا يعود إلى طلب في هذا المتجر. ولا يُغيَّر شيء.

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

يرد الإشعار بـ Order busy: كان رد آخر من Ozow للطلب نفسه يُعالَج في اللحظة نفسها. لا يُطبَّق هذا الرد؛ وسيطبّقه الإشعار التالي أو عودة العميل.

يرد الإشعار بـ Payment not confirmed yet: مع API Key، لم تستطع GetTransaction API تأكيد الدفع. يبقى الطلب في الانتظار، ويُكمله الإشعار التالي. وإن بقي في الانتظار، فتحقق من API Key ومن الدفع في لوحة Ozow.

يرى العميل الرسالة Ozow accepts payments in South African rand (ZAR) only: الطلب بعملة أخرى. ولا يمكن استخدام Ozow لهذا الطلب.

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

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب وتحقق من الدفع في لوحة Ozow، ثم اضبط الطلب على Processing أو استرد الدفعة من Ozow.

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

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

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

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