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

المتطلبات

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

PHP: 8.0 أو أحدث.

حساب Adyen: تحتاج إلى اسم حساب التاجر في Adyen، ومفتاح API، ومفتاح HMAC لكل بيئة تستخدمها (الاختبار والإنتاج)، وإلى بادئة عنوان URL للإنتاج من أجل المدفوعات الفعلية. ينتمي مفتاح API إلى بيانات اعتماد API تحمل الدورين Checkout webservice وMerchant PAL webservice. يُنشأ مفتاح HMAC من أجل الـ webhook القياسي (راجع Configuration). منطقة العميل للاختبار هي ca-test.adyen.com، ومنطقة العميل للإنتاج هي ca-live.adyen.com. مفاتيح الاختبار ومفاتيح الإنتاج منفصلة. لا حاجة إلى مفتاح العميل، لأن صفحة الدفع تستضيفها Adyen.

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل حساب التاجر ومفتاح API للاختبار ومفتاح HMAC للاختبار، ولاحقًا مفتاح API للإنتاج ومفتاح HMAC للإنتاج وبادئة عنوان URL للإنتاج.

5. في Customer Area الخاصة بـ Adyen (الاختبار والإنتاج)، أضف webhook قياسيًا باستخدام عنوان URL المعروض في قسم Webhook من الإعدادات (راجع Configuration).

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

OpenCart 4

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

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

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

4. الصق مفتاح الترخيص وأدخل الإعدادات كما في الخطوات من 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الرابط الخاص بـ webhook فقط مختلف (انظر Webhook).

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

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Adyen Gateway > Edit. تظهر الأقسام في الجهة اليسرى، ويحفظ الزر Save أسفل القائمة الصفحة بأكملها. طالما أن إعدادات الوضع الحالي غير مكتملة، تعرض الصفحة Adyen is hidden at checkout until the test settings are complete (أو إعدادات الإنتاج) وتسرد ما ينقص: Merchant account ومفتاح API ومفتاح HMAC، وفي وضع الإنتاج Live URL prefix. وأثناء تفعيل وضع الاختبار تعرض الصفحة Test mode is on: payment links and refunds go to the Adyen test environment, no real money. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ يجب أن يتكون Title من 1 إلى 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، وTotal عددًا أكبر من أو يساوي 0، ويجب أن توجد المنطقة الجغرافية وحالات الطلب؛ وإلا فلن يُحفظ شيء، وتذكر الصفحة الحقل المعني. لا تُحفظ مفاتيح HMAC غير السداسية عشرية، ولا بادئة عنوان URL للإنتاج التي تحتوي على أحرف غير الأحرف والأرقام والشرطات: يذكر تحذير الحقل، وتبقى القيمة السابقة، وتُحفظ الإعدادات الأخرى.

Adyen

Enable/Disable: Enable Adyen payment gateway يفعّل وسيلة الدفع أو يعطّلها. الافتراضي: معطّل.

Title: اسم وسيلة الدفع الذي يراه العميل في صفحة الدفع، ويُحفظ أيضًا في الطلب. الافتراضي: Adyen. حقل إلزامي، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely via Adyen.

Sort Order: ترتيب Adyen بين وسائل الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

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

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب حتى يُعرض Adyen. اتركه فارغًا لعرض Adyen مهما كان المبلغ.

حساب Adyen

تُنشأ مفاتيح API في Customer Area الخاصة بـ Adyen تحت Developers > API credentials (يتضمن القسم روابط إلى منطقة العميل للاختبار وأخرى للإنتاج). املأ المجموعتين من المفاتيح؛ ويحدد مفتاح Test mode أيهما يُستخدم.

Test mode: يستخدم بيئة الاختبار الخاصة بـ Adyen (دون أموال حقيقية). وعند التفعيل، تُرسل روابط الدفع والمبالغ المستردة إلى checkout-test.adyen.com باستخدام مفتاح API للاختبار. الافتراضي: مفعّل. أوقفه لاستقبال المدفوعات الفعلية. وطالما هو مفعّل، يرى العملاء في خطوة Confirm Order الرسالة Test mode: no real payment is taken.

