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

المتطلبات

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

PHP: ‏8.0 أو أحدث.

عملة المتجر: يجب تفعيل عملة بلد حساب MercadoPago الخاص بك في المتجر: ARS (الأرجنتين)، أو BRL (البرازيل)، أو CLP (تشيلي)، أو COP (كولومبيا)، أو MXN (المكسيك)، أو PEN (بيرو)، أو UYU (الأوروغواي). تقوم MercadoPago بالتحصيل بعملة الحساب دون تحويل العملات، لذلك لا يظهر طريقة الدفع إلا للعملاء الذين يدفعون بتلك العملة.

حساب MercadoPago: تحتاج إلى تطبيق في لوحة مطوري MercadoPago (Your integrations > your application > Credentials) مع بيانات اعتماده التجريبية (تبدأ بـ TEST-) وبيانات اعتماد الإنتاج (تبدأ بـ APP_USR-): مفتاح Public Key ورمز Access Token لكل منهما. وللتحقق الاختياري من توقيع الإشعارات تحتاج أيضًا إلى التوقيع السري من your application > Webhooks.

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

التثبيت

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

OpenCart 3

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

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

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

4. اختر Account country، وأدخل بيانات الاعتماد التجريبية والإنتاجية، ويمكنك اختياريًا إعداد الإشعارات في تطبيق MercadoPago الخاص بك (راجع الإعداد). تأكد من تفعيل عملة الحساب في System > Localisation > Currencies.

5. فعّل Enable / Disable واضغط Save. جرّب دفعة في وضع الاختبار باستخدام بطاقات الاختبار الخاصة بـ MercadoPago، ثم أوقف Test mode.

OpenCart 4

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

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

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

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

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

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox MercadoPago Gateway > Edit. تظهر الأقسام في الجهة اليسرى، ويحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات تعرض الصفحة Test mode is on: the TEST- credentials are used and no real money is charged. طالما كان وضع الاختبار مفعّلًا. وتحذرك عندما يكون مفتاح Public Key أو رمز Access Token للوضع الحالي مفقودًا (وفي هذه الحالة تُخفى طريقة الدفع عند الدفع)، وعندما تختلف عملة المتجر الافتراضية عن عملة حساب MercadoPago الخاص بك (وفي هذه الحالة تُعرض الطريقة فقط للعملاء الذين يدفعون بعملة الحساب، أو تُخفى إذا لم تكن تلك العملة مفعّلة في المتجر)، وعندما تنتمي بيانات الاعتماد إلى حساب في بلد غير Account country. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

إذا حفظت والحقل Title فارغ (أو أطول من 128 حرفًا)، فلن يُحفظ شيء وتعرض الصفحة Enter a title for the payment method (1 to 128 characters). وأي قيمة خاطئة أخرى لا تُحفظ وتبقى قيمتها السابقة، مع رسالة خطأ تسمّي الحقل وتنتهي بـ — the previous value was kept. ينطبق هذا على بيانات اعتماد لا تبدأ بالبادئة المتوقعة (TEST- لحقول الاختبار، وAPP_USR- لحقول الإنتاج)، وعلى Maximum installments خارج النطاق 1–24، وعلى Sort Order الذي ليس عددًا صحيحًا (Sort Order must be a whole number)، وعلى Total الذي ليس رقمًا أكبر من أو يساوي 0، وعلى منطقة جغرافية أو حالة طلب غير موجودة. وبعد الحفظ تسأل الإضافة MercadoPago عن البلد الذي ينتمي إليه كل رمز وصول. إذا تعذّر التحقق من الرمز الخاص بالوضع الحالي، أو لم يكن الحساب في بلد مدعوم، أو اختلف البلد عن Account country، يظهر تحذير. وعندها تستخدم الإضافة بلد الحساب.

MercadoPago

Enable / Disable: Enable MercadoPago card payments يفعّل طريقة الدفع أو يعطّلها. تظهر الطريقة عند الدفع فقط عندما تكون بيانات اعتماد الوضع النشط مُدخلة ويدفع العميل بعملة حساب MercadoPago. الافتراضي: معطّل.

