Pantalla de monitor mostrando un panel de administración de comercio electrónico con una sección de configuración de métodos de pago moderna y limpia,
Conectar Mercado Pago con Magento permite ofrecer los métodos de pago que más se usan en México dentro de tu tienda en línea. Esta guía cubre desde los requisitos previos hasta las pruebas finales, con énfasis en errores reales que pueden frenar tu integración.
Integrar Mercado Pago en Magento requiere tres acciones concretas: instalar el módulo oficial vía Composer, configurar las credenciales de API (Access Token y Public Key) en el panel de administración y activar los métodos de pago que quieres ofrecer. El proceso es compatible con Magento Open Source y Adobe Commerce en versiones 2.4.4 o superiores.
A lo largo de este artículo encontrarás los requisitos previos que debes tener listos, los comandos de instalación del módulo, la configuración de credenciales y métodos de pago, las pruebas en ambiente sandbox y —como punto diferenciador frente a otras guías— un apartado dedicado a errores reales que pueden bloquear tu integración en producción y cómo diagnosticarlos.
Espacio de trabajo ordenado con una laptop abierta mostrando credenciales de API en la pantalla, junto a documentos técnicos y una taza de café, ilumi
Qué necesitas antes de integrar Mercado Pago en Magento
Antes de ejecutar cualquier comando o tocar el panel de administración, conviene tener todo en orden. Estos son los requisitos indispensables:
- Cuenta activa en Mercado Pago con datos personales y fiscales completos.
- Magento 2.4.4 o superior, ya sea Open Source o Adobe Commerce.
- Acceso de administrador al panel de Magento con permisos de edición.
- Acceso SSH o Composer al servidor donde está instalada la tienda.
- Credenciales de API: Access Token y Public Key, obtenidas desde el panel de desarrollador de Mercado Pago.
Para obtener tus credenciales, entra a tu cuenta de Mercado Pago y ve a la sección de desarrollo o panel de desarrollador. Ahí encontrarás dos conjuntos de credenciales: uno para el entorno de pruebas (sandbox) y otro para producción. Lo recomendable es comenzar con las de sandbox durante la configuración inicial.
Cómo instalar el módulo de Mercado Pago en Magento paso a paso
El módulo oficial de Mercado Pago para Magento se instala a través de Composer, el gestor de dependencias que Magento utiliza de forma nativa. A continuación se describen los comandos y las verificaciones necesarias.
Instalación con Composer desde la terminal
Conéctate al servidor vía SSH y ejecuta los siguientes comandos en el orden indicado:
- composer require mercadopago/adb-payment — descarga el módulo y sus dependencias.
- bin/magento module:enable MercadoPago_AdbPayment — habilita el módulo dentro de Magento.
- bin/magento setup:upgrade — registra el módulo en la base de datos de Magento.
- bin/magento setup:di:compile — compila las dependencias de inyección para que el módulo funcione con el resto de la tienda.
- bin/magento cache:flush — limpia la caché para que los cambios sean visibles en el panel.
Cada comando debe completarse sin errores antes de ejecutar el siguiente. Si alguno devuelve un aviso de permisos, verifica que el usuario del servidor tenga acceso de escritura sobre los directorios de Magento.
Verificación de que el módulo quedó activo
Una vez ejecutados los comandos, entra al panel de administración de Magento y navega a Stores > Configuration > Sales > Payment Methods. Ahí debería aparecer la sección de Mercado Pago con sus opciones de configuración.
Si el módulo no aparece, los motivos más comunes son permisos de archivo incorrectos o que el comando setup:upgrade no se ejecutó con éxito. En ese caso, vuelve a ejecutar los pasos 3 y 4 y repite el flush de caché.
Configuración de credenciales y métodos de pago en Magento
Una vez que el módulo está activo, el siguiente paso es conectar tu cuenta de Mercado Pago con Magento y elegir qué métodos de pago ofrecer a quienes compren en tu tienda.
Ingreso de credenciales en el panel de administración
Desde el panel de Magento, ve a Stores > Configuration > Sales > Payment Methods > Mercado Pago. Verás campos para ingresar el Access Token y la Public Key. Pega cada credencial con cuidado: un espacio en blanco al inicio o al final puede causar errores de autenticación que son difíciles de detectar a simple vista.
Usa primero las credenciales de sandbox. Esto te permite probar el flujo completo sin procesar transacciones reales. Solo cuando las pruebas sean exitosas, reemplaza estos valores por las credenciales de producción.
Activación de métodos de pago disponibles
El módulo permite activar distintas formas de cobro según las necesidades de tu tienda:
- Tarjetas de crédito y débito: Visa, Mastercard, American Express.
- Pagos en efectivo: OXXO y 7-Eleven.
- Transferencias bancarias: SPEI.
- Saldo en cuenta de Mercado Pago.
- Pagos en cuotas: hasta 15 MSI en artículos seleccionados.
Además, el módulo ofrece dos modalidades de checkout. El Checkout Pro redirige a quien compra hacia el sitio de Mercado Pago para completar el pago; el Checkout Transparente procesa el pago dentro de tu tienda sin redirección. La segunda opción suele generar menor fricción en el proceso de compra, aunque requiere una configuración más cuidadosa para cumplir con los estándares de seguridad.
Vista cercana de una terminal de comandos en pantalla oscura con líneas de código ejecutándose, rodeada de un ambiente de desarrollo moderno con ilumi
Pruebas en ambiente sandbox antes de salir a producción
Activar la integración sin pruebas previas es uno de los errores más comunes en proyectos de ecommerce. El entorno sandbox de Mercado Pago permite simular transacciones completas sin mover dinero real, lo que da la oportunidad de detectar problemas antes de que lleguen a tus clientes.
Para comenzar, crea usuarios de prueba desde el panel de desarrollador de Mercado Pago. Con esos usuarios, realiza una compra completa en tu tienda usando las tarjetas de prueba que Mercado Pago proporciona en su documentación. El objetivo es verificar que el estado del pedido en Magento se actualice de forma correcta según el resultado del pago.
Prueba al menos tres escenarios distintos: pago aprobado, pago rechazado y pago pendiente. Cada uno debería generar un estado de orden diferente en Magento. Si todos los pedidos quedan en el mismo estado sin importar el resultado, hay un problema en el mapeo de estados que debes resolver antes de salir a producción.
Una vez que los tres escenarios funcionen como se espera, reemplaza las credenciales de sandbox por las de producción y desactiva el modo de prueba desde la configuración del módulo.
Errores frecuentes al integrar Mercado Pago en Magento y cómo resolverlos
Muchas guías describen los pasos de instalación, pero pocas explican qué hacer cuando algo no funciona. Esta sección cubre los problemas más comunes que surgen durante y después de la integración.
Los errores que con mayor frecuencia bloquean la integración son:
- Credenciales inválidas o copiadas con espacios: verifica que no haya caracteres extra al inicio o al final, y que las credenciales correspondan al entorno correcto (sandbox para pruebas, producción para transacciones reales).
- El módulo no aparece en el panel tras la instalación: revisa los permisos de archivos en el servidor y vuelve a ejecutar setup:upgrade y setup:di:compile. Un error silencioso en alguno de estos pasos puede dejar el módulo registrado de forma incompleta.
- Los webhooks no notifican cambios de estado del pago: verifica que la URL de notificación configurada en el panel de Mercado Pago sea accesible desde internet y que el servidor permita conexiones entrantes desde las IPs de Mercado Pago. Un firewall mal configurado puede bloquear estas notificaciones sin generar un error visible.
- Pedidos que quedan como "pendiente" aunque el pago fue aprobado: este problema suele originarse en el mapeo de estados del módulo. Revisa la configuración de correspondencia entre los estados de Mercado Pago y los estados de orden de Magento.
- Conflictos con extensiones de terceros o temas personalizados: desactiva las extensiones adicionales una por una para identificar cuál genera el conflicto. Los temas con modificaciones en el checkout son una fuente habitual de incompatibilidades.
Ante cualquier comportamiento inesperado, los registros de Magento en var/log son el primer lugar donde buscar. La documentación oficial de Mercado Pago Developers también incluye códigos de error con su descripción, lo que puede ahorrar horas de diagnóstico.
Preguntas frecuentes sobre la integración de Mercado Pago en Magento
¿Qué versiones de Magento son compatibles con el módulo de Mercado Pago?
El módulo oficial es compatible con Magento 2.4.4 o versiones superiores. Aplica tanto para Magento Open Source como para Adobe Commerce. Si tu tienda corre sobre una versión anterior, deberás actualizar Magento antes de proceder con la integración.
¿Se puede usar Checkout Transparente y Checkout Pro a la vez?
Por lo general, se elige uno como método principal dentro de la configuración del módulo. El Checkout Pro redirige a quien compra hacia el sitio de Mercado Pago, mientras que el Checkout Transparente procesa el pago dentro de la tienda. La elección depende del nivel de control y la experiencia de compra que quieras ofrecer.
¿Cuánto cobra Mercado Pago por transacción en México?
La comisión puede variar según el tipo de operación y el volumen de ventas de tu tienda. Para conocer las tarifas vigentes, lo más conveniente es consultar la página oficial de Mercado Pago, ya que estos valores se actualizan con regularidad y pueden diferir según el método de pago utilizado.
¿Cómo se prueban los pagos antes de activar la tienda?
Debes usar las credenciales de sandbox y crear usuarios de prueba desde el panel de desarrollador de Mercado Pago. Con esas cuentas, simula pagos aprobados, rechazados y pendientes para verificar que el flujo completo funcione antes de recibir transacciones reales.
Para quienes quieran profundizar en opciones avanzadas —como personalización del checkout, webhooks con lógica propia o integración con sistemas de facturación—, la documentación de Mercado Pago Developers ofrece referencias técnicas detalladas para cada escenario. Además, la app de Mercado Pago permite monitorear las transacciones de tu tienda en tiempo real, lo que facilita el seguimiento de pagos y la detección de incidencias sin necesidad de entrar al panel de Magento cada vez.
¡Aplican restricciones! Consulta más información sobre productos y promociones en: https://mpago.li/2MdeJDh