Cómo configurar Mercado Pago: credenciales y webhook

Mercado Pago es la otra pasarela que puedes conectar a tu tienda para cobrar con tarjeta, PSE y saldo en cuenta. El proceso tiene tres etapas: crear y verificar la cuenta, crear una aplicación y copiar las credenciales, y configurar el webhook que le avisa a tu tienda cuando un pago cambia de estado. Aquí va cada una, en orden.

Tienly no está afiliado ni asociado con Mercado Pago. Cada comercio se registra directamente con la pasarela y usa sus propias credenciales. Las tarifas y los tiempos de liberación de dinero los define Mercado Pago.

Qué necesitas antes de empezar

• Tu documento de identidad.
• Datos de tu negocio y tu actividad económica.
• Una cuenta bancaria colombiana para retirar el dinero.
• Un correo y un celular a los que tengas acceso, para la verificación en dos pasos.

Importante: mientras tu cuenta no esté verificada, las credenciales de producción aparecen bloqueadas. No es un error de la plataforma: primero completa la verificación de identidad y los datos del negocio, y las credenciales se habilitan.

Etapa 1: crear y verificar tu cuenta

1. Regístrate en el sitio de Mercado Pago Colombia con tu correo.
2. Elige el tipo de cuenta. Si vas a vender de forma habitual, una cuenta de negocio es lo apropiado; te pedirán documentación acorde.
3. Completa la verificación de identidad subiendo tu documento y siguiendo la validación que te pidan.
4. Registra tu cuenta bancaria para poder retirar el dinero de tus ventas.
5. Activa la verificación en dos pasos. Ten el celular a mano: durante la creación de credenciales suele pedirte un código.

Etapa 2: crear tu aplicación en el panel de desarrollador

Mercado Pago no te entrega credenciales sueltas: las asocia a una aplicación, que es el registro que identifica tu integración. Necesitas crear una.

1. Inicia sesión en tu cuenta de Mercado Pago.
2. Ve al panel de desarrollador, en la sección Tus integraciones. También puedes llegar desde Configuración → Negocio → Integraciones.
3. Haz clic en Crear aplicación. Si ya tienes una, puedes reutilizarla.
4. Ponle un nombre reconocible, por ejemplo el nombre de tu tienda. Esto es solo para que tú la identifiques.
5. Elige el tipo de solución que corresponda a tu integración. Si no estás seguro de cuál seleccionar para tu tienda Tienly, escríbenos antes de crearla: el tipo de aplicación determina qué credenciales sirven.
6. Acepta los términos y completa el captcha para finalizar.

Etapa 3: copiar las credenciales

Al crear la aplicación, Mercado Pago te entrega dos juegos de credenciales:

Dentro de cada juego encontrarás:

• Public Key: la llave pública. Se usa del lado visible de la integración y puede aparecer en el navegador.
• Access Token: la llave que autoriza las operaciones y vincula los pagos con tu cuenta. Va únicamente en el servidor y es estrictamente secreta. En producción empieza por APP_USR-.
• Client ID y Client Secret: aparecen junto a las credenciales de producción y se usan en flujos que lo requieran.

Para copiarlas: entra a Tus integraciones, selecciona tu aplicación y ve a la sección de credenciales de producción o de prueba, según lo que necesites.

Ojo con el país. Las credenciales son específicas de la cuenta y del país. Si cambias la región de la cuenta o el titular, las credenciales cambian y tu integración deja de funcionar hasta que las actualices.

Etapa 4: pegar las credenciales en tu tienda

1. Entra al panel de administración de tu tienda Tienly.
2. Ve a [RUTA: Configuración → Pagos → Mercado Pago].
3. Selecciona el modo: pruebas o producción.
4. Pega la Public Key y el Access Token del mismo modo que seleccionaste.
5. Guarda y activa Mercado Pago como método de pago.

Copia y pega siempre, sin espacios al inicio ni al final. Y no mezcles: si estás en producción, ambas credenciales deben ser de producción.

Etapa 5: configurar el webhook

Qué hace

El webhook es la dirección a la que Mercado Pago le envía a tu tienda un aviso automático cada vez que ocurre algo relevante con un pago. Sin él, un pago aprobado puede quedar figurando como pendiente en tu panel aunque el dinero ya haya entrado.

Cómo configurarlo

1. Copia la URL de webhook que te entrega tu tienda Tienly en [RUTA: Configuración → Pagos → Mercado Pago]. Se ve parecida a https://tutienda.tienly.co/webhooks/mercadopago [PLACEHOLDER: reemplazar por la URL real].
2. En el panel de desarrollador, entra a Tus integraciones y selecciona tu aplicación.
3. En el menú lateral elige Webhooks → Configurar notificaciones.
4. Verás dos pestañas: modo de prueba y modo productivo. Configura la URL en la que corresponda; lo ideal es hacerlo en ambas.
5. Pega la URL HTTPS completa.
6. Selecciona los eventos de los que quieres recibir notificaciones. Si no sabes cuáles marcar para tu tienda, escríbenos.
7. Haz clic en Guardar configuración.
8. Copia la clave secreta que se genera al guardar. Es exclusiva de esa aplicación y sirve para validar que las notificaciones vienen realmente de Mercado Pago. Pégala en tu tienda en el campo correspondiente.

