VibeFox Authorize.Net for WooCommerce — المساعدة

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: يجب أن تستخدم صفحة الدفع بروتوكول HTTPS. ترفض Accept.js العمل عبر HTTP العادي.

حساب Authorize.Net: تحتاج إلى API Login ID وTransaction Key وPublic Client Key لحسابك لدى Authorize.Net، وإلى Signature Key إذا كنت تستخدم webhook. ولحسابي الإنتاج (account.authorize.net) وبيئة الاختبار (sandbox.authorize.net) بيانات اعتماد مختلفة. وحسابات Authorize.Net متاحة للتجار في الولايات المتحدة وكندا والمملكة المتحدة وأوروبا وأستراليا ونيوزيلندا.

العملة: يجب أن تكون عملة المتجر من بين USD وCAD وCHF وDKK وEUR وGBP وNOK وPLN وSEK وAUD وNZD، ويجب أن يُسوّي حسابك لدى Authorize.Net بها. ولعملات أخرى تُخفى طريقة الدفع في صفحة الدفع.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل بيانات اعتماد حسابي بيئة الاختبار والإنتاج (راجع قسم الإعدادات). واضبط الـ webhook اختياريًا.

6. فعّل Enable/Disable، واختر Transaction type، ثم احفظ. اختبر دفعة في وضع بيئة الاختبار باستخدام البطاقة 4111 1111 1111 1111 وأي تاريخ انتهاء مستقبلي وأي رمز CVV، ثم ألغِ تحديد Sandbox mode.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Authorize.Net. وتحذّرك الصفحة فوق الحقول عندما لا يستخدم الموقع HTTPS (يعمل Accept.js في الصفحات المعتمدة على HTTPS فقط)، وعندما لا تكون عملة المتجر مدعومة (وتُخفى طريقة الدفع في صفحة الدفع حينها). وتعرض الصفحة حقول بيانات الاعتماد للوضع المحدد فقط.

عام

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

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

Description: النص الذي يظهر فوق نموذج البطاقة في صفحة الدفع. الافتراضي: Pay securely with your credit card via Authorize.Net.

بيانات اعتماد الواجهة البرمجية

في Merchant Interface الخاصة بـ Authorize.Net افتح Account > Settings > Security Settings. وضمن API Credentials & Keys انسخ API Login ID، وأنشئ Transaction Key وSignature Key. وضمن Manage Public Client Key انسخ Public Client Key. وتستخدم بيئة الاختبار والإنتاج بيانات اعتماد مختلفة.

Sandbox mode: Use the Authorize.Net sandbox (test transactions, no real charges). يبدّل نقطة الوصول للواجهة البرمجية وAccept.js ومجموعة بيانات الاعتماد أدناه. الافتراضي: مفعّل. ألغِ تحديده لاستقبال مدفوعات حقيقية.

Live API Login ID وSandbox API Login ID: API Login ID لحساب الإنتاج أو لحساب بيئة الاختبار.

Live Transaction Key وSandbox Transaction Key: Transaction Key لذلك الحساب.

Live Public Client Key وSandbox Public Client Key: المفتاح العام الذي يستخدمه Accept.js في المتصفح.

Live Signature Key وSandbox Signature Key: مطلوب فقط للـ webhook. يتحقق من الترويسة X-ANET-Signature في كل إشعار.

الدفع

Transaction type: كيفية تحصيل المبلغ من البطاقة. ينتهي التفويض بعد 30 يومًا.

Webhooks (موصى به)

بدون webhook يجب تحديث الطلبات التي يحجزها Fraud Detection Suite، أو التي تُحصَّل أو تُبطل في لوحة Authorize.Net، يدويًا. في Merchant Interface انتقل إلى Account > Settings > Business Settings > Webhooks وانقر Add Endpoint. استخدم عنوان URL الظاهر في هذا القسم من الإعدادات، ويبدو بالشكل https://your-site/wc-api/wc_authorizenet/. اختر الأحداث التالية:

أدخل Signature Key الخاص بالحساب في Live Signature Key أو Sandbox Signature Key. ويُرفض الـ webhook الذي لا يحمل توقيعًا صالحًا. ولكل إشعار تطلب الإضافة من Authorize.Net الحالة والمبلغ الحاليين للمعاملة قبل تغيير الطلب، فلا تغيّر الإشعارات المكررة شيئًا.

متقدم

Debug log: Log API requests and responses إلى WooCommerce > Status > Logs، والمصدر wcp_authorizenet_gateway. تُخفى المفاتيح ورموز البطاقات والبيانات الشخصية. الافتراضي: إيقاف.

Delete data on uninstall: Remove the settings and the Authorize.Net order meta when the plugin is deleted. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit Card) ويُدخل رقم البطاقة وتاريخ الانتهاء (MM/YY) ورمز الأمان (CVV) في صفحة الدفع. وفي وضع بيئة الاختبار يعرض النموذج تلميحًا ببطاقة الاختبار 4111 1111 1111 1111. وعند تقديم الطلب يستبدل Accept.js بيانات البطاقة برمز مؤقت لمرة واحدة في المتصفح. وحقول البطاقة لا تحمل أسماء نماذج، فلا يُرسل رقم البطاقة ولا CVV إلى خادمك أبدًا.

تُحصّل الإضافة المبلغ باستخدام الرمز عبر واجهة Authorize.Net البرمجية، بإجمالي الطلب وبعملة الطلب. ويُرسل عنوان الفوترة والبريد الإلكتروني وعنوان IP مع المعاملة للتحقق من العنوان ومرشحات الاحتيال. وإذا تمت الموافقة على الدفع ينتقل العميل إلى صفحة استلام الطلب، وتُفرَّغ السلة.

