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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

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

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

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

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

التثبيت

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

OpenCart 3

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

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

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

4. أدخل بيانات اعتماد الحسابات التجريبية (sandbox) والإنتاجية (انظر الإعداد). يمكنك اختيارياً إعداد الـ webhook.

5. فعّل Enable/Disable، واختر Transaction type، ثم انقر على Save. اختبر عملية دفع في وضع sandbox باستخدام البطاقة 4111 1111 1111 1111 وأي تاريخ انتهاء مستقبلي وأي رمز CVV، ثم أوقف تفعيل Sandbox mode.

OpenCart 4

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

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

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

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

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

الإعداد

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Authorize.Net Gateway > Edit. تظهر الأقسام في الجهة اليسرى؛ يحفظ الزر Save أسفل القائمة الصفحة بأكملها. وفوق الإعدادات، تُظهر الصفحة تحذيراً عندما لا يستخدم المتجر بروتوكول HTTPS (يعمل Accept.js فقط على صفحات HTTPS)، وعندما لا تكون العملة الافتراضية للمتجر مدعومة من Authorize.Net، وعندما لا يحتوي الوضع الحالي على API Login ID أو Transaction Key أو Public Client Key (وعندئذ تُخفى طريقة الدفع عند الدفع)، وعندما لا يحتوي الوضع الحالي على Signature Key (وعندئذ تُعطَّل webhooks). وطالما أن وضع sandbox مفعّل، تعرض الصفحة Sandbox mode is on: test transactions, no real charges. ومن دون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

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

Authorize.Net

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order، أعلى نموذج البطاقة. الافتراضي: Pay securely with your credit card via Authorize.Net.

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

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

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

API credentials

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

Sandbox mode: يستخدم بيئة sandbox الخاصة بـ Authorize.Net (معاملات تجريبية، دون خصم مبالغ حقيقية). ويبدّل عنوان واجهة API وAccept.js ومجموعة بيانات الاعتماد المستخدمة في المدفوعات الجديدة. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية. وطالما هو مفعّل، يرى العملاء Sandbox mode: مع بطاقة الاختبار 4111 1111 1111 1111 أعلى نموذج البطاقة.

Sandbox API Login ID وLive API Login ID: معرّف API Login ID لحساب sandbox أو الحساب الإنتاجي.

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

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

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

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

Payment

Transaction type: طريقة خصم البطاقة. تنتهي صلاحية التفويض (authorization) بعد 30 يوماً.

Webhooks (recommended)

من دون webhooks، يجب تحديث الطلبات المحتجزة من Fraud Detection Suite، أو المحصّلة أو الملغاة في لوحة Authorize.Net، يدوياً. في Merchant Interface انتقل إلى Account > Settings > Business Settings > Webhooks وانقر على Add Endpoint، في حساب sandbox وفي الحساب الإنتاجي. استخدم عنوان URL المعروض في Endpoint URL ضمن هذا القسم. في OpenCart 3 يبدو على النحو التالي: https://your-store/index.php?route=extension/payment/wcp_authorizenet_gateway/webhook، وفي OpenCart 4 يبدو على النحو التالي: https://your-store/index.php?route=extension/wcp_authorizenet_gateway/payment/wcp_authorizenet_gateway.webhook، ويُبنى من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. انسخ عنوان URL تماماً كما تعرضه الإعدادات. اختر الأحداث التالية (مدرجة أيضاً في هذا القسم):

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

Orders

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

Order Status After Payment: تم خصم البطاقة (Authorize and capture، أو تحصيل لاحق). الافتراضي: Processing.

Authorized Status: Authorize only: المبالغ محجوزة وغير محصّلة بعد. يُعرض Capture payment في تبويب الطلب في هذه الحالة فقط. الافتراضي: Pending.

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

Canceled Status: رُفضت أو أُلغيت أو انتهت صلاحيتها في Authorize.Net دون دفع (webhook)، أو تم إلغاء التفويض من تبويب الطلب. الافتراضي: Canceled.

Refunded Status: يُعيَّن بعد استرداد كامل للدفعة (أو إلغاء معاملة مدفوعة) من تبويب الطلب. الافتراضي: Refunded.

Advanced

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

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

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

Import / Export

Export: ينقل Download JSON الإعدادات إلى ملف JSON. لا يتم تصدير Transaction Keys وSignature Keys.

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

الدفع

في خطوة Payment Method، يختار العميل طريقة الدفع (افتراضياً Credit Card). وفي خطوة Confirm Order، يرى العميل وصفك ويُدخل رقم البطاقة وتاريخ الانتهاء (MM/YY) ورمز الأمان (CVV) في النموذج أعلى زر التأكيد. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. يُحمَّل Accept.js من Authorize.Net فقط مع هذا النموذج. وعندما ينقر العميل على Confirm Order، يستبدل Accept.js بيانات البطاقة برمز لمرة واحدة داخل المتصفح. لا تملك حقول البطاقة أسماء نماذج، لذلك لا يُرسل رقم البطاقة ولا CVV أبداً إلى خادمك.

