Mercado Pago es el procesador de pagos más usado en Argentina y gran parte de Latinoamérica. Integrar sus medios de pago en tu aplicación web puede parecer simple, pero hay decisiones clave que impactan directamente en la conversión y la experiencia del usuario. En este artículo te explicamos las opciones disponibles y los puntos críticos a tener en cuenta.
Checkout Pro vs Checkout API: ¿cuál elegir?
Checkout Pro
Es la opción más rápida de implementar. Vos generás una preferencia de pago en el backend con el monto, los ítems y la URL de retorno, y Mercado Pago se encarga de mostrar su propio formulario de pago. El usuario es redirigido (o ve un modal) al checkout de Mercado Pago.
Ventajas: Implementación en horas, cumplimiento PCI automático, soporte para todos los medios de pago disponibles en tu país.
Desventajas: Menor control sobre la experiencia del usuario. El checkout tiene la marca de Mercado Pago, no la tuya.
Checkout API (Bricks o custom)
Con el Checkout API, el formulario de pago vive dentro de tu sitio. Mercado Pago provee los "Bricks" (componentes de React o JS) que manejan la tokenización de la tarjeta de forma segura, o podés construir un formulario completamente custom usando su SDK de front.
Ventajas: Experiencia de pago completamente integrada en tu sitio, con tu diseño. Mayor control sobre el flujo.
Desventajas: Implementación más compleja. Requiere más trabajo de testing y validación.
Recomendación: Para la mayoría de los proyectos, empezar con Checkout Pro y migrar al Checkout API cuando la conversión y la experiencia de usuario sean prioridad.
Flujo básico de una integración con Checkout Pro
El flujo tiene tres partes: crear la preferencia, redirigir al usuario y manejar el resultado.
1. Crear la preferencia (backend)
Desde tu servidor hacés un POST a la API de Mercado Pago con el Access Token de tu cuenta, los ítems y las URLs de retorno:
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.mercadopago.com/checkout/preferences',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . TU_ACCESS_TOKEN,
],
CURLOPT_POSTFIELDS => json_encode([
'items' => [[
'title' => 'Mi producto',
'quantity' => 1,
'unit_price' => 1500.00,
]],
'back_urls' => [
'success' => 'https://tusitio.com/gracias',
'failure' => 'https://tusitio.com/error',
'pending' => 'https://tusitio.com/pendiente',
],
'auto_return' => 'approved',
'notification_url' => 'https://tusitio.com/webhook/mercadopago',
]),
]);
$response = json_decode(curl_exec($curl), true);
$init_point = $response['init_point']; // URL donde redirigir al usuario
2. Redirigir al usuario
Con el init_point obtenido, redirigís al usuario o lo abrís en un modal. Mercado Pago maneja el proceso de pago completo.
3. Manejar el webhook (notificaciones)
Este es el punto más crítico y donde más errores se cometen. No confíes en las back_urls para confirmar el pago — el usuario puede cerrar el browser antes de ser redirigido. El mecanismo confiable son los webhooks: Mercado Pago hace un POST a tu notification_url cada vez que cambia el estado de un pago.
<?php
// webhook/mercadopago.php
$payload = json_decode(file_get_contents('php://input'), true);
if($payload['type'] === 'payment') {
$payment_id = $payload['data']['id'];
// Consultamos el estado real del pago
$curl = curl_init("https://api.mercadopago.com/v1/payments/{$payment_id}");
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . TU_ACCESS_TOKEN],
]);
$payment = json_decode(curl_exec($curl), true);
if($payment['status'] === 'approved') {
// Acreditar el pedido en tu sistema
}
}
http_response_code(200);
Errores frecuentes al integrar Mercado Pago
- Usar las credenciales de producción para testear — Mercado Pago tiene un ambiente sandbox con cuentas de prueba. Siempre desarrollá y testeá ahí.
- No validar el webhook — Cualquiera puede hacer un POST a tu endpoint. Verificá siempre el estado del pago consultando directamente a la API de Mercado Pago con el ID recibido.
- Actualizar el pedido al volver de back_url — Como mencionamos, el usuario puede no volver. El estado de la orden debe actualizarse por webhook, no por back_url.
- No manejar el estado "pending" — Los pagos en efectivo (Rapipago, PagoFácil) quedan en estado pending hasta que el usuario paga. Tu sistema tiene que soportar ese estado intermedio.
- Ignorar el campo external_reference — Es el campo que te permite relacionar el pago de Mercado Pago con el pedido en tu sistema. Siempre envialo en la preferencia.
¿Necesitás ayuda con la integración?
En Softix IT tenemos experiencia integrando Mercado Pago en decenas de proyectos: ecommerce, plataformas SaaS, marketplaces y sistemas de reservas. Si tu integración tiene comportamientos inesperados o necesitás construirla desde cero, consultanos.
