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

المتطلبات

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

PHP: 8.0 أو أحدث.

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

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

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص ومفاتيح Yoco كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. عنوان الـ webhook هو الوحيد المختلف (انظر Webhooks)؛ يُسجَّل لدى Yoco عند الحفظ بالطريقة نفسها.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Yoco Pay Gateway > Edit. تُدرج الأقسام على اليسار؛ يحفظ الزر Save الموجود أسفل القائمة الصفحة كاملة. بدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

تعرض الصفحة فوق الإعدادات الوضع النشط (Test mode: the test secret key is used, no real money is charged. أو Live mode: real payments are accepted.). وتحذّرك عندما تكون عملة المتجر الافتراضية غير الـ ZAR (فتُعرض Yoco حينها فقط عندما يدفع العميل بالـ ZAR، أو لا تُعرض إطلاقًا إذا لم تكن أي عملة ZAR مفعّلة)، وعندما لا يملك الوضع الحالي مفتاحًا سريًا، مثل Enter the test secret key to offer Yoco at checkout (test mode).

عند الحفظ، يجب ألا يتجاوز Title 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن توجد المنطقة الجغرافية وحالات الطلبات. وإلا فلن يُحفظ شيء، وتذكر الصفحة الحقل المعني. ثم تتحقق الإضافة من المفاتيح وأسرار الـ webhook وتسجّل الـ webhooks. تظهر الرسائل المتعلقة بذلك فوق الإعدادات.

Yoco

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Card or Instant EFT (Yoco). حتى 128 حرفًا؛ وإذا كان فارغًا يرى العملاء Card or Instant EFT (Yoco).

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

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

Geo Zone: اعرض Yoco فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يصل إليه الطلب قبل عرض Yoco. اتركه فارغًا لعرض Yoco لأي إجمالي. ولا تقبل Yoco نفسها أقل من R2.00 في كل الأحوال.

مفاتيح API

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

Test mode: يستخدم المفتاح السري للاختبار. لا يُحصَّل أي مال حقيقي؛ ادفع ببطاقات اختبار Yoco. الافتراضي: on. أوقفه لقبول المدفوعات الحقيقية. وطالما هو مفعّل يرى العملاء Test mode — use a Yoco test card; no real money is charged. في خطوة Confirm Order.

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. أدخل قيمة جديدة فقط عند الرغبة في تغييرها. لحذف قيمة محفوظة، ضع علامة على Clear the saved value أسفل الحقل، ثم انقر على Save.

Webhooks

ترسل Yoco تأكيدات الدفع والاسترداد إلى عنوان URL الظاهر في Webhook URL في هذا القسم. على OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_yoco_pay/webhook، وعلى OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_yoco_pay/payment/wcp_yoco_pay.webhook ويُبنى من عنوان واجهة المتجر لتثبيت OpenCart لديك. لا تحتاج إلى إنشاء الـ webhook في بوابة Yoco. عند حفظ الإعدادات، تسجّل الإضافة العنوان لدى Yoco لكل وضع له مفتاح سري ولا يملك سر webhook، وتخزّن سر التوقيع في حقل ذلك الوضع. وتعيد تسجيل العنوان عندما يتغير المفتاح السري لذلك الوضع أو عنوان الـ webhook. وعندما يتغير العنوان يُزال التسجيل القديم.

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

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

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

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

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

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

الطلبات

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

Paid Order Status: الحالة بعد دفع مؤكد. الافتراضي: Processing.

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

Refunded Status: تُعيَّن عندما تبلغ المبالغ المستردة المبلغ المدفوع. الافتراضي: Refunded.

متقدم

Debug log: يكتب طلبات Yoco والـ webhooks في الملف yoco_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs، وعلى OpenCart 4 في system/storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُنقل إلى yoco_p_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات، مثل الطلبات الفاشلة إلى Yoco والـ webhooks المرفوضة، دائمًا. تُخفى المفاتيح وأسرار الـ webhook وعناوين البريد الإلكتروني. الافتراضي: off.

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

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

استيراد / تصدير

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

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

الدفع