Title: اسم طريقة الدفع الذي يراه العميل عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit or debit card (MercadoPago). مطلوب، حتى 128 حرفًا.

Description: النص الذي يظهر فوق حقول البطاقة في خطوة Confirm Order. الافتراضي: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

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

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

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

حساب MercadoPago

احصل على بيانات اعتماد تطبيقك من لوحة مطوري MercadoPago: Your integrations > your application > Credentials (تحتوي الصفحة على رابط يوصلك إليها). تبدأ بيانات الاعتماد التجريبية بـ TEST-، وبيانات الاعتماد الإنتاجية بـ APP_USR-.

Account country: بلد حساب MercadoPago الخاص بك. يحدد العملة المحصّلة، ولغة حقول البطاقة، وما إذا كانت وثيقة حامل البطاقة مطلوبة. يجب أن يدفع العميل بالعملة نفسها، مثل ARS للأرجنتين. عند حفظ بيانات الاعتماد يُتحقق من البلد مقابل الحساب. الافتراضي: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): البلدان المدعومة. يظهر حقل الوثيقة لجميعها باستثناء المكسيك.

Test mode: في وضع الاختبار تُستخدم بيانات الاعتماد TEST- وتدفع ببطاقات الاختبار الخاصة بـ MercadoPago؛ وتظهر شارة TEST MODE عند الدفع مع النص Use MercadoPago test cards. No real charges.. أوقفه لتحصيل المبالغ من بطاقات حقيقية باستخدام بيانات اعتماد الإنتاج. تستخدم عمليات الاسترداد والإشعارات دائمًا بيانات اعتماد الوضع الذي تمت فيه الدفعة. الافتراضي: مفعّل.

Test Public Key: يبدأ بـ TEST-. يُستخدم في المتصفح لترميز البطاقة.

Test Access Token: يبدأ بـ TEST-. يُستخدم على الخادم فقط. احتفظ به سرًا.

Production Public Key: يبدأ بـ APP_USR-.

Production Access Token: يبدأ بـ APP_USR-. يُستخدم على الخادم فقط. احتفظ به سرًا.

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

خيارات الدفع

Maximum installments: أعلى عدد من الأقساط (cuotas أو parcelas) يمكن للعميل اختياره، من 1 إلى 24. ‏1 = دفعة واحدة فقط. يُطبَّق الحد أيضًا على الخادم. الافتراضي: 1.

إشعارات الدفع (webhooks)

تحصل المدفوعات بالبطاقة عادةً على رد نهائي فورًا. أما المدفوعات التي تحتفظ بها MercadoPago للمراجعة (قيد المعالجة أو معلّقة) فتكتمل عبر إشعارات MercadoPago. ترسل الإضافة عنوان URL للإشعار مع كل دفعة عندما يكون لمتجرك عنوان عام (وليس localhost ولا نطاق .local أو .test). يمكنك أيضًا إضافته في your application > Webhooks لحدث Payments. يظهر العنوان في Notification URL في هذا القسم. في OpenCart 3 وهو بالشكل التالي: https://your-store/index.php?route=extension/payment/wcp_mercadopago_gateway/webhook&source_news=webhooks، وفي OpenCart 4 بالشكل التالي: https://your-store/index.php?route=extension/wcp_mercadopago_gateway/payment/wcp_mercadopago_gateway.webhook&source_news=webhooks، ويُبنى من عنوان واجهة المتجر لتثبيت OpenCart الخاص بك. انسخ العنوان تمامًا كما تعرضه الإعدادات.

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

تتعامل الإضافة مع حالات الدفع التالية من MercadoPago:

approved: تمت الموافقة على الدفعة. يُعلَّم الطلب كمدفوع عندما يتطابق المبلغ والعملة.

in_process, pending, authorized: الدفعة قيد المراجعة. ينتظر الطلب في Awaiting MercadoPago Status ويكتمل بإشعار لاحق.

