Cómo integrar Mercado Pago en tu app (2026): Checkout Pro, Bricks y webhooks que no mienten

¿Cómo se integra Mercado Pago de verdad (y dónde das acceso)?

Te lo digo de entrada, igual que en mi post de Stripe: el pago es asíncrono y el redirect del navegador es solo experiencia de usuario. La fuente de verdad es el webhook firmado. Integras Mercado Pago creando una preferencia del lado del servidor, redirigiendo al comprador al Checkout Pro alojado y, cuando MP te avisa por webhook, validas el header x-signature, consultas el pago por su id, confirmas que el status sea approved y solo entonces das acceso. Nunca antes.

He cableado esto en productos reales para el mercado mexicano: en Mercanto, el marketplace B2B donde un comprador podía pagar con SPEI una factura grande, y en Nixbly. Y aprendí a las malas que si confías en el back_url de éxito, tarde o temprano alguien llega a tu página de “gracias” sin que el dinero haya caído todavía, sobre todo con OXXO. Por eso este post existe.

Mercado Pago es la pasarela que domina México y LATAM. Eso no es opinión: es dónde está la confianza del consumidor y dónde ya vienen integrados los métodos locales que de verdad mueven la conversión aquí (MSI, OXXO, SPEI, wallet). Si quieres el panorama completo de proveedores, escribí la comparativa en pasarelas de pago en México.

Tienes tres formas de integrarlo, de más administrado a más control: Checkout Pro, Checkout Bricks y la Checkout API (Checkout Transparente). Las desgloso abajo. Pero la columna vertebral es la misma para las tres, y es la parte que más bugs previene: el flujo crear-preferencia → redirect → webhook → verificar → dar acceso. Si esa espina dorsal está bien, te ahorras la mayoría de los errores de doble cobro o de acceso falso.

Checkout Pro, Checkout Bricks o Checkout API: ¿cuál deberías elegir?

La decisión se reduce a cuánto control de UX necesitas contra cuánto esfuerzo y cuánto alcance de PCI estás dispuesto a cargar.

Checkout Pro es el más administrado. Creas una preferencia del lado del servidor, obtienes un init_point y rediriges al comprador a la página alojada de MP. Mercado Pago se encarga de mostrar todos los métodos de pago y de todo el alcance PCI. Es el más rápido de montar y el de menor responsabilidad PCI. Para una tienda B2C o un SaaS que solo quiere cobrar bien y rápido, es mi default sin pensarlo.

Checkout Bricks es el punto intermedio. Son componentes embebibles modulares que sueltas en tu propia página: Payment Brick, Card Payment Brick, Wallet Brick y Status Screen Brick. Tienes más control del look-and-feel y de dónde viven los campos, pero los campos sensibles siguen siendo administrados por MP. Es para cuando el equipo de diseño quiere un checkout con tu marca, dentro de tu dominio, sin construir el formulario de tarjeta desde cero.

Checkout API (Checkout Transparente / Core) te da control total: construyes toda la UI y creas los pagos del lado del servidor vía la API. A cambio cargas el mayor alcance PCI. Solo lo elegiría para un flujo de pago totalmente custom dentro de la app, donde la experiencia es el producto y tienes con qué cumplir PCI.

Mi recomendación, opinión clara: empieza con Checkout Pro a menos que tengas una razón concreta de UX para embeber. Si la tienes, Bricks antes que la Checkout API. No te cargues alcance PCI que no necesitas.

¿Cómo es el flujo de crear-preferencia a redirect (con código)?

Primero, las credenciales. Vas a “Tus integraciones” en el Developer Dashboard, creas la aplicación y de ahí sacas tus credenciales y tus usuarios de prueba para el sandbox. Usas el SDK oficial de servidor (mercadopago para Node) y, si embebes, el SDK de front (MercadoPago.js). Un detalle que ahorra horas de depuración: estos ejemplos usan el SDK mercadopago v2+ (importaciones por clase como MercadoPagoConfig, Preference, Payment); la API v1 (mercadopago.configure(...)) tiene otra sintaxis y no funciona con este código.

La preferencia se crea con el recurso Preference. Los campos que cargan el peso son items, back_urls (success/failure/pending) y notification_url. Ese último es el que conecta el webhook que va a darte la verdad después. Agrego también auto_return: "approved", que es lo que hace que MP regrese al comprador a tu success automáticamente cuando el pago se aprueba; sin él, el comprador puede quedarse en la pantalla de MP. Eso sí: el retorno sigue siendo solo UX, no concede nada.