Merchant account: اسم حساب التاجر في Adyen (وليس حساب الشركة)، مثل MyShopECOM. وعادةً ما يكون هو نفسه في منطقة العميل للاختبار وفي منطقة الإنتاج.

بيانات اعتماد الاختبار

تُستخدم طالما أن Test mode مفعّل.

Test API key: من منطقة العميل للاختبار: Developers > API credentials > بيانات الاعتماد > API key.

Test HMAC key: من منطقة العميل للاختبار: Developers > Webhooks > الـ webhook القياسي > HMAC key (سداسي عشري). حقل إلزامي: تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا.

بيانات اعتماد الإنتاج

تُستخدم عندما يكون Test mode معطّلًا.

Live API key: من منطقة العميل للإنتاج: Developers > API credentials > بيانات الاعتماد > API key.

Live HMAC key: من منطقة العميل للإنتاج: Developers > Webhooks > الـ webhook القياسي > HMAC key (سداسي عشري).

Live URL prefix: من منطقة العميل للإنتاج: Developers > API URLs، مثل 1797a841fbb37ca7-AdyenDemo من العنوان https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. يمكنك لصق عنوان URL كاملًا؛ وسيُستخرج منه البادئة عند الحفظ.

لا تُعرض مفاتيح API ومفاتيح HMAC المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح محفوظ، فعّل Clear the saved value on save أسفل الحقل، ثم انقر على Save.

Webhook

لا تُعلَّم الطلبات كمدفوعة إلا عبر الـ webhooks الخاصة بـ Adyen. في Customer Area (الاختبار والإنتاج)، انتقل إلى Developers > Webhooks وأضف Standard webhook باستخدام عنوان URL المعروض في Webhook URL في هذا القسم. على OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_adyen_gateway/webhook، وعلى OpenCart 4 يبدو هكذا: https://your-store/index.php?route=extension/wcp_adyen_gateway/payment/wcp_adyen_gateway.webhook. ويُنشأ من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. انسخ عنوان URL تمامًا كما تعرضه الإعدادات، لأن Adyen لا تتبع إعادة التوجيه. اختر طريقة JSON، وفعّل Generate HMAC key، وانسخ المفتاح إلى Test HMAC key أو Live HMAC key.

تحدد بيئة كل إشعار مفتاح HMAC المستخدم، ولا يُطبَّق الإشعار إلا على رابط دفع أُنشئ في البيئة نفسها وبحساب التاجر نفسه. ولا يؤكد إشعار الاختبار أبدًا دفعة فعلية. تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا برمز HTTP 401، ويعيد Adyen إرسالها لاحقًا. وبدون الـ webhook لا يحصل أي طلب على حالة.

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

تُضاف الأحداث الأخرى إلى ملاحظات الطلب. تُتجاهل الإشعارات الخاصة بطلب بلا حالة، عدا AUTHORISATION. أما الإشعارات التي لا تخص طلبًا من هذا المتجر، مثل زر الاختبار في Customer Area، فتُقبل وتُتجاهل. ويعمل الـ webhook أيضًا أثناء وضع الصيانة في المتجر، لأن OpenCart يسمح بمرور طلبات إضافات الدفع. وتضيف الإضافة في OpenCart 4 startup action لهذا الغرض.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا عندما تؤكد Adyen الدفعة بـ webhook AUTHORISATION موقّع، ويتطابق المبلغ والعملة مع الطلب. ولا تغيّر عودة العميل الطلب أبدًا. يسرد كل حقل أدناه حالات الطلبات الخاصة بك في OpenCart.

Order status after payment: الحالة التي يحددها webhook AUTHORISATION ناجح وموقّع. الافتراضي: قيد التنفيذ.