rejected, cancelled: رُفضت الدفعة أو أُلغيت. يبقى الطلب الجديد بلا حالة؛ ويحصل الطلب الذي كان ينتظر على Payment Failed Status.

refunded, charged_back, in_mediation: تُضاف ملاحظة؛ ولا تتغير حالة الطلب.

Webhook secret signature: اختياري. التوقيع السري المعروض في your application > Webhooks. عند تعيينه تُرفض الإشعارات التي لا تحمل x-signature صالحًا (HTTP 401).

الطلبات

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

Order Status After Payment: وافقت MercadoPago على الدفعة، ويتطابق المبلغ والعملة مع الطلب. الافتراضي: قيد التنفيذ.

Awaiting MercadoPago Status: الدفعة قيد المراجعة لدى MercadoPago (قيد المعالجة أو معلّقة)؛ يكمل الإشعار الطلب. الافتراضي: قيد الانتظار.

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

Payment Failed Status: رفضت MercadoPago الدفعة التي كانت قيد المراجعة أو ألغتها. الافتراضي: فشل.

Cancelled Status: الطلب في هذه الحالة (أو في حالة الاسترداد) مغلق: الموافقة المتأخرة من MercadoPago تضيف ملاحظة فقط. الافتراضي: ملغي.

Refunded Status: يُسترد الدفع بالكامل من صفحة الطلب. الاسترداد الجزئي يضيف ملاحظة فقط. الافتراضي: مُسترد.

متقدم

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

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

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

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

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا يتم تصدير رموز الوصول والسر الخاص بالـ webhook.

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit or debit card (MercadoPago)). ينشئ OpenCart الطلب في خطوة Confirm Order، ولا يزال بلا حالة. هناك يرى العميل وصفك ويملأ حقول البطاقة: Card number، وExpiry (MM/YY)، وSecurity code، وCardholder name. وحسب البلد والبطاقة، يختار العميل أيضًا Document type ويدخل Document number، ويحدد Card issuer وعدد Installments. تأتي خيارات الأقساط والفوائد من MercadoPago لإجمالي الطلب.

في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، داخل النافذة Payment method options. تظهر حقول البطاقة بعد ذلك في كتلة تأكيد الطلب أسفل صفحة الدفع، فوق زر Confirm Order.

عندما يضغط العميل Confirm Order، تحوّل MercadoPago البطاقة إلى رمز يُستخدم مرة واحدة، ويُنشئ متجرك الدفعة على الخادم بمبلغ إجمالي الطلب بعملة الطلب. يُرسل البريد الإلكتروني للعميل واسمه والوثيقة إلى MercadoPago؛ وتظهر الدفعة بالعبارة Order # ورقم الطلب واسم متجرك. تُحصَّل المبالغ بالـ CLP والـ COP دون كسور عشرية.

تضبط الدفعة المعتمدة حالة الطلب بالطريقة القياسية في OpenCart، مع رسائل البريد المعتادة للطلب وتحديث المخزون؛ ويُفرَّغ سلة التسوق ويرى العميل صفحة نجاح الطلب في OpenCart. أما الدفعة قيد المراجعة فتضبط Awaiting MercadoPago Status، وتعرض الصفحة أيضًا MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. ويعرض الطلب في حالة المراجعة Your payment is being reviewed. We will update your order as soon as the review is complete.

تترك البطاقة المرفوضة الطلب بلا حالة. يبقى العميل في خطوة Confirm Order مع سبب موجز، مثل Your card has insufficient funds. Please use another card or payment method. أو Please check the security code of your card. يمكن للعميل تصحيح البيانات أو استخدام بطاقة أخرى؛ ويُنشأ رمز جديد للبطاقة مع كل محاولة. وإذا كانت بيانات البطاقة ناقصة فتظهر Please fill in all card fields.