تخصم الإضافة الرمز عبر واجهة API الخاصة بـ Authorize.Net بقيمة إجمالي الطلب بعملة الطلب. ويُرسل عنوان الفوترة والبريد الإلكتروني وعنوان IP مع المعاملة للتحقق من العنوان ولفلاتر الاحتيال، ويُرسل رقم الطلب كرقم فاتورة. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Authorize.Net ذلك: إذا تمت الموافقة على المعاملة، يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويُفرَّغ سلة التسوق، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your card payment has been received. ومع Authorize only تعرض الصفحة Your card payment has been authorized. The amount will be charged when your order is processed. وإذا حجزت Fraud Detection Suite المعاملة، تظهر الرسالة Your payment is being reviewed. We will update your order as soon as the review is complete.

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

لا يُخصم الطلب مرتين أبداً بسبب النقر المزدوج أو تبويب ثانٍ أو إعادة الإرسال. ينشئ OpenCart 3 طلباً جديداً في كل مرة تُعرض فيها خطوة Confirm Order، لذلك قد يكون لسلة واحدة عدة طلبات (في OpenCart 4 قد يحتفظ طلب سابق أو تبويب متصفح ثانٍ بالسلة نفسها): فبمجرد دفع أحدها، لا يُخصم طلب آخر من السلة نفسها. يرى العميل This cart has already been paid with order #…. Please check your order history — do not pay again. أما المحاولة الثانية أثناء استمرار الأولى، فتعرض Your payment is already being processed. Please wait a moment and check your order history before trying again. وإذا تمت الموافقة على الدفعة لكن تعذّر تعيين حالة الطلب، يرى العميل Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. ثم يحصل الطلب على حالته من الدفعة المعتمدة في المحاولة التالية أو عبر الـ webhook، من دون خصم البطاقة مرة أخرى.

في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options. ويظهر نموذج البطاقة بعد ذلك في كتلة تأكيد الطلب أسفل صفحة الدفع، فوق Confirm Order. عنوان الدفع اختياري في OpenCart 4: فإن لم يُدخل، يُرسل عنوان الشحن إلى Authorize.Net بوصفه عنوان الفوترة. يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك بعد رفض البطاقة يدفع العميل الطلب نفسه. وإذا أُغلق ذلك الطلب في الأثناء (مثلاً ألغيته)، أو كان مدفوعاً بالفعل وتحتوي السلة الآن على عملية شراء جديدة، يعيد Confirm Order العميل إلى صفحة الدفع، ويدفع Confirm Order التالي طلباً جديداً. ويرى العميل أعلى صفحة الدفع Your previous order is closed (cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order. عندما يكون الطلب قد أُغلق، أو Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. عندما يكون قد دُفع لسلة سابقة. ويُعد أي تغيير في السلة، بما في ذلك الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

إذا لم يتطابق المبلغ المخصوم مع إجمالي الطلب، ينتقل الطلب إلى On Hold (Review) Status مع ملاحظة، وتُسجَّل الدفعة بالمبلغ الذي خُصم فعلاً.

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

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

Order statuses

No status (missing order): رُفضت البطاقة أو فشلت عملية الدفع. تظهر هذه الطلبات في Sales > Orders فقط عند ضبط المرشح Order Status على Missing Orders.

Order Status After Payment (default Processing): تم خصم البطاقة (Authorize and capture)، أو تم تحصيل تفويض. تعرض الملاحظة المبلغ، وTrans ID، ورمز التفويض، ونوع البطاقة، وآخر أربعة أرقام.

Authorized Status (default Pending): المبالغ مفوَّضة فقط (Authorize only). قم بتحصيلها قبل التنفيذ.

On Hold (Review) Status (default Pending): حجزت Fraud Detection Suite المعاملة للمراجعة، أو لا يتطابق المبلغ المخصوم مع إجمالي الطلب، أو لا يتطابق التحصيل الذي أبلغ عنه الـ webhook مع مبلغ الطلب. تشرح الملاحظة ذلك. وافق على المعاملة المحتجزة أو ارفضها في لوحة Authorize.Net؛ ومع webhooks يتحدّث الطلب تلقائياً.

Canceled Status (default Canceled): أبلغ الـ webhook أن المعاملة رُفضت أو أُلغيت أو انتهت صلاحيتها قبل دفع الطلب، أو ألغيت تفويضاً لم يُحصَّل. وإذا أُلغيت معاملة طلب مدفوع في لوحة Authorize.Net، فلا تتغير حالته وتُضاف ملاحظة تحذير.

Refunded Status (default Refunded): تم استرداد الدفعة بالكامل أو إلغاؤها عبر الإضافة.

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

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

VibeFox Authorize.Net Gateway tab

في Sales > Orders افتح طلباً مدفوعاً عبر Authorize.Net. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Authorize.Net Gateway الرقم Trans ID مع التسمية Sandbox لمدفوعات sandbox، وآخر Transaction type، وStatus للمعاملة، وCard ورمز التفويض، والمبالغ Charged / order / refunded، وزر التحصيل، ونموذج الاسترداد، وسجل الاسترداد، وAuthorize.Net notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة. يتطلب التحصيل والاسترداد صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups).

