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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

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

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

التثبيت

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

2. عند انتهاء الرفع انقر Configure، أو ابحث لاحقًا عن VibeFox Adyen Gateway في قائمة الوحدات وانقر Configure.

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

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

5. في منطقة عملاء Adyen (الاختبار والإنتاج) أضف webhook من نوع Standard بالعنوان الظاهر في قسم Webhook الخاص بالوحدة (انظر الإعدادات).

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

عند التثبيت تُنشئ الوحدة حالة الطلب Adyen payment on hold. تعرض PrestaShop وحدة دفع جديدة للعملات والدول ومجموعات العملاء النشطة في تلك اللحظة. راجعها وعدّلها من Payment > Preferences، ويجب تحديد الدول التي تضيفها لاحقًا هناك.

الإعدادات

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

Adyen

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند إتمام الطلب. الافتراضي: Pay securely via Adyen.

حساب Adyen

تُنشأ مفاتيح API في منطقة عملاء Adyen تحت Developers > API credentials. املأ المجموعتين من المفاتيح؛ ويحدد مفتاح Test mode المجموعة المستخدمة.

Test mode: يستخدم بيئة الاختبار لدى Adyen (دون أموال حقيقية). وعند التفعيل تُرسل روابط الدفع والاستردادات إلى checkout-test.adyen.com بمفتاح API للاختبار. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية. وطالما هو مفعّل يرى العملاء أسفل طريقة الدفع العبارة 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 من نوع Standard > HMAC key (سداسي عشري). مطلوب: تُرفض طلبات webhook التي لا توقيع صالح لها.

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

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

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

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

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

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

Clear saved secrets: حدد مفتاحًا وانقر Save لحذفه. والحقل الفارغ يُبقي القيمة المحفوظة.

Webhook

لا تُنشأ الطلبات إلا عبر webhooks من Adyen. في منطقة العملاء (الاختبار والإنتاج) انتقل إلى Developers > Webhooks وأضف Standard webhook بالعنوان الظاهر في Webhook URL في هذا القسم. مع الروابط الودية يبدو العنوان هكذا: https://your-shop/module/wcp_adyen_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات، لأن Adyen لا تتبع عمليات إعادة التوجيه. اختر تنسيق JSON، وفعّل Generate HMAC key، وانسخ المفتاح إلى Test HMAC key أو Live HMAC key.

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

تتعامل الوحدة مع هذه الأحداث:

تُضاف الأحداث الأخرى إلى ملاحظات الطلب. أما الإشعارات التي لا تخص سلة من سلال هذا المتجر، مثل زر الاختبار في منطقة العملاء، فتُقبل ويتم تجاهلها. ويعمل webhook أثناء وضع الصيانة في المتجر، ولا يتأثر بقيود الدول في متجرك.

متقدم

Order status after payment: حالة الطلب التي يضبطها webhook من نوع AUTHORISATION الناجح.

تذهب فروق المبلغ أو العملة وعمليات التحصيل الفاشلة دائمًا إلى Adyen payment on hold.

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

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

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

إتمام الطلب

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

بعد الدفع يعود العميل إلى متجرك. لا تُنشئ العودة طلبًا ولا تدفعه: لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Adyen ذلك عبر webhook الموقّع من نوع AUTHORISATION ويتطابق المبلغ والعملة مع السلة. وإذا وصل الـ webhook من قبل، يرى العميل صفحة تأكيد الطلب المعتادة مع العبارة 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 created as soon as Adyen confirms the payment, and you will receive an e-mail. مع الزرين Check again وBack to checkout، وذلك للعميل الذي لم يُكمل الدفع.

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

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

يستطيع المطورون تعديل طلب رابط الدفع عبر الخطاف actionAdygPaymentLinkRequest.

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

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

حالات الطلب

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

Payment accepted, Delivered or Adyen payment on hold: تمت الموافقة على الدفعة. وتتبع الحالة Order status after payment. وتُسجَّل الدفعة بمرجع PSP لدى Adyen كمعرّف للمعاملة، وتعرض ملاحظة المبلغ ومرجع PSP وطريقة الدفع.