إذا لم تردّ MercadoPago، يرى العميل We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. تبحث المحاولة التالية أولًا عن الدفعة، حتى لا تُخصم البطاقة مرتين. أما النقرة الثانية أثناء دفع السلة فتعرض This order is already being paid. Please wait a moment and check your e-mail before trying again. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، أما OpenCart 4 فيُبقي طلب الدفع نفسه ويدفع العميل الطلب نفسه بعد البطاقة المرفوضة. وفي الحالتين، فالسلة التي لديها طلب مدفوع أو قيد الانتظار لا تُحصَّل منها الدفعة مرة أخرى؛ ويُوجَّه العميل إلى صفحة النجاح.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تظهر صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please reload the checkout page and confirm the order again — the payment will be made with a new order. وإذا كان الطلب قد تم تقديمه بالفعل وتغيّرت السلة منذ ذلك، فالرسالة هي Your previous order has already been placed. Your cart has changed since — please reload the checkout page and confirm the order again to pay for the current cart with a new order. ويُحسب تغيير السلة، بما فيه الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص.

يعمل عنوان URL للإشعار أيضًا عندما يكون المتجر في وضع الصيانة، : يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة في OpenCart 4 startup action يسمح بمرور الإشعار وعودة العميل.

لا تقبل الإضافة سوى بطاقات الائتمان والخصم. ليس فيها تحويل إلى Checkout Pro، ولا محفظة MercadoPago أو رصيد الحساب، ولا الدفع النقدي (Rapipago وOXXO وboleto وغيرها)، ولا Pix أو PSE أو Yape، ولا البطاقات المحفوظة أو الاشتراكات، ولا التفويض والتحصيل المنفصلان، ولا تحدي 3-D Secure، ولا تحويل العملات.

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

حالات الطلب

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

Order Status After Payment (الافتراضي قيد التنفيذ): وافقت MercadoPago على الدفعة، ويتطابق المبلغ والعملة مع الطلب. تعرض ملاحظة رقم الدفعة والبيئة وعدد الأقساط.

Awaiting MercadoPago Status (الافتراضي قيد الانتظار): الدفعة قيد المراجعة (قيد المعالجة أو معلّقة) وتنتظر إشعار MercadoPago. ينتقل الطلب إلى Order Status After Payment عندما توافق عليه MercadoPago.

On Hold (Review) Status (الافتراضي قيد الانتظار): المبلغ أو العملة المعتمدة تختلف عن الطلب، أو أعادت MercadoPago حالة غير متوقعة. تشرح الملاحظة ذلك. تحقق من الطلب ثم أكمله أو استرد الدفعة.

Payment Failed Status (الافتراضي فشل): رُفضت دفعة قيد المراجعة أو أُلغيت. تعرض الملاحظة الحالة وتفاصيلها.

Refunded Status (الافتراضي مُسترد): استُردت الدفعة بالكامل عبر الإضافة.

إذا وافقت MercadoPago على دفعة لطلب ملغى أو مُسترد أصلًا، فلن تتغير الحالة، وستطلب منك ملاحظة إكمال الطلب أو استرداد الدفعة. وإذا وصلت دفعة أخرى لطلب أو سلة مدفوعة بالفعل، فستطلب منك ملاحظة استرداد الدفعة الزائدة في لوحة MercadoPago.

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

تبويب VibeFox MercadoPago Gateway

في Sales > Orders افتح طلبًا دُفع عبر MercadoPago. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox MercadoPago Gateway الحقول: Payment ID، وStatus للدفعة، وEnvironment (تسمية Test لدفعات الاختبار)، وInstallments، والمبالغ Charged / order، والمبلغ Refunded، ونموذج الاسترداد، وسجل عمليات الاسترداد، وMercadoPago notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

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

لا ترجع مرتجعات المنتجات في Sales > Returns أموالًا عبر MercadoPago.

تصل عمليات الاسترداد والاستردادات المحجوزة (chargebacks) والوساطات التي تتم في لوحة MercadoPago عبر الإشعار وتُضاف إلى الملاحظات. لا تتغير حالة الطلب تلقائيًا. حدّثها يدويًا عند الحاجة.

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

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

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

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

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