إذا رُفضت البطاقة يبقى العميل في صفحة الدفع، ويرى Payment failed: متبوعة بالسبب، مثل رفض البطاقة أو رمز أمان خاطئ أو بطاقة منتهية الصلاحية. ولا تُعرض أخطاء الإعدادات والواجهة البرمجية على العملاء: يرون رسالة عامة، وتذهب التفاصيل إلى ملاحظة الطلب والسجل. وإذا لم يتمكن المتجر من الوصول إلى Authorize.Net يرى العميل الرسالة Payment error: unable to connect to the payment gateway. Please try again.

ولا يُحصَّل الطلب المدفوع مرة ثانية عند تكرار تقديم النموذج أو تكرار الدفع للطلب نفسه. وتعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

لا تتضمن الإضافة بطاقات محفوظة أو ملفات تعريف للعملاء، ولا WooCommerce Subscriptions أو Pre-Orders، ولا eCheck/ACH أو Apple Pay أو Google Pay أو PayPal أو 3-D Secure، ولا تحصيلًا جزئيًا لتفويض، ولا تحويلًا تلقائيًا للعملات.

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

Order statuses

Processing or Completed: تم تحصيل المبلغ من البطاقة (Authorize and capture)، أو تم تحصيل تفويض. تضع WooCommerce الطلب في حالة «قيد التنفيذ»، أو «مكتمل» للطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل. وتعرض ملاحظة الطلب المبلغ ومعرّف المعاملة ورمز الموافقة ونوع البطاقة وآخر أربعة أرقام. ومعرّف المعاملة هو Trans ID الخاص بـ Authorize.Net.

On hold: الأموال مفوّضة فقط (Authorize only)، أو حجز Fraud Detection Suite المعاملة للمراجعة. وافق على المعاملة المحجوزة أو ارفضها من لوحة Authorize.Net؛ ومع webhook يُحدَّث الطلب تلقائيًا. ويُوضع الطلب في حالة «في الانتظار» أيضًا عندما يُبلغ webhook بتحصيل لا يطابق مبلغ الطلب.

Cancelled: أبلغ webhook بأن المعاملة رُفضت أو أُبطلت أو انتهت قبل دفع الطلب. وإذا حدث ذلك لطلب مدفوع، فلا تتغير حالته وتُضاف ملاحظة تحذير.

التحصيل

لطلب لديه تفويض، افتح الطلب واختر Capture payment (Authorize.Net) في إجراءات الطلب، ثم انقر زر التحديث. يُحصَّل إجمالي الطلب كاملًا مطروحًا منه الاستردادات، ويُعلَّم الطلب كمدفوع. وإذا فشل التحصيل يُعرض الخطأ ويُضاف إلى ملاحظات الطلب. ويمكنك أيضًا التحصيل من لوحة Authorize.Net؛ ومع webhook يُحدَّث الطلب تلقائيًا.

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Credit Card (يستخدم الزر عنوان طريقة الدفع لديك). ويُبطل الاسترداد لكامل مبلغ الطلب المعاملة أولًا إذا لم تُسوَّ بعد، أو التفويض الذي لم يُحصَّل. أما المعاملات المُسوّاة، عادةً بعد 24 ساعة، فيمكن استردادها كليًا أو جزئيًا. وقبل التسوية لا يمكن الاسترداد الجزئي: استرد المبلغ كاملًا لإبطال المعاملة، أو أعد المحاولة بعد التسوية. وإذا لم تقبل Authorize.Net الاسترداد تعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. وتُضاف عملية الاسترداد أو الإبطال الناجحة إلى ملاحظات الطلب.

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

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

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

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

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

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

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

Authorize.Net لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على API Login ID وTransaction Key وPublic Client Key. تحقق من أن عملة المتجر مدعومة؛ وتعرض صفحة الإعدادات تحذيرًا عندما لا تكون مدعومة.

تمت عملية الدفع لكن الطلب ما زال On hold: نوع المعاملة هو Authorize only (فحصّله بإجراء الطلب)، أو أن Authorize.Net حجزت المعاملة للمراجعة. وافق عليها أو ارفضها من لوحة Authorize.Net. ولتحديث هذه الطلبات تلقائيًا، اضبط الـ webhook: تحقق من أن عنوان الـ endpoint مطابق تمامًا للعنوان الظاهر في الإعدادات، ومن اختيار الأحداث الأربعة، ومن إدخال Signature Key للوضع الحالي.

Webhook answers webhooks are not configured: لم يُدخَل Signature Key لأي من الوضعين.

Webhook answers invalid signature: Signature Key يخص حسابًا أو وضعًا آخر. أنشئ Signature Key من جديد أو انسخه، وألصقه في حقل وضعه.

Webhook answers verification failed, retry later: تعذّر على المتجر قراءة المعاملة من الواجهة البرمجية لـ Authorize.Net. وتعيد Authorize.Net إرسال الإشعار.

The card form does not load or shows The secure card form (Accept.js) could not be loaded: يجب أن تستخدم صفحة الدفع HTTPS، وأن يكون Public Client Key وAPI Login ID للوضع الحالي صحيحين.

Payment error: the card could not be tokenized: لم يُرجع Accept.js رمزًا. وعلى العميل إعادة إدخال بيانات البطاقة والمحاولة مجددًا.

The customer sees a general error: افتح ملاحظات الطلب أو فعّل Debug log وراجع WooCommerce > Status > Logs، والمصدر wcp_authorizenet_gateway. وتُرفض العملة التي لا يدعمها الحساب من Authorize.Net.

A partial refund fails because the transaction is not settled yet: استرد المبلغ كاملًا لإبطال المعاملة، أو أعد المحاولة بعد التسوية، عادةً خلال 24 ساعة.

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

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

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

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