Capture

بالنسبة لطلب في Authorized Status، انقر على Capture payment في التبويب، ثم أكد Capture the authorized amount through Authorize.Net? يُحصَّل المبلغ المفوَّض ويحصل الطلب على Order Status After Payment. وإذا فشل التحصيل، يُعرض الخطأ ويُضاف إلى الملاحظات. يمكنك أيضاً التحصيل من لوحة Authorize.Net؛ ومع webhooks يتحدّث الطلب تلقائياً.

Refunds

في التبويب، أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختيارياً Reason (optional)، ثم انقر على Refund via Authorize.Net وأكد Refund this amount through Authorize.Net? This cannot be undone. يقوم استرداد المبلغ الكامل أولاً بإلغاء المعاملة إذا لم تكن قد سُوّيت بعد، أو إلغاء تفويض لم يُحصَّل. أما المعاملات المسوّاة، فعادةً بعد 24 ساعة، فيمكن استردادها كلياً أو جزئياً. قبل التسوية لا يمكن الاسترداد الجزئي: استرد المبلغ كاملاً لإلغاء المعاملة، أو حاول مجدداً بعد التسوية. تُنفَّذ عمليات الاسترداد بالمبلغ والعملة اللذين خصمهما Authorize.Net، لذلك بعد وجود فرق في المبلغ يمكنك استرداد ما دفعه العميل فعلياً فقط، لا إجمالي الطلب. وإذا لم يقبل Authorize.Net الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. وتُضاف عملية الاسترداد أو الإلغاء الناجحة إلى سجل الاسترداد والملاحظات. يؤدي الاسترداد الكامل إلى تعيين الطلب على Refunded Status (أو Canceled Status عند إلغاء تفويض فقط) دون إخطار العميل ودون إعادة المنتجات إلى المخزون، تماماً مثل تغيير الحالة يدوياً. ولا يغيّر الاسترداد الجزئي الحالة. وطالما أن المعاملة محتجزة للمراجعة، لا تُعرض عمليات الاسترداد.

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

لا ترد مرتجعات المنتجات في Sales > Returns أموالاً عبر Authorize.Net. والعمليات المستردة في لوحة Authorize.Net لا تُبلَّغ إلى المتجر: حدّث الطلب يدوياً.

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

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

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

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

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

لا يظهر الدفع بالبطاقة عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على API Login ID وTransaction Key وPublic Client Key. تعرض صفحة الإعدادات تحذيراً عند غياب أيٍّ منها. وتحقق من أن عملة العميل مدعومة، وأن عنوان الدفع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المحدد في الإعدادات.

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

استجابة الـ webhook: webhooks are not configured: لم يُدخل Signature Key لأي من الوضعين.

استجابة الـ webhook: invalid signature: إن Signature Key يعود إلى حساب آخر، أو أن مفتاحاً قد تغيّر في Authorize.Net. أنشئ Signature Key من جديد أو انسخه، ثم الصقه في حقل وضعه.

استجابة الـ webhook: mode mismatch: وُقّع الإشعار بمفتاح وضع معين، لكن الدفعة تمت في الوضع الآخر. تحقق من أن Signature Key الخاصين بـ sandbox والبيئة الحية لم يتبادلا مكانيهما.

استجابة الـ webhook: verification failed, retry later: لم يتمكن المتجر من قراءة المعاملة من واجهة Authorize.Net API، أو أن بيانات اعتماد وضع الدفع مفقودة. وسيعيد Authorize.Net محاولة التسليم.

استجابة الـ webhook: busy, retry later: كان الطلب يُحدَّث من طلب آخر في اللحظة نفسها، أو فشلت المعالجة. وسيعيد Authorize.Net محاولة التسليم. راجع الحقل Log لمعرفة السبب.

يعرض عنوان URL الخاص بالـ webhook الرسالة method not allowed في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Authorize.Net فقط.

يعرض نموذج البطاقة الرسالة 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 رمزاً. يجب على العميل إعادة إدخال بيانات البطاقة والمحاولة مجدداً.

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

يرى العميل خطأً عاماً: راجع الحقل Log في صفحة الإضافة؛ فالأخطاء تُكتب فيه دائماً. والعملة التي لا يدعمها الحساب يرفضها Authorize.Net.

يفشل الاسترداد الجزئي لأن المعاملة لم تُسوَّ بعد: استرد المبلغ كاملاً لإلغاء المعاملة، أو أعد المحاولة بعد التسوية، وعادةً خلال 24 ساعة.

يفشل الاسترداد أو التحصيل برسالة متعلقة بالوضع: تمت عملية الدفع في وضع sandbox أو الوضع الحي، ولم تُعيَّن API Login ID وTransaction Key لذلك الوضع. أدخلهما ثم أعد المحاولة.

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

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

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

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