MercadoPago لا تظهر عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على بيانات الاعتماد الاثنتين بالبادئة الصحيحة: مفاتيح TEST- في وضع الاختبار، ومفاتيح APP_USR- في الإنتاج. تحقق من أن العميل يدفع بعملة حساب MercadoPago الخاص بك (يجب أن تكون العملة مفعّلة في المتجر)، ومن أن عنوان الدفع ضمن Geo Zone المحددة، ومن أن الطلب يبلغ Total المحدد في الإعدادات. تُخبرك صفحة الإعدادات بما هو ناقص.

تمت الدفعة لكن الطلب يبقى في Awaiting MercadoPago Status: لم يصل الإشعار. ترسل الإضافة عنوان URL للإشعار فقط عندما يكون لمتجرك عنوان عام (وليس localhost ولا نطاق .local أو .test). أضف العنوان من Notification URL في your application > Webhooks مع الحدث Payments. وإذا كان Webhook secret signature مُعيّنًا، فتحقق من أنه السر الخاص بالتطبيق نفسه. تعرض لوحة MercadoPago رد متجرك على كل إشعار.

يرد الإشعار بـ invalid signature: التوقيع السري يخص تطبيقًا آخر، أو أن الإشعار لا يحمل x-signature صالحًا. انسخ السر من جديد أو اترك الحقل فارغًا.

يرد الإشعار بـ no credentials for test أو no credentials for live: رمز الوصول لبيئة الدفعة غير مُعيّن. أدخله؛ وستعيد MercadoPago إرسال الإشعار.

يرد الإشعار بـ not for this store: الدفعة لا تنتمي إلى محاولة دفع لهذا المتجر. لا يُعدَّل أي طلب.

يرد الإشعار بـ order busy أو payment could not be read: كان الطلب يُحدَّث بطلب آخر في اللحظة نفسها، أو تعذّر الوصول إلى MercadoPago. تعيد MercadoPago إرسال الإشعار تلقائيًا.

لا تُحفظ بيانات اعتماد: يشير الخطأ must start with إلى أن القيمة لها بادئة خاطئة لهذا الحقل. تقبل الحقول التجريبية بيانات TEST-، والحقول الإنتاجية بيانات APP_USR-.

يرى العميل «This payment method is not configured correctly. Please choose another payment method or contact the store.»: بيانات اعتماد الوضع الحالي مفقودة، أو ذات بادئة خاطئة، أو رفضتها MercadoPago. تحقق منها في صفحة الإعدادات.

يرى العميل «MercadoPago cannot process payments in»: عملة الطلب ليست عملة حساب MercadoPago الخاص بك. لا تحوّل MercadoPago العملات.

نموذج البطاقة الآمن لا يُحمَّل: يرى العميل The secure card form could not be loaded. Please reload the page or choose another payment method. تحقق من Public Key للوضع الحالي.

يرى العميل «Your session has expired. Please reload the page and try again.»: نموذج البطاقة لم يعد يخص جلسة الدفع الخاصة بالعميل. يعيد العميل تحميل صفحة الدفع.

يرى العميل «Your payment was received, but the order could not be completed automatically»: حصّلت MercadoPago الدفعة، لكن OpenCart لم يتمكن من ضبط حالة الطلب. انظر إلى حقل Log في صفحة الإضافة: تُسجَّل الأخطاء دائمًا. يُطلب من العميل ألا يدفع مرة أخرى؛ ومحاولة الدفع أو الإشعار التالي للسلة يضبط الحالة دون تحصيل جديد.

الطلب في حالة المراجعة بعد الدفع: اقرأ MercadoPago notes في تبويب الطلب (راجع حالات الطلب)، ثم أكمل الطلب أو استرد الدفعة.

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

يفشل الاسترداد بـ MercadoPago did not answer the refund request: تحقق من الدفعة في لوحة MercadoPago قبل إعادة المحاولة.

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

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

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

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