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

المتطلبات

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

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

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

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

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

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

التثبيت

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

2. عند انتهاء الرفع اضغط Configure، أو اعثر لاحقًا على VibeFox Yoco Pay Gateway في قائمة الوحدات واضغط Configure.

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

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

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

عند التثبيت تنشئ الوحدة حالة الطلب Yoco payment on hold. تقدّم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذّرك الصفحة عندما لا تكون عملة المتجر ZAR (فلا يُعرض Yoco عندئذٍ في الدفع)، وعندما لا يملك الوضع الحالي مفتاحًا سريًا، مثل Enter the test secret key to offer Yoco at checkout (test mode). وعند الحفظ تتحقق الوحدة من المفاتيح وأسرار الـ webhooks وتسجّل الـ webhooks. وتظهر الرسائل المتعلقة بذلك في أعلى الصفحة.

Yoco

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

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: يستخدم المفتاح السري للاختبار. لا يُخصم أي مبلغ حقيقي؛ ادفع ببطاقات اختبار Yoco. الافتراضي: مفعّل. أوقفه لاستقبال المدفوعات الحقيقية. وما دام مفعّلًا يرى العملاء أسفل طريقة الدفع الرسالة Test mode — use a Yoco test card; no real money is charged.

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

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

لا يُحفظ المفتاح الذي لا يبدأ بالبادئة المتوقعة: تعرض الصفحة خطأ، مثل Yoco: the test secret key must start with sk_test_ — the previous value was kept. وإذا أبلغت Yoco أثناء تسجيل الـ webhook بأن المفتاح يتبع الوضع الآخر، فستخبرك الصفحة بذلك.

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

Webhooks

تؤكد Yoco المدفوعات والاستردادات على العنوان الظاهر في Webhook URL في هذا القسم. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_yoco_pay/webhook، وقد يسبقه رمز لغة مثل /en/. لا تحتاج إلى إنشاء الـ webhook في بوابة Yoco. عند حفظ الإعدادات تسجّل الوحدة العنوان لدى Yoco لكل وضع له مفتاح سري ولا يملك سر webhook، وتخزّن سر التوقيع في حقل ذلك الوضع. وتعيد التسجيل عند تغيّر المفتاح السري لذلك الوضع أو تغيّر عنوان الـ webhook. وعند تغيّر العنوان يُحذف التسجيل القديم.

لكل وضع (Test وLive) يعرض هذا القسم حالة الـ webhook:

تعالج الوحدة هذه الأحداث (وهي مدرجة أيضًا في هذا القسم):

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

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

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

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

Clear saved secrets: ضع علامة على مفتاح أو سر واضغط Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة. ومسح سر الـ webhook ثم الحفظ يعيد تسجيل الـ webhook.

متقدم

Debug log: يكتب طلبات Yoco والـ webhooks في logs/yoco_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح هذا الملف من الويب. تُسجَّل الأخطاء والتحذيرات، مثل الطلبات الفاشلة إلى Yoco والـ webhooks المرفوضة، دائمًا. تُخفى المفاتيح وأسرار الـ webhooks وعناوين البريد الإلكتروني. الافتراضي: معطّل.

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

Delete data: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات والسجل والـ webhooks التي سجّلتها الوحدة لدى Yoco. أما بيانات الطلبات (معرّفات checkout ودفع Yoco والاستردادات) وحالة الطلب Yoco payment on hold فتبقى دائمًا لأنها لازمة للاستردادات. الافتراضي: معطّل.

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Yoco: تطلب الوحدة الـ checkout من Yoco عند عودة العميل، ومرة أخرى عند وصول الـ webhook الموقّع. ثم يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب المعتادة مع الرسالة Your payment with Yoco has been received. إذا لم تؤكد Yoco الدفعة بعد عند عودة العميل، تظهر صفحة Payment confirmation مع الرسالة We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. وزر Check again؛ وينشئ الـ webhook الطلب فور وصوله.

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

قبل محاولة دفع جديدة للسلة نفسها تتحقق الوحدة من المحاولة السابقة لدى Yoco. إذا كانت قد دُفعت، يُنشأ الطلب دون عرض صفحة دفع جديدة. وإذا كانت لا تزال مفتوحة للمبلغ نفسه وأُنشئت منذ أقل من 30 دقيقة، يحصل العميل على صفحة Yoco نفسها مرة أخرى. وفي الحالات الأخرى يُنشأ checkout جديد في 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.

يعمل الـ webhook أثناء وضع الصيانة للمتجر، ولا يتأثر بقيود الدول في متجرك.

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

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

حالات الطلب

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

Payment accepted: تم تأكيد الدفعة. تُسجَّل الدفعة بمعرّف دفع Yoco كمعرّف للمعاملة، وتعرض ملاحظة المبلغ ومعرّفات دفع Yoco والـ checkout والوضع وكيفية تأكيد الدفعة (عودة العميل أو الـ webhook أو فحص قبل محاولة دفع جديدة).

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

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

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

كتلة الدفع في Yoco

تعرض صفحة الطلب كتلة Yoco payment تتضمن معرّفات دفع Yoco والـ checkout، والحالة، والمبلغ المدفوع والمسترد، وشارة Test mode للدفعات التجريبية، وسجل الاستردادات، ومحاولات دفع السلة (إذا كانت أكثر من واحدة)، وملاحظات Yoco notes الخاصة بالطلب.

الاستردادات

في كتلة Yoco payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب سببًا اختياريًا، ثم اضغط Refund via Yoco. أكّد السؤال Refund this amount through Yoco? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. يلزمك حق تعديل الطلبات. تُحسب الاستردادات من المبلغ الذي حصّلته Yoco، لذلك لا يمكنك استرداد أكثر مما دفعه العميل فعلًا، حتى لو عُدّل الطلب لاحقًا. يُرسل الاسترداد في الوضع الذي تمت به الدفعة (اختبار أو إنتاج)، لذلك يجب أن يكون المفتاح السري لذلك الوضع مضبوطًا. والاسترداد المكرر بعد ضياع الرد لا يُصرف مرتين.

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترد الأموال عبر Yoco.

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

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

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

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

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

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

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

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

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

يتم رفض الـ webhooks: تُكتب الـ webhooks المرفوضة في السجل. 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.

يظهر POST فقط عند فتح عنوان الـ webhook في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Yoco فقط.

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

يرى العميل خطأ عند اختيار Yoco: راجع حقل Log في صفحة الوحدة. تعني الرسالة Yoco is not available at the moment. Please choose another payment method. أن الوضع الحالي ليس له مفتاح سري.

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

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

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

المطورون: يتيح الخطاف actionYocoPCheckoutPayload لوحدة أخرى تعديل الطلب الذي يُنشئ checkout في Yoco.

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

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

Yoco علامة تجارية مسجّلة لصاحبها. هذه الوحدة غير تابعة لـ Yoco ولا معتمدة منها.