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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبت ومفعّل. ترفض الإضافة التفعيل بدونه.

PHP: 8.0 أو أحدث.

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

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

التثبيت

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

2. انقر Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > Adyen > Manage، أو انقر Settings تحت اسم الإضافة في صفحة Plugins.

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

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

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

7. فعّل Enable/Disable. اختبر دفعة مع تفعيل Test mode، ثم ألغِ تحديده.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Adyen. وما دامت إعدادات الوضع الحالي غير مكتملة، تعرض الصفحة الرسالة Adyen is hidden at checkout until the test settings are complete (أو إعدادات الإنتاج)، وتسرد ما ينقص: Merchant account، ومفتاح API، ومفتاح HMAC، وفي وضع الإنتاج Live URL prefix. وعند الحفظ يُرفض مفتاح HMAC غير السداسي عشري، وبادئة عنوان URL للإنتاج التي تحتوي على أحرف غير الأحرف والأرقام والشرطات، برسالة خطأ، ويبقى الإدخال السابق كما هو.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Adyen.

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

حساب Adyen

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

Test mode: Use the Adyen test environment (no real money). عند التفعيل تُرسل روابط الدفع والاستردادات إلى checkout-test.adyen.com باستخدام مفتاح API الخاص بالاختبار. الافتراضي: مفعّل. ألغِ تحديده لاستقبال مدفوعات حقيقية.

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. يمكنك لصق العنوان كاملًا؛ تُستخرج البادئة منه عند الحفظ.

Webhook

لا يُعلَّم الطلب كمدفوع إلا عبر webhook من Adyen. في منطقة العملاء (الاختبار والإنتاج) انتقل إلى Developers > Webhooks وأضف webhook من نوع Standard بعنوان URL الظاهر في هذا القسم من الإعدادات. ويبدو بالشكل https://your-site/wc-api/adyg_adyen_webhook/. اختر صيغة JSON، وفعّل Generate HMAC key، وانسخ المفتاح إلى Test HMAC key أو Live HMAC key. وتحدد البيئة في كل إشعار مفتاح HMAC المستخدم. ويُرفض الـ webhook الذي لا يحمل توقيعًا صالحًا، وتعيد Adyen إرساله لاحقًا. وبدون الـ webhook تبقى الطلبات في حالة «بانتظار الدفع».

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

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

متقدم

Order status after payment: حالة الطلب التي تُضبط بعد الدفع الناجح، في تغيير واحد للحالة.

Debug log: Log API calls and webhook events إلى WooCommerce > Status > Logs، والمصدر wcp_adyen_gateway. تُسجَّل الأخطاء دائمًا. ولا تحتوي السجلات أبدًا على مفاتيح API أو HMAC ولا على البيانات الشخصية للعميل. الافتراضي: إيقاف.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Adyen) ويقدّم الطلب. تُنشئ الإضافة رابط دفع في Adyen بإجمالي الطلب بعملة الطلب، وتنقل العميل إلى صفحة الدفع الخاصة بـ Adyen. هناك يدفع العميل بأي طريقة مفعّلة في حسابك لدى Adyen. وتُرسل إلى Adyen بريد فوترة العميل واسمه وبلده ولغة المتجر، وتظهر الدفعة باسم Order # ورقم الطلب.

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

إذا رُفض الدفع يصبح الطلب «فشل»، ويمكن للعميل المحاولة مجددًا. وعندما يبدأ العميل دفعًا جديدًا للطلب نفسه، مثلًا من صفحة Pay for 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.

بالنسبة إلى العملات التي لا منازل عشرية لها، مثل JPY وKRW وIDR وVND، اضبط WooCommerce > Settings > General > Number of decimals على 0. وإلا يُقرَّب الإجمالي إلى وحدة صحيحة.

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

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

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

Order statuses

Pending payment: أُنشئ رابط الدفع ولم تؤكد Adyen الدفعة بعد. تعرض ملاحظة الطلب رابط الدفع والمبلغ والبيئة.

Processing, Completed or On Hold: تم تفويض الدفعة. تتبع الطلب الإعداد Order status after payment. وتعرض ملاحظة الطلب المبلغ ومرجع PSP وطريقة الدفع. ومعرّف المعاملة هو مرجع PSP الخاص بـ Adyen.

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

Failed: رُفضت الدفعة. ولا يغيّر الدفع المرفوض الطلبات المدفوعة أو المعلّقة أو الملغاة.

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

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

الاستردادات

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

الاستردادات التي تُجرى في منطقة العملاء في Adyen تصل عبر webhook وتُضاف إلى ملاحظات الطلب. ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce.

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

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

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

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

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

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

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

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

يرد الـ webhook برسالة busy، retry later: كان الطلب يُعالَج في الوقت نفسه بإرسال آخر. وستعيد Adyen إرسال الـ webhook تلقائيًا.

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

يرى العميل الرسالة Payment could not be initiated: افتح ملاحظات الطلب، أو فعّل Debug log وراجع WooCommerce > Status > Logs، والمصدر wcp_adyen_gateway. تحقق من مفتاح API وحساب التاجر، وفي وضع الإنتاج من بادئة عنوان URL للإنتاج.

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

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

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

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

إلغاء تفعيل الإضافة يُبقي جميع البيانات. للإزالة، ألغِ التفعيل ثم احذفها من صفحة Plugins. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالته. أما إعدادات البوابة والبيانات الخاصة بـ Adyen المحفوظة في الطلبات (مراجع PSP، وروابط الدفع، والأحداث المعالجة) فتُحذف فقط إذا كان Delete data on uninstall مفعّلًا، وإلا فتبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات معاملاتها.

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