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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. بدون WooCommerce لا تُفعَّل الإضافة.

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. ويعمل المفتاح الواحد على نطاق واحد.

التثبيت

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

2. انقر Activate.

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

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

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

6. فعّل Enable / Disable واحفظ. اختبر ببطاقات اختبار MercadoPago (اسم حامل البطاقة APRO = معتمدة، وCONT = قيد الانتظار، وOTHE = مرفوضة)، ثم ألغِ تحديد Test mode.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > MercadoPago. وتعرض الصفحة فوق الحقول رسالة Test mode is on: the TEST- credentials are used and no real money is charged. طالما أن وضع الاختبار مفعّل. وتحذّرك عندما تكون بيانات اعتماد الوضع الحالي ناقصة، أو عندما لا تكون عملة المتجر هي عملة حساب MercadoPago (وعندئذ تُخفى طريقة الدفع في صفحة الدفع)، وعندما تنتمي بيانات الاعتماد إلى حساب في بلد غير Account country. وفي قائمة طرق الدفع يُعرض MercadoPago على أنه بحاجة إلى إعداد حتى يحصل الوضع الحالي على بيانات اعتماده.

عند الحفظ، لا تُحفظ بيانات الاعتماد التي لا تبدأ بالبادئة المتوقعة (TEST- لحقول الاختبار، وAPP_USR- لحقول الإنتاج): تظهر رسالة خطأ ويبقى القيمة السابقة. وتسأل الإضافة MercadoPago أيضًا عن البلد الذي ينتمي إليه Access Token. وإذا تعذّر التحقق من الرمز، أو لم يكن الحساب في بلد مدعوم، أو اختلف البلد عن Account country، تظهر رسالة خطأ. وعندئذ تستخدم الإضافة بلد الحساب.

عام

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

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: Use the test credentials (no real charges). في وضع الاختبار تُستخدم بيانات اعتماد TEST-، وتدفع ببطاقات اختبار MercadoPago، ويظهر شارة TEST MODE في صفحة الدفع. ألغِ التحديد لتحصيل المبالغ من بطاقات حقيقية ببيانات اعتماد الإنتاج. الافتراضي: مفعّل. ولاختبار الإضافة بحساب مستخدم اختبار في MercadoPago (بيانات اعتماد APP_USR-)، أدخل بيانات اعتماد ذلك الحساب في حقول الإنتاج وأوقف وضع الاختبار.

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

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

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

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

خيارات الدفع

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

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

تحصل مدفوعات البطاقات عادةً على رد نهائي فورًا. أما المدفوعات التي تحتفظ بها MercadoPago قيد المراجعة (قيد المعالجة أو قيد الانتظار)، فتكتمل بإشعارات من MercadoPago. وترسل الإضافة عنوان URL الخاص بالإشعارات مع كل دفعة عندما يكون لموقعك عنوان عام. ويمكنك أيضًا إضافته في your application > Webhooks، بالحدث Payments. ويظهر عنوان URL في هذا القسم من الإعدادات بالشكل التالي: https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

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

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

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

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

rejected, cancelled: رُفضت الدفعة أو أُلغيت. يُعلَّم الطلب غير المدفوع بأنه فشل.

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

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

متقدم

Debug log: Log API requests and notifications يكتب في WooCommerce > Status > Logs، بالمصدر wcp_mercadopago_gateway. ولا تُسجَّل في السجل رموز الوصول Access Token ولا رموز البطاقات ولا بيانات الدافع. الافتراضي: معطّل.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. تُعد معرّفات دفعات MercadoPago المحفوظة على الطلبات جزءًا من سجل المدفوعات، ولا تُحذف أبدًا. الافتراضي: معطّل.

الدفع

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

عند تقديم الطلب، تحوّل MercadoPago البطاقة إلى رمز لمرة واحدة، وينشئ متجرك الدفعة على الخادم بإجمالي الطلب. وتُرسل إلى MercadoPago البريد الإلكتروني للفوترة والاسم، والمستند، ورقم الطلب. وتُحصَّل مبالغ CLP وCOP بدون منازل عشرية ويُقرَّب إلى عدد صحيح، لذلك اضبط عدد المنازل العشرية في WooCommerce على 0 لهذه العملات.