// server.js — crear la preferencia y devolver el init_point
import { MercadoPagoConfig, Preference } from "mercadopago";

const client = new MercadoPagoConfig({ accessToken: process.env.MP_ACCESS_TOKEN });

export async function crearPreferencia(req, res) {
  const pref = await new Preference(client).create({
    body: {
      items: [
        { title: "Plan Pro", quantity: 1, unit_price: 499, currency_id: "MXN" },
      ],
      back_urls: {
        success: "https://tuapp.com/pago/exito",
        failure: "https://tuapp.com/pago/error",
        pending: "https://tuapp.com/pago/pendiente",
      },
      auto_return: "approved", // regresa al comprador a success cuando se aprueba (solo UX)
      // notification_url es lo que cablea el webhook (la fuente de verdad)
      notification_url: "https://tuapp.com/webhooks/mercadopago",
      external_reference: req.user.orderId, // para reconciliar de tu lado
    },
  });

  // Rediriges al comprador a este URL alojado por MP
  return res.json({ init_point: pref.init_point });
}

Ojo con algo clave: este redirect no concede nada todavía. El init_point solo lleva al comprador al checkout. Quien da acceso es el webhook. Por eso pones notification_url ahora, para que el evento dispare después. Si quieres entender por qué este patrón le gana al polling de la API, lo desarrollé en webhooks vs polling vs API.

¿Por qué el webhook verificado es la única fuente de verdad (valida x-signature, luego consulta)?

Esta es la sección que más importa, y es exactamente la misma disciplina que predico en cómo integrar Stripe en tu SaaS. Los webhooks nuevos de Mercado Pago reemplazan al viejo IPN. La notificación te llega con el payment id más el topic/type. Tu trabajo es no creerle a nadie hasta confirmar dos cosas: que la notificación es genuinamente de MP, y que el pago de verdad está aprobado.

Primero validas el header x-signature con un HMAC usando tu webhook secret. Si la firma no cuadra, descartas y respondes rápido. Si cuadra, recién entonces llamas a la Payments API para traer el pago por su id y verificar status === "approved". Nunca confíes en el redirect del navegador para esto. Un detalle que rompe firmas válidas en silencio: MP pide normalizar el data.id a minúsculas antes de armar el manifest, porque algunos ids llegan con mayúsculas y el HMAC no cuadraría aunque tu código se vea perfecto.

// webhook.js — validar x-signature, consultar el pago, dar acceso una sola vez
import crypto from "crypto";
import { MercadoPagoConfig, Payment } from "mercadopago";

const client = new MercadoPagoConfig({ accessToken: process.env.MP_ACCESS_TOKEN });
const SECRET = process.env.MP_WEBHOOK_SECRET;

export async function webhookHandler(req, res) {
  const sig = req.headers["x-signature"];      // ej: "ts=...,v1=..."
  const requestId = req.headers["x-request-id"];
  const id = String(req.query["data.id"]).toLowerCase(); // normalizar a minúsculas

  // 1) Reconstruir el manifest y validar el HMAC
  const parts = Object.fromEntries(sig.split(",").map((p) => p.split("=")));
  const manifest = `id:${id};request-id:${requestId};ts:${parts.ts};`;
  const hmac = crypto.createHmac("sha256", SECRET).update(manifest).digest("hex");
  if (hmac !== parts.v1) return res.sendStatus(401); // firma inválida: descartar

  // 2) Solo ahora consultar el pago por id en la Payments API
  const payment = await new Payment(client).get({ id });

  // 3) Dar acceso EXACTAMENTE UNA VEZ y solo si está aprobado
  if (payment.status === "approved") {
    await grantAccessOnce(payment.external_reference); // idempotente
  }

  // 4) Responder 2xx rápido para que MP no siga reintentando
  return res.sendStatus(200);
}

Tres detalles de disciplina que no son negociables. Uno: las notificaciones se reintentan, así que grantAccessOnce tiene que ser idempotente, das acceso exactamente una vez aunque MP te mande el mismo evento tres veces. Dos: responde 2xx rápido o MP seguirá reintentando y vas a ver duplicados. Tres: separa el trabajo pesado del ACK; confirma rápido y procesa aparte si hace falta.

¿Qué métodos de pago mexicanos obtienes (tarjetas, MSI, OXXO, SPEI, wallet)?

Aquí es donde Mercado Pago gana en México, y donde el patrón de webhook deja de ser teoría. Checkout Pro muestra estos métodos automáticamente:

• Tarjetas de crédito y débito, más MSI (meses sin intereses). Los MSI son la palanca de conversión más grande en carritos de ticket alto. En México, ofrecer 3, 6 o 12 MSI cambia la decisión de compra.
• OXXO (voucher en efectivo): el comprador recibe un voucher y va a pagar a la tienda más tarde. El pago queda pending hasta que liquida. Esto puede tomar horas o días. Si das acceso en el redirect, regalaste tu producto.
• SPEI (transferencia bancaria interbancaria): muy común para facturas B2B grandes. En Mercanto era el método de los pedidos serios.
• Wallet de Mercado Pago: saldo guardado / cuenta MP, con muchísima confianza del consumidor mexicano.

OXXO y SPEI son exactamente la razón por la que el redirect no se puede creer: liquidan de forma asíncrona, después del checkout. El único momento confiable para dar acceso es cuando llega el webhook con status === "approved". Si construyes para este mercado, vale la pena leer mi nota sobre ser desarrollador de apps en México.

¿Cuánto cuesta Mercado Pago y cuáles son los detalles a cuidar?

Las comisiones de Mercado Pago varían por país, método y velocidad de liquidación, y son sensibles al tiempo. Como referencia, a 2026 la regla general es que entre más rápido quieras tu dinero, más alta es la tasa, y que cada método tiene su propio costo. No me voy a inventar números aquí: confirma la tarifa vigente para México directamente en la página de Mercado Pago, porque cambia.

Y los detalles de práctica que te van a morder si no los cuidas:

• Prueba con sandbox y usuarios de prueba bajo “Tus integraciones” antes de salir a producción. No descubras los bugs con dinero real.
• No confundas pending con approved. OXXO y SPEI necesitan el webhook de liquidación. Tratar pending como pago bueno es el error clásico.
• Las credenciales de test y de producción son distintas. Mezclarlas rompe en silencio la validación de firma o los pagos. Si tu x-signature no valida en local pero el código se ve bien, revisa que el secret y el access token sean del mismo entorno.
• Velocidad de payout afecta tu tasa. Decide conscientemente si quieres liquidación rápida o tarifa más baja.

Para elegir entre proveedores con criterio, vuelve a la comparativa de pasarelas de pago en México.

Preguntas frecuentes sobre integrar Mercado Pago

¿Checkout Pro, Bricks o Checkout API? Checkout Pro si quieres lo más rápido y menos PCI (página alojada). Bricks si quieres un checkout con tu marca embebido. Checkout API si necesitas control total de la UI y puedes cargar todo el alcance PCI.

¿Puedo confiar en los back_urls / el redirect para dar acceso? No. El redirect es solo UX. Solo el webhook verificado y con status === "approved" concede acceso.

¿Cómo soporto OXXO y SPEI? Vienen incluidos en Checkout Pro. Como liquidan más tarde, esperas el webhook aprobado, nunca asumes que el redirect significa pago.

¿Necesito validar el x-signature? Sí. Confirma que la notificación viene genuinamente de Mercado Pago. Sin esa validación, cualquiera que conozca tu URL puede falsificar un “pago”.

¿Cómo pruebo antes de salir a producción? Con sandbox y usuarios de prueba bajo “Tus integraciones” en el Developer Dashboard, usando las credenciales de test (no las de producción).

¿Mercado Pago o Stripe en México? Mercado Pago por la confianza del consumidor B2C y los métodos locales (MSI, OXXO, SPEI, wallet). Stripe brilla en otros escenarios; lo comparo a fondo en la comparativa de pasarelas y en cómo integrar Stripe en tu SaaS.

Cierre: lanza la versión aburrida y verificada

Un respiro y lo resumo: creas la preferencia del lado del servidor, rediriges al comprador a Checkout Pro, pero das acceso únicamente cuando llega un webhook con firma verificada y status === "approved". Esa es toda la disciplina.

Elige Checkout Pro por default; ve por Bricks o la Checkout API solo cuando la UX lo exija de verdad, no por gusto. La cobertura de métodos mexicanos (MSI, OXXO, SPEI, wallet) es lo que de verdad mueve la conversión aquí, y los métodos asíncronos son justo lo que hace innegociable la regla del webhook. La versión aburrida y correcta del webhook es la que evita que se te fugue el dinero.

Toda la documentación oficial está en Mercado Pago Developers. Lo demás es construir con calma y verificar antes de dar acceso.