تظهر طريقة الدفع عندما يدفع العميل بالـ ZAR ويكون إجمالي الطلب R2.00 على الأقل. يختارها العميل في خطوة Payment Method (افتراضيًا Card or Instant EFT (Yoco)). في خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ما زال دون حالة. في OpenCart 4 يختار العميل وسيلة الدفع بزر Choose في كتلة وسيلة الدفع، في النافذة Payment method options، ثم ينقر على Confirm Order في أسفل صفحة الدفع. عندما ينقر العميل على Confirm Order، تنشئ الإضافة صفحة دفع Yoco بإجمالي الطلب بالسنتات، وتنقل العميل إلى صفحة الدفع الخاصة بـ Yoco، حيث يدفع بالبطاقة أو Instant EFT.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Yoco ذلك: تستعلم الإضافة من Yoco عن صفحة الدفع عندما يعود العميل، ومرة أخرى عندما يصل الـ webhook الموقّع. ثم يحصل الطلب على حالته بالطريقة المعيارية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع 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 وBack to checkout؛ ويضبط الـ webhook حالة الطلب فور وصوله. على OpenCart 4، عند عودة العميل من صفحة Yoco، تفتح صفحة وسيطة قصيرة عنوان العودة في متجرك مرة أخرى، فتبقى السلة وتسجيل دخول العميل محفوظين.

إذا ألغى العميل في صفحة 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. وتُضاف ملاحظة إلى الطلب. وتبقى السلة محفوظة. على OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع.

ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويحدّث OpenCart 4 طلب الدفع. قبل أي دفعة جديدة تتحقق الإضافة من السلة: إذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل، ينتقل العميل مباشرة إلى صفحة النجاح. تُتحقق أولًا من صفحات الدفع غير المدفوعة في Yoco لهذا الطلب ولسلة آخر 24 ساعة؛ وإذا دُفعت إحداها في الأثناء، تُؤكَّد تلك الدفعة بدلًا من إنشاء دفعة جديدة. وإذا كانت صفحة الدفع المفتوحة لهذا الطلب بالمبلغ والوضع نفسيهما، وأُنشئت قبل أقل من 30 دقيقة، يحصل العميل على صفحة Yoco نفسها مرة أخرى. وإلا يُنشأ صفحة دفع جديدة في Yoco. ويُعد تغيير السلة، بما في ذلك الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

يُبقي OpenCart 4 الطلب في الدفع حتى تُعرض صفحة النجاح، لذلك بعد دفعة ملغاة أو فاشلة يدفع العميل الطلب نفسه مرة أخرى. وإذا أُغلق ذلك الطلب دون دفع في الأثناء (مثلًا ألغيته أنت)، يُعاد العميل إلى صفحة الدفع مع Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. ويدفع Confirm Order التالي طلبًا جديدًا.

إذا تعذّر على Yoco بدء الدفع، يبقى العميل في خطوة Confirm Order مع 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 أيضًا والمتجر في وضع الصيانة، لأن OpenCart يمرّر طلبات إضافات الدفع. وفي OpenCart 4 تسمح إجراء بدء التشغيل التابع للإضافة بمرور الـ webhook وعودة العميل.

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

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

حالات الطلب

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

Paid Order Status (الافتراضي Processing): تم تأكيد الدفع. تعرض ملاحظة المبلغ ومعرّفي دفع Yoco وصفحة الدفع والوضع، وكيف تم تأكيد الدفع (عودة العميل، أو الـ webhook، أو التحقق قبل محاولة دفع جديدة).

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

Refunded Status (الافتراضي Refunded): بلغت المبالغ المستردة المبلغ المدفوع.

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

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

الملاحظات هي إدخالات في History الطلب لا يراها العميل. وتبدأ بكلمة Yoco.

تبويب VibeFox Yoco Pay Gateway

في Sales > Orders افتح طلبًا دُفع عبر Yoco. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Yoco Pay Gateway معرّف Checkout ID ومعرّف Payment ID وMode (مع تسمية Test لمدفوعات الاختبار) وStatus وPaid / refunded والمبالغ، ونموذج الاسترداد، وجدول Yoco checkouts of this order، وسجل Refunds، وملاحظات Yoco notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

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

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

لا تُرسل المرتجعات في Sales > Returns المال عبر Yoco.

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

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

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

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

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

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

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

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

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

تُرفض الـ 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.

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

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

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

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

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

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

للمطورين: قبل إنشاء صفحة دفع Yoco، تُطلق الإضافة حدث OpenCart yoco_p_checkout_payload مع بيانات الطلب والطلب نفسه، لتتمكن إضافة أخرى من إضافة بيانات إلى الطلب.

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

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

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

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