يُعلَّم الدفع المعتمد كمدفوع فورًا، وينتقل العميل إلى صفحة استلام الطلب. ويضع الدفع قيد المراجعة الطلب في حالة قيد الانتظار؛ وينتقل العميل أيضًا إلى صفحة استلام الطلب، ويكتمل الطلب بالإشعار. ويعرض البطاقة المرفوضة سببًا موجزًا في صفحة الدفع، مثل 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 وصفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

حالات الطلب

Pending payment: تم إنشاء الطلب، ولم يصل بعد أي نتيجة دفع، على سبيل المثال بعد انتهاء المهلة.

Processing: وافقت MercadoPago على الدفعة، ويطابق المبلغ والعملة. أما الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط، فتصبح مكتملة، وهو السلوك الافتراضي لـ WooCommerce. وتعرض ملاحظة الطلب معرّف دفعة MercadoPago وعدد الأقساط. ومعرّف المعاملة هو معرّف دفعة MercadoPago.

On hold: الدفعة قيد المراجعة (قيد المعالجة أو قيد الانتظار) وتنتظر إشعار MercadoPago. ويُعيَّن الطلب أيضًا إلى قيد الانتظار عندما يختلف المبلغ أو العملة المعتمدة عن الطلب، أو عندما تعيد MercadoPago حالة غير متوقعة. وتوضح ملاحظة الطلب السبب.

Failed: رُفضت الدفعة أو أُلغيت. وتعرض ملاحظة الطلب الحالة وتفاصيلها. ويمكن للعميل الدفع مرة أخرى.

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

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Credit or debit card (MercadoPago) (يعرض الزر قيمة Title الخاصة بك). وتُدعم الاستردادات الكاملة والجزئية. ويُرسل الاسترداد ببيانات اعتماد البيئة التي تمت فيها الدفعة (الاختبار أو الإنتاج)، لذلك يجب تعيين Access Token لتلك البيئة. وإذا رفضت MercadoPago الاسترداد، يعرض WooCommerce الرسالة MercadoPago refused the refund مع السبب، ولا يُسجَّل أي استرداد. ويُضاف الاسترداد المعتمد أو الجاري معالجته إلى ملاحظات الطلب مع معرّف الاسترداد.

تصل الاستردادات والـ chargebacks التي تُجرى من لوحة MercadoPago عبر الإشعار، وتُضاف إلى ملاحظات الطلب. ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce.

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

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

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

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

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

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

MercadoPago does not appear at checkout: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يملك بيانات الاعتماد الاثنتين بالبادئة الصحيحة: مفاتيح TEST- في وضع الاختبار، ومفاتيح APP_USR- في وضع الإنتاج. وتحقق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي عملة حساب MercadoPago الخاص بك. وتوضح صفحة الإعدادات ما هو الناقص.

The payment went through, but the order stays On hold or Pending payment: تمت الدفعة، لكن الطلب يبقى قيد الانتظار أو في حالة الدفع المعلّق: لم يصل الإشعار. ولا ترسل الإضافة عنوان URL للإشعارات إلا عندما يكون لموقعك عنوان عام (وليس localhost أو نطاقًا من نوع .local أو .test). أضِف عنوان URL من الإعدادات في your application > Webhooks مع الحدث Payments. وإذا كان Webhook secret signature مُعيّنًا، فتحقق من أنه السر الخاص بالتطبيق نفسه. وتعرض لوحة MercadoPago رد متجرك على كل إشعار.

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

Notification answers not for this store: الدفعة لا تخص طلبًا في هذا المتجر دُفع عبر MercadoPago. ولا يُعدَّل الطلب.

A credential is not saved: تُظهر الرسالة must start with أن القيمة لها بادئة خاطئة للحقل. تقبل حقول الاختبار بيانات اعتماد TEST-، وتقبل حقول الإنتاج بيانات اعتماد APP_USR-.

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

The customer sees MercadoPago cannot process payments in: عملة الطلب ليست عملة حساب MercadoPago الخاص بك. ولا تحوّل MercadoPago العملات.

The secure card form does not load: يرى العميل الرسالة The secure card form could not be loaded. Please reload the page or choose another payment method. تحقق من Public Key للوضع الحالي. ولمزيد من التفاصيل، فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_mercadopago_gateway.

Refund fails with a message about the mode: تمت الدفعة في وضع الاختبار أو وضع الإنتاج، ولم يُعيَّن Access Token لذلك الوضع. أدخله ثم أعد المحاولة.

Refund fails with MercadoPago did not answer the refund request: تحقق من الدفعة في لوحة MercadoPago قبل إعادة المحاولة.

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

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

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

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