On hold (review) status: عدم تطابق في المبلغ أو العملة، أو فشل تحصيل طلب مدفوع، أو دفعة وصلت بعد أن تغيّرت حالة الطلب (مثل إلغائه). توضح ملاحظة السبب. الافتراضي: في انتظار الدفع، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Cancelled status: تُحدَّد عندما تلغي Adyen دفعة الطلب (CANCELLATION). الافتراضي: ملغي.

Refunded status: تُحدَّد بعد استرداد الدفعة بالكامل من صفحة الطلب. وإذا أبلغت Adyen بعد ذلك بفشل هذا الاسترداد، ينتقل الطلب إلى حالة المراجعة مع ملاحظة. الافتراضي: مسترد.

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تبقى سجلات دفعات Adyen (مراجع PSP وأحداث الـ webhook والمبالغ المستردة) محفوظة دائمًا، بحيث تظل الطلبات القديمة قابلة للاسترداد. الافتراضي: معطّل.

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

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر مفاتيح API ومفاتيح HMAC.

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

الدفع

في خطوة Payment Method يختار العميل وسيلة الدفع (الافتراضية Adyen). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to Adyen to complete the payment securely. وينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة رابط دفع Adyen بإجمالي الطلب وبعملة الطلب، وتوجّه العميل إلى صفحة الدفع الخاصة بـ Adyen. هناك يدفع العميل بأي وسيلة مفعّلة في حسابك لدى Adyen. ويُرسل بريد العميل الإلكتروني واسمه ودولة الفوترة (أو دولة المتجر) ولغة المتجر إلى Adyen، ويظهر الدفع باسم Order # متبوعًا برقم الطلب.

بعد الدفع يعود العميل إلى متجرك. والعودة في حد ذاتها لا تدفع الطلب: لا يُعلَّم الطلب كمدفوع إلا عندما تؤكده Adyen بـ webhook AUTHORISATION موقّع، ويتطابق المبلغ والعملة مع الطلب. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون. وإذا كان الـ webhook قد وصل بالفعل، يرى العميل صفحة نجاح الطلب في OpenCart مع العبارة Your payment with Adyen has been received. (أو Your payment with Adyen has been received and is being reviewed by the store. لطلب قيد المراجعة). وإذا ألغت Adyen الدفعة قبل ذلك، تعرض الصفحة Your Adyen payment was not completed. Please contact us about this order. وإذا لم يصل الـ webhook بعد، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by Adyen. Your order will be confirmed as soon as Adyen confirms the payment, and you will receive an e-mail. مع الزرين Check again وBack to checkout، وذلك للعميل الذي لم يُكمل الدفع.

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

في OpenCart 4 يختار العميل وسيلة الدفع بزر Choose في كتلة وسيلة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وعنوان الدفع اختياري في OpenCart 4: فمن دونه يُرسَل اسم العميل بوصفه اسم الدافع، ودولة عنوان الشحن (أو دولة المتجر) بوصفها الدولة. ويحتفظ OpenCart 4 بطلب واحد لصفحة الدفع ويحدّثه: فـ Back to checkout وConfirm Order جديد ينشئان رابط دفع جديدًا للطلب نفسه ويُبطلان السابق. وإذا أُغلق ذلك الطلب دون دفع في هذه الأثناء (مثلًا لأن Adyen ألغت الدفعة أو لأنك ألغيت الطلب)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. أعلى صفحة الدفع، ويدفع Confirm Order التالي طلبًا جديدًا. وإذا كان طلب صفحة الدفع قد دُفع مسبقًا لسلة مختلفة، يُعاد العميل إلى صفحة الدفع ويدفع طلبًا جديدًا. ويُعدّ أي تغيير في السلة، بما فيه الكمية الجديدة، سلةً جديدة تحتاج إلى دفعة خاصة بها.

إذا تعذّر إنشاء رابط الدفع، يبقى العميل في خطوة Confirm Order مع الرسالة Payment could not be initiated. Please try again or choose another payment method. ويُكتب السبب في السجل. وإذا كانت الإعدادات غير مكتملة، تكون الرسالة Payment gateway is not configured properly. Please contact the store administrator.

لا تتضمن الإضافة اشتراكات أو مدفوعات متكررة، ولا بطاقات محفوظة، ولا حقول بطاقات داخل الموقع (Drop-in أو Components)، ولا أزرار تحصيل أو إلغاء في OpenCart، ولا مصادقة أساسية للـ webhooks.

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

حالات الطلب

No status (missing order): أُرسل العميل إلى Adyen ولم يدفع، أو رُفضت الدفعة، أو لم تؤكد Adyen الدفعة بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط فلتر Order Status على Missing Orders.

Order status after payment (default Processing): تم تفويض الدفعة. تعرض ملاحظة المبلغ ومرجع PSP ووسيلة الدفع.

On hold (review) status (default Pending): أكدت Adyen مبلغًا أو عملة مختلفين عن إجمالي الطلب، أو فشل تحصيل، أو فشل استرداد كامل، أو وصلت الدفعة بعد أن تغيّرت حالة الطلب، مثل إلغائه. توضح الملاحظة ذلك. تحقّق من الدفعة في Customer Area، ثم أنجز الطلب أو استرد الدفعة. وتؤدي الدفعة الصحيحة لطلب قيد المراجعة بعد عدم تطابق إلى تعليمه كمدفوع.

Cancelled status (default Canceled): أُلغيت دفعة هذا الطلب في Adyen.

Refunded status (default Refunded): استُرد الدفع بالكامل عبر الإضافة. وتُحدَّد هذه الحالة عند إرسال المبلغ المسترد؛ وإذا أبلغت Adyen لاحقًا بفشل هذا الاسترداد، ينتقل الطلب إلى حالة المراجعة.

إذا وصلت دفعة ناجحة ثانية لطلب مدفوع بالفعل، مثل دفعة من رابط دفع قديم، فلن يتغير الطلب. وتطلب منك ملاحظة أن تتحقق في Customer Area من وجود خصم مكرر، وأن تسترده هناك إذا لزم الأمر. ويسري الأمر نفسه على السلة: بمجرد دفع أحد طلبات السلة، لا يُنشأ أي رابط دفع جديد لطلب آخر من السلة نفسها، ولا تمنح دفعة ما زالت تصل لذلك الطلب حالةً له؛ ويحصل الطلب المدفوع على الملاحظة.

في OpenCart 4 قد يحصل طلب غير مدفوع من صفحة الدفع على الحالة Voided، وهي الحالة التي يضبطها OpenCart 4 عندما يعود العميل إلى خطوة Confirm Order. وتعامل الإضافة هذا الطلب كطلب بلا حالة، ويؤكده أي دفع لاحق.

الملاحظات هي إدخالات في History الخاص بالطلب، ولا يراها العميل.

تبويب VibeFox Adyen Gateway

في Sales > Orders افتح طلبًا دُفع عبر Adyen. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض التبويب VibeFox Adyen Gateway الـ PSP reference مع الوسم Test mode لدفعات الاختبار، وPayment link، وMerchant account، وStatus الدفعة، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، وAdyen notes الخاصة بالطلب. ويظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

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

تعالج Adyen الاستردادات بشكل غير متزامن: يُضاف الطلب إلى سجل الاستردادات والملاحظات بالحالة received، وتصل النتيجة النهائية عبر الـ webhook REFUND أو REFUND_FAILED. ولا يُحسب الاسترداد الفاشل ضمن المبالغ المستردة. وعندما تبلغ المبالغ المُرسَلة للاسترداد قيمة الدفعة، ينتقل الطلب إلى Refunded status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا مثل تغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. وعند استخدام التحصيل اليدوي في Adyen، لا يمكن استرداد إلا الدفعات المحصّلة.

لا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Adyen. وتصل المبالغ المستردة المنفَّذة في Customer Area الخاصة بـ Adyen عبر الـ webhook وتُضاف إلى الملاحظات. ولا تتغير حالة الطلب تلقائيًا.

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

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

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

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

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

لا يظهر Adyen في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن إعدادات الوضع الحالي مكتملة: Merchant account، ومفتاح API ومفتاح HMAC لذلك الوضع، وفي وضع الإنتاج Live URL prefix. تسرد صفحة الإعدادات ما ينقص. وتحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت الدفعة لكن الطلب بقي بدون حالة: الـ webhook لا يعمل. في Customer Area للبيئة التي تستخدمها (الاختبار أو الإنتاج)، تحقق من وجود الـ webhook القياسي، ومن أن عنوان URL الخاص به هو بالضبط العنوان المعروض في Webhook URL، ومن أن الطريقة JSON. وتحقق من أن مفتاح HMAC الخاص بهذا الـ webhook موجود في الحقل المناسب (Test HMAC key أو Live HMAC key). ومع مفتاح HMAC غير صالح أو مفقود، ترد الإضافة برمز HTTP 401 ويعيد Adyen محاولة التسليم لاحقًا، فيحصل الطلب على حالته تلقائيًا بمجرد تصحيح المفتاح. ويوضح السجل أن توقيع HMAC غير صالح أو أن مفتاح HMAC غير مضبوط.

يرد الـ webhook بالرسالة [rejected] HMAC key not configured: مفتاح HMAC الخاص ببيئة الإشعار فارغ. الصقه في الإعدادات.

يرد الـ webhook بالرسالة [rejected] invalid HMAC signature: مفتاح HMAC يخص webhook آخر أو بيئة أخرى. وإذا كان توقيع عنصر واحد في دفعة خاطئًا، تُرفض الدفعة كلها.

يرد الـ webhook بالرسالة [rejected] busy, retry later: كان الطلب يُعالَج بتسليم آخر في اللحظة نفسها، أو فشلت المعالجة. تعيد Adyen محاولة الـ webhook تلقائيًا. والسبب موجود في السجل.

يعرض عنوان URL للـ webhook الرسالة [rejected] POST required في المتصفح: هذا أمر طبيعي. يقبل العنوان إشعارات من Adyen فقط.

تحذير مفتاح HMAC عند الحفظ: يجب أن يحتوي الحقل على مفتاح HMAC السداسي عشري من Customer Area. وقد حُفظت القيمة السابقة.

يرى العميل الرسالة Payment could not be initiated: انظر إلى حقل Log في صفحة الإضافة (الأخطاء تُسجَّل دائمًا). تحقق من مفتاح API وحساب التاجر، وفي وضع الإنتاج من بادئة عنوان URL للإنتاج.

يرى العميل الرسالة This payment method is not available. Please reload the checkout page.: لم تعد جلسة الدفع تطابق الطلب، أو أن وسيلة الدفع أُوقفت في هذه الأثناء. ينبغي للعميل إعادة تحميل صفحة الدفع.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Adyen Gateway. لم يطابق المبلغ أو العملة اللذان أكدتهما Adyen الطلب، أو فشل تحصيل، أو وصلت الدفعة بعد أن تغيّرت حالة الطلب.

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

يفشل الاسترداد: يعرض التبويب الرسالة القادمة من Adyen. ومع التحصيل اليدوي، لا يمكن استرداد إلا الدفعات المحصّلة. وإذا كان استرداد آخر للطلب قيد التنفيذ، فانتظر لحظة ثم أعد المحاولة.

للمطورين: قبل إنشاء رابط الدفع، تطلق الإضافة حدث OpenCart باسم adyg_payment_link_request مع بيانات الطلب والطلب نفسه.

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

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

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

Adyen علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ Adyen ولا معتمدة من قبلها.