Adyen payment on hold after payment: أكدت Adyen مبلغًا أو عملة تختلف عن إجمالي السلة (مثلًا عُدّلت السلة بعد بدء الدفع)، أو فشل التحصيل، أو وصلت الدفعة بعد إلغاء الطلب. وتشرح الملاحظة ذلك. تحقق من الدفعة في منطقة العملاء، ثم نفّذ الطلب أو استرد الدفعة.

Canceled: أُلغيت دفعة هذا الطلب في Adyen.

Refunded: استُرد المبلغ كاملًا عبر الوحدة.

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

كتلة الدفع عبر Adyen

تعرض صفحة الطلب كتلة Adyen payment تتضمن مرجع PSP ورابط الدفع وحساب التاجر والبيئة وحالة الدفع والمبلغ المدفوع والمسترد وشارة Test mode لدفعات الاختبار وسجل الاسترداد وAdyen notes: وهي الملاحظات التي تضيفها الوحدة إلى الطلب (تمت الموافقة على الدفعة، عدم تطابق المبلغ، دفعة مكررة، تحصيل، إلغاء، نتائج الاسترداد)، مرتبة من الأحدث إلى الأقدم. وهذه الملاحظات رسائل خاصة بالطلب؛ ولا تعرضها PrestaShop 8.2 و9 في مكان آخر من صفحة الطلب.

الاسترداد

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

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

لا تُنشئ الوحدة إشعارات دائنة. ولا تعيد أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب المال عبر Adyen. وتصل الاستردادات التي تتم في منطقة عملاء Adyen عبر webhook وتُضاف إلى الملاحظات. ولا تتغير حالة الطلب ولا الإشعارات الدائنة تلقائيًا.

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

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

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

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

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

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

مرّت الدفعة لكن لم يُنشأ طلب: الـ webhook لا يعمل. في منطقة عملاء البيئة التي تستخدمها (الاختبار أو الإنتاج) تحقق من وجود الـ webhook من نوع Standard، ومن أن عنوانه مطابق تمامًا للعنوان الظاهر في Webhook URL، ومن أن الطريقة JSON. وتحقق من أن مفتاح HMAC لذلك الـ webhook موجود في الحقل المناسب (Test HMAC key أو Live HMAC key). ومع مفتاح HMAC غير صالح أو مفقود ترد الوحدة بالرمز HTTP 401، وتعيد Adyen الإرسال لاحقًا، لذلك يُنشأ الطلب تلقائيًا بعد تصحيح المفتاح. يعرض السجل Webhook rejected: invalid HMAC signature أو أن مفتاح HMAC غير مُعدّ.

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

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

يعرض عنوان webhook في المتصفح [rejected] POST required in the browser: هذا طبيعي. يقبل العنوان إشعارات Adyen فقط.

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

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

الطلب في حالة Adyen payment on hold بعد الدفع: اقرأ الملاحظة على الطلب. المبلغ أو العملة اللذان أكدتهما Adyen لم يتطابقا مع السلة، أو فشل التحصيل، أو وصلت الدفعة بعد إلغاء. وقد يكون السبب أيضًا إعداد Order status after payment.

يفشل الاسترداد: يجب أن يكون للطلب مرجع PSP من Adyen، ويصل مع webhook من نوع AUTHORISATION. ويجب ضبط بيانات اعتماد البيئة التي تمت فيها الدفعة؛ وإلا تعرض الكتلة أن بيانات الاعتماد غير مُعدّة. ومع التحصيل اليدوي لا يمكن استرداد إلا الدفعات المحصَّلة.

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Adyen Gateway، واختر Uninstall. يُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذه الوحدة. إذا كان Delete data on uninstall مفعّلًا تُحذف إعدادات الوحدة وسجلات دفعات Adyen (مراجع PSP وأحداث webhook والاستردادات) والسجلات. وإذا كان معطّلًا تُحفظ كلها لإعادة التثبيت لاحقًا، فتظل الطلبات المدفوعة سابقًا قابلة للاسترداد. وتبقى حالة الطلب Adyen payment on hold دائمًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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