No te saltes el último paso. La clave secreta se genera después de guardar la configuración del webhook. Mucha gente configura la URL, sale de la pantalla y luego no entiende por qué su tienda rechaza las notificaciones.

Esa clave no tiene fecha de caducidad y no estás obligado a renovarla, aunque hacerlo de vez en cuando es una buena práctica de seguridad.

Simulador de notificaciones

En la misma pantalla de configuración, Mercado Pago ofrece un simulador que te permite enviar una notificación de prueba a tu URL sin necesidad de hacer una compra real. Es la forma más rápida de confirmar que tu tienda está recibiendo y respondiendo bien.

Etapa 6: probar antes de vender

1. Usa primero las credenciales de prueba y haz una compra completa desde tu tienda.
2. Envía una notificación desde el simulador y verifica que tu tienda la recibe.
3. Confirma que el pedido queda registrado y que su estado cambia solo, sin que tú lo toques.
4. Prueba también un pago rechazado: necesitas saber qué ve el cliente cuando falla.
5. Cambia a producción, actualiza credenciales y webhook, y haz una compra real de monto bajo con tu propia tarjeta.

Para desarrolladores: validar el header x-signature

Si usas Tienly, esto ya está resuelto y no tienes que hacer nada. Esta sección es para quien construye su propia integración.

Cada notificación llega con un header x-signature, que contiene la firma que permite comprobar su autenticidad. Para validarla:

1. Divide el contenido del header por comas para obtener sus elementos.
2. El valor con prefijo ts es el timestamp de la notificación en milisegundos; el valor con prefijo v1 es la firma cifrada.
3. Construye la cadena a firmar con el formato que indica la documentación oficial, usando el identificador que llega en los query params, el header de identificación de la petición y el timestamp.
4. Calcula el HMAC SHA-256 de esa cadena usando como llave la clave secreta de tu aplicación.
5. Compara el resultado con el valor v1. Si no coincide, descarta la petición.

El formato exacto de la cadena y los SDK con ejemplos completos están en la documentación oficial de Mercado Pago para desarrolladores, y conviene consultarla directamente porque la mantienen actualizada.

Dos advertencias prácticas: las notificaciones IPN son un mecanismo anterior que Mercado Pago ha indicado que será descontinuado y que no permite esta validación por clave secreta, así que si todavía las usas conviene migrar a Webhooks. Y haz tu endpoint idempotente: puedes recibir varias notificaciones del mismo pago.

Errores comunes

Seguridad de tus credenciales

• El Access Token da control sobre tus cobros. Nunca lo publiques, ni lo pongas en el navegador, ni lo mandes por WhatsApp o correo.
• La Public Key sí puede ser visible: está diseñada para el lado público.
• Si necesitas que alguien te ayude con la integración, Mercado Pago permite compartir credenciales de forma segura desde el panel, con otra cuenta de Mercado Pago, en vez de enviárselas por chat. Los permisos se pueden quitar después.
• Renueva tus credenciales periódicamente y actualiza la integración dentro de la ventana en la que las antiguas siguen activas.
• Mantén activa la verificación en dos pasos.

Preguntas frecuentes

¿Mercado Pago y Mercado Libre son lo mismo?

No. Mercado Libre es un marketplace donde publicas productos y compites con otros vendedores; Mercado Pago es la pasarela que procesa cobros dentro de tu propia tienda. Para conectar pagos a tu tienda necesitas Mercado Pago.

¿Por qué no me aparecen las credenciales de producción?

Porque la cuenta todavía no está verificada. Completa la verificación de identidad y los datos del negocio, y se habilitan automáticamente.

¿Tengo que crear una aplicación obligatoriamente?

Sí. Las credenciales están vinculadas a una aplicación dentro de tu cuenta; sin crearla, no hay credenciales que copiar.

¿Dónde consigo la clave secreta del webhook?

Se genera automáticamente cuando guardas la configuración de notificaciones de tu aplicación. Cópiala en ese momento y pégala en tu tienda.

¿Puedo tener Wompi y Mercado Pago al mismo tiempo?

Sí. Puedes configurar ambas y también seguir recibiendo pedidos por WhatsApp con pago contra entrega. Entre más opciones de pago le des al cliente, menos ventas pierdes.

¿Cuánto cobra Mercado Pago por transacción?

La tarifa la define Mercado Pago y varía según el método de pago y el plazo de liberación del dinero. Consúltala en su sitio oficial antes de fijar tus precios. Tienly no cobra ninguna comisión adicional sobre tus ventas.

Sigue leyendo: Cómo crear tu cuenta de Wompi y configurar las llaves · Cómo crear una tienda online en Colombia