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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

عملة المتجر: عملة بلد حساب 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. يعمل مفتاح واحد على نطاق واحد.

التثبيت

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

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

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

4. اختر Account country، وأدخل بيانات الاعتماد للاختبار وللإنتاج، واضبط الإشعارات في تطبيق MercadoPago الخاص بك إن رغبت (انظر الإعدادات).

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

عند التثبيت تنشئ الوحدة حالتين للطلب: Awaiting MercadoPago payment وMercadoPago payment on hold. تُسند PrestaShop وحدة الدفع الجديدة إلى البلدان النشطة وقت التثبيت. راجع عملات الوحدة وبلدانها ومجموعات عملائها في Payment > Preferences.

الإعدادات

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

عند الحفظ، لا تُحفظ بيانات الاعتماد التي لا تبدأ بالبادئة المتوقعة (TEST- لحقول الاختبار وAPP_USR- لحقول الإنتاج)، وتظهر الرسالة must start with … — the previous value was kept.. كما تسأل الوحدة MercadoPago عن بلد كل Access Token. فإذا تعذّر التحقق من رمز الوضع الحالي، أو كان الحساب في بلد غير مدعوم، أو لم يطابق البلد Account country، ظهر خطأ. وعندئذ تستخدم الوحدة بلد الحساب.

MercadoPago

Enable / Disable: Enable MercadoPago card payments يفعّل طريقة الدفع أو يوقفها. الافتراضي: off.

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

Description: النص الذي يظهر فوق حقول البطاقة عند الدفع. الافتراضي: Pay securely with your credit or debit card. Card data is sent directly to 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 عند الدفع. أوقفه لتحصيل البطاقات الحقيقية ببيانات الإنتاج. الافتراضي: on.

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

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

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

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

لا تُعرض رموز Access Token المحفوظة وسر الـ webhook مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

خيارات الدفع

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

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

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

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

تتعامل الوحدة مع حالات الدفع التالية في MercadoPago:

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

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

rejected, cancelled: رُفضت الدفعة أو أُلغيت. لا يُنشأ طلب؛ ويتلقى الطلب المنتظر الحالة Payment error.

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

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

Clear saved secrets: ضع علامة على Test Access Token أو Production Access Token أو Webhook secret signature ثم انقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

متقدم

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

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit or debit card (MercadoPago)) ويملأ حقول البطاقة: Card number وExpiry (MM/YY) وSecurity code وCardholder name. وحسب البلد والبطاقة، يختار العميل أيضًا Document type ويُدخل Document number، ويختار Card issuer وعدد Installments. وتأتي خيارات الأقساط والفوائد من MercadoPago لإجمالي السلة. ويعمل نموذج البطاقة مع السمتين Classic وHummingbird.

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

تنشئ الدفعة المعتمدة طلبًا مدفوعًا، ويرى العميل صفحة تأكيد الطلب مع Your card payment has been received. وتنشئ الدفعة قيد المراجعة طلبًا في Awaiting MercadoPago payment، وتعرض الصفحة MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. وإذا رُفضت دفعة قيد المراجعة لاحقًا، تعرض الصفحة Your MercadoPago payment was not completed. Please contact us about this order. ويعرض الطلب المعلّق Your payment is being reviewed. We will update your order as soon as the review is complete.

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

إذا لم ترد 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. ولا يُعاد خصم سلة لها طلب أبدًا؛ ويُوجَّه العميل إلى صفحة تأكيد ذلك الطلب.

يعمل عنوان الإشعار أثناء وضع الصيانة في المتجر، ولا يحجبه قيد البلدان في متجرك.

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

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

حالات الطلب

No order: رُفضت البطاقة، أو لم ترد MercadoPago بعد. لا يوجد سوى السلة.

Payment accepted: اعتمدت MercadoPago الدفعة، ويتطابق المبلغ والعملة مع السلة. تُسجَّل الدفعة بمعرّف دفعة MercadoPago كمعرّف للمعاملة، وتعرض ملاحظة معرّف الدفعة والبيئة وعدد الأقساط.

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

MercadoPago payment on hold: المبلغ المعتمد أو العملة يختلف عن السلة، أو أعادت MercadoPago حالة غير متوقعة. تشرح الملاحظة السبب. تحقّق من الطلب ثم أكمله أو استرد الدفعة.

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

Refunded: استُردّت الدفعة بالكامل من خلال الوحدة.

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

كتلة الدفع في MercadoPago

تعرض صفحة الطلب كتلة MercadoPago payment تتضمن معرّف الدفعة وحالتها والبيئة (شارة Test للدفعات التجريبية) والأقساط والمبلغ الذي حصّلته MercadoPago وإجمالي الطلب، والمبلغ المُسترد، وسجل الاستردادات، وملاحظات MercadoPago notes الخاصة بالطلب.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر MercadoPago.

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

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

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

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

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

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

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

تمت الدفعة لكن الطلب ما زال في Awaiting MercadoPago payment: لم يصل الإشعار. ترسل الوحدة عنوان الإشعار فقط عندما يكون لمتجرك عنوان عام (وليس 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: Access Token للبيئة التي تمت فيها الدفعة غير مُعدّ. أدخله؛ فستعيد 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 payment was received, but the order could not be completed automatically: حصّلت MercadoPago الدفعة، لكن PrestaShop لم يتمكن من إنشاء الطلب (مثلًا لأن الوحدة كانت معطّلة في تلك اللحظة). تحقّق من حقل Log في صفحة الوحدة: تُسجَّل الأخطاء دائمًا. يُطلب من العميل ألّا يدفع مرة أخرى؛ وستنشئ محاولة الدفع أو الإشعار التالي لتلك السلة الطلب دون خصم جديد.

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

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

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

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

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

MercadoPago علامة تجارية تخص مالكها. هذه الوحدة غير تابعة لـ MercadoPago ولا معتمدة من قِبلها.