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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: راند جنوب أفريقيا (ZAR). تقبل Yoco عملة ZAR فقط. وبأي عملة أخرى لا تظهر طريقة الدفع في صفحة الدفع. ويجب أن يكون إجمالي الطلب R2.00 على الأقل.

حساب Yoco: حساب Yoco مفعّل للمدفوعات الإلكترونية. تحتاج إلى مفاتيحه السرية، وتجدها في Yoco Business Portal ضمن Selling Online > Payment Gateway. تُدخَل المفاتيح السرية فقط. تسجّل الإضافة الـ webhook، وتُملأ لك خانة سر التوقيع تلقائيًا.

موقع عام: ترسل Yoco الـ webhooks إلى موقعك، لذا يجب أن يكون متاحًا من الإنترنت. ويجب أن يقبل عنوان URL الخاص بالـ webhook طلب POST دون عمليات إعادة توجيه.

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

التثبيت

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

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > Yoco > Manage.

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

5. الصق المفتاح السري للاختبار (sk_test_...) ثم، عند الاستعداد، المفتاح السري للإنتاج (sk_live_...). احفظ الإعدادات. يُسجَّل الـ webhook لكل وضع لديه مفتاح.

6. فعّل Enable/Disable. أجرِ دفعة تجريبية ببطاقة اختبار من Yoco ما دام Test mode مفعّلًا، ثم ألغِ تحديد Test mode لاستقبال مدفوعات حقيقية.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Yoco. وتُظهر الصفحة فوق الحقول تحذيرًا عندما لا تكون عملة المتجر ZAR (وعندها لا تُعرض Yoco في صفحة الدفع)، وعندما لا يملك الوضع الحالي مفتاحًا سريًا. وفي قائمة طرق الدفع تُعلَّم Yoco بأنها تحتاج إلى إعداد حتى يملك الوضع الحالي مفتاحًا سريًا. وعند الحفظ تتحقق الإضافة من المفاتيح وأسرار الـ webhooks وتسجّل الـ webhooks. وتظهر الرسائل المتعلقة بذلك في أعلى الصفحة.

عام

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. الافتراضي: Card or Instant EFT (Yoco).

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

مفاتيح API

انسخ المفاتيح السرية من Yoco Business Portal ضمن Selling Online > Payment Gateway. لدى Yoco واجهة API واحدة للوضعين: المفتاح هو ما يحدد إن كانت الدفعة تجريبية أم حقيقية. يستخدم وضع الاختبار مفتاح الاختبار فقط، ويستخدم وضع الإنتاج مفتاح الإنتاج فقط.

Test mode: Use the test secret key (no real payments). لا يُخصم أي مبلغ حقيقي؛ ادفع ببطاقات اختبار Yoco. الافتراضي: on. ألغِ التحديد لاستقبال مدفوعات حقيقية.

Test secret key: المفتاح السري لوضع الاختبار. يبدأ بـ sk_test_.

Live secret key: المفتاح السري لوضع الإنتاج. يبدأ بـ sk_live_.

لا يُحفظ المفتاح الذي لا يبدأ بالبادئة المتوقعة: تعرض الصفحة خطأً وتحتفظ بالقيمة السابقة. وإذا أبلغت Yoco أثناء تسجيل الـ webhook بأن المفتاح يتبع الوضع الآخر، فستخبرك الصفحة بذلك.

Webhooks

تؤكد Yoco المدفوعات والاستردادات إلى عنوان URL الخاص بالـ webhook المعروض في هذا القسم. وهو بالشكل التالي: https://your-site/wc-api/yoco_pay_webhook/. لا تحتاج إلى إنشاء الـ webhook في بوابة Yoco. وعند حفظ الإعدادات تسجّل الإضافة العنوان لدى Yoco لكل وضع لديه مفتاح سري وليس لديه سر webhook، وتخزّن سر التوقيع في خانة ذلك الوضع. وتُعيد تسجيل العنوان عندما يتغير المفتاح السري لذلك الوضع أو عنوان الـ webhook. وعند تغيير العنوان تُحذف التسجيلة القديمة.

يعرض القسم حالة الـ webhook لكل وضع:

تتعامل الإضافة مع هذه الأحداث:

تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. وإذا كان موقعك يستخدم بادئة لغة في عناوين URL، فأبقِ العنوان كما تعرضه الإعدادات تمامًا، لأن الـ webhook يجب أن يصل إلى متجرك دون إعادة توجيه.

Test webhook secret: يُملأ تلقائيًا عند تسجيل الـ webhook. الصق سرًا (whsec_...) فقط إذا سجّلتَ عنوان الـ webhook بنفسك.

Live webhook secret: يُملأ تلقائيًا عند تسجيل الـ webhook. أفرغ الحقل واحفظ لإعادة تسجيل الـ webhook.

يجب أن يكون شكل سر الـ webhook whsec_ يتبعه نص base64. وأي قيمة أخرى لا تُحفظ، وتبقى القيمة السابقة.

متقدم

Debug log: Log Yoco requests and webhooks يكتب الطلبات والـ webhooks في WooCommerce > Status > Logs، بالمصدر wcp_yoco_pay. وتُسجَّل الأخطاء والتحذيرات، مثل الطلبات الفاشلة إلى Yoco والـ webhooks المرفوضة، دائمًا. وتُخفى المفاتيح وأسرار الـ webhooks وعناوين البريد الإلكتروني. الافتراضي: off.

Delete data: Delete the settings and logs of this plugin when it is deleted. التعطيل لا يحذف أي شيء أبدًا. وتُحفظ بيانات الطلبات (معرّفات checkout ودفع Yoco) دائمًا، لأنها لازمة للاستردادات. الافتراضي: off.

الدفع

يختار العميل طريقة الدفع (الافتراضي Card or Instant EFT (Yoco)) ويُقدّم الطلب. وفي وضع الاختبار تعرض صفحة الدفع Test mode — use a Yoco test card; no real money is charged. وتُنشئ الإضافة checkout من Yoco بمبلغ الطلب بالسنتات، وتُرسل العميل إلى صفحة الدفع الخاصة بـ Yoco، حيث يدفع ببطاقة أو Instant EFT.

بعد الدفع يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Yoco: تسأل الإضافة Yoco عن الـ checkout عند عودة العميل، ومرة أخرى عند وصول الـ webhook الموقَّع. وإذا لم تكن Yoco قد أكدت الدفعة بعد، تعرض صفحة استلام الطلب We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

إذا ألغى العميل في صفحة Yoco، يبقى الطلب غير مدفوع، ويصل العميل إلى صفحة Pay for order مع الرسالة The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. وإذا فشلت الدفعة فالرسالة هي The Yoco payment was not successful. Please try again or choose another payment method. وتُضاف ملاحظة إلى الطلب.

يستطيع العميل دفع طلب غير مدفوع مرة أخرى من صفحة Pay for order. وقبل المحاولة الجديدة تتحقق الإضافة من المحاولة السابقة لدى Yoco. فإذا كانت قد دُفعت، يكتمل الطلب دون عرض صفحة دفع جديدة. وإذا كانت ما تزال مفتوحة بالمبلغ نفسه وأُنشئت قبل أقل من 30 دقيقة، يحصل العميل على صفحة Yoco نفسها مرة أخرى.

إذا تعذّر على Yoco بدء الدفعة، يرى العميل Yoco could not start the payment. Please try again in a moment or choose another payment method. ويُضاف السبب إلى ملاحظات الطلب. ويحصل الطلب الذي يقل عن R2.00 على Yoco requires an order total of at least R2.00.

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

تُخصم المدفوعات فورًا في صفحة Yoco. لا تتضمن الإضافة بطاقات محفوظة ولا اشتراكات أو مدفوعات متكررة، ولا نموذج إدخال بطاقة على الموقع، ولا تفويضًا وتحصيلًا منفصلين، ولا تعمل بغير عملة ZAR.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Yoco ولم يدفع بعد، أو ألغى في صفحة Yoco، أو لم تؤكد Yoco الدفعة بعد.

Processing or Completed: تم تأكيد الدفعة. يضع WooCommerce الحالة «قيد التجهيز»، أو «مكتمل» للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. وتُظهر ملاحظة الطلب المبلغ، ومعرّفات دفعة Yoco والـ checkout، والوضع، وكيفية تأكيد الدفعة (عودة العميل، أو الـ webhook، أو فحص قبل محاولة دفع جديدة). ومعرّف المعاملة هو معرّف دفعة Yoco.

On hold: أبلغت Yoco عن مبلغ أو عملة يختلفان عن إجمالي الطلب، مثلًا لأن الطلب عُدِّل بعد بدء الدفع. وتشرح الملاحظة ذلك، ويرى العميل العائد من Yoco الرسالة We received your payment and are reviewing it. We will contact you if anything else is needed. تحقق من الدفعة قبل الشحن.

Cancelled or Refunded: لا تُغيّر الدفعة التي تصل لطلب كهذا الطلب. وتطلب منك ملاحظة استرداد الدفعة في بوابة Yoco أو استعادة الطلب يدويًا. ويرى العميل العائد من Yoco الرسالة Your payment was received after the order had been cancelled. Please contact us — do not pay again.

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

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على زر Refund via مع اسم طريقة الدفع الخاصة بك (الافتراضي Card or Instant EFT (Yoco)). يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد في الوضع الذي تمت به الدفعة (الاختبار أو الإنتاج)، لذلك يجب أن يكون المفتاح السري لذلك الوضع مُعدًّا. والاسترداد المُعاد بعد استجابة مفقودة لا يُصرف مرتين.

يُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف استرداد Yoco. وإذا رفضت Yoco الاسترداد، يعرض WooCommerce Yoco refused the refund: مع السبب، ولا يُسجَّل أي استرداد. وإذا أبلغت Yoco بأن الاسترداد معلّق، يعرض WooCommerce أنه ما زال معلّقًا ولا يسجّل شيئًا. لا تُكرره: سيُضاف إلى الطلب عندما تؤكده Yoco عبر الـ webhook.

تصل الاستردادات التي تتم في بوابة Yoco عبر webhook الخاص بـ refund.succeeded، وتُسجَّل تلقائيًا كاستردادات WooCommerce دون إعادة المنتجات إلى المخزون. ولا يُسجَّل الاسترداد الذي يتجاوز المبلغ المتبقي القابل للاسترداد، وتطلب منك ملاحظة فحص الطلب. ويُضيف الاسترداد الفاشل ملاحظة بأن المال لم يُعَد إلى العميل.

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

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

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

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

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

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

لا تظهر Yoco في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح سري: Test secret key في وضع الاختبار، وLive secret key في وضع الإنتاج. يجب أن تكون عملة المتجر أو الطلب ZAR، وأن يكون إجمالي الطلب R2.00 على الأقل. وتعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو العملة ليست ZAR.

تمت الدفعة لكن الطلب ما زال Pending payment: الـ webhook لا يعمل. افتح قسم Webhooks في الإعدادات وتحقق من حالة الوضع الذي تستخدمه. إذا لم يكن مسجّلًا، أو كان مسجّلًا لعنوان URL آخر، فاحفظ الإعدادات. وإذا فشل التسجيل، تعرض الصفحة السبب. وإذا أدخلت السر بنفسك، فتحقق من أنه يتبع الـ webhook الخاص بهذا العنوان وهذا الوضع. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع، وعندما يحاول الدفع مرة أخرى.

تعذّر تسجيل الـ webhook: تُؤكَّد المدفوعات عند عودة العملاء إلى المتجر. أصلح السبب المعروض في الرسالة، مثل أن الموقع يجب أن يكون متاحًا من الإنترنت عبر HTTPS، ثم احفظ مرة أخرى. ويمكنك أيضًا تسجيل العنوان بنفسك ولصق سر التوقيع.

تُرفض الـ webhooks: تُكتب الـ webhooks المرفوضة في السجل، بالمصدر wcp_yoco_pay. تعني webhook secret not configured أنه لم يُعيَّن أي سر webhook. وتعني invalid signature أن السر يتبع تسجيلًا أو وضعًا آخر. وتعني timestamp outside the tolerance أن ساعة الخادم غير صحيحة: تُقبل التوقيعات خلال 5 دقائق من وقت الخادم فقط. أما checkout not completed yet — retry وcould not confirm the checkout with Yoco — retry فهي مؤقتة، إذ تعيد Yoco إرسال الـ webhook.

The secret key must start with sk_test_ / sk_live_ error on save: لُصق مفتاح في الحقل الخطأ. يبدأ مفتاح الاختبار بـ sk_test_، ويبدأ مفتاح الإنتاج بـ sk_live_. وقد احتُفظ بالقيمة السابقة.

يرى العميل خطأً عند تقديم الطلب: اقرأ ملاحظات الطلب أو WooCommerce > Status > Logs، بالمصدر wcp_yoco_pay. تعني Yoco is not available at the moment. Please choose another payment method. أن الوضع الحالي لا يملك مفتاحًا سريًا.

يُبلَّغ العميل بأن الدفعة تحتاج إلى مراجعة: دُفعت محاولة سابقة بمبلغ مختلف، أو بعد إلغاء الطلب. اقرأ ملاحظة الطلب، ثم أنجز الطلب أو استرد الدفعة في بوابة Yoco.

يفشل الاسترداد برسالة متعلقة بالوضع: تمت الدفعة في وضع الاختبار أو الإنتاج، والمفتاح السري لذلك الوضع غير مُعدّ. أدخله وأعد المحاولة.

يفشل الاسترداد برسالة No answer from Yoco: لم يُسجَّل شيء في WooCommerce. وإذا عالجت Yoco الاسترداد، فأعد الاسترداد نفسه: لن يُسترد مرتين.

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

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

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

Yoco علامة تجارية مملوكة لصاحبها. هذه الإضافة غير مرتبطة بـ Yoco ولا تحظى بتأييدها.