Clase 05 · Módulo 08
Confirmar pagos con webhooks y registrar pedidos
Confirmar pagos con webhooks y registrar pedidos
Qué logras en esta clase
Dejas tu tienda marcando un pedido como pagado solo cuando el pago existe de verdad.
- Recibes el aviso de Mercado Pago en una función propia.
- Verificas la firma y consultas el pago antes de creerlo.
- Registras el pedido una sola vez y avisas al cliente.
02
Dónde se confirma un pago
La página de retorno es una cortesía. El pago se confirma en el servidor.
03
Por qué el retorno no basta
- El comprador puede pagar y cerrar la pestaña antes de volver.
- Su conexión puede caerse en el camino.
- Cualquiera puede escribir a mano la dirección de «pago aprobado».
- Algunos pagos quedan pendientes y se resuelven después.
Si tu tienda marca pagado al cargar esa página, pierdes ventas reales y regalas productos.
04
Qué es un webhook
Un webhook es un aviso que un servicio le envía a tu servidor cuando ocurre algo. En vez de preguntar tú cada minuto si hubo un pago, Mercado Pago llama a una dirección tuya cuando lo hay.
Esa dirección es una función de servidor de tu proyecto que recibe peticiones POST, igual que la del formulario del módulo 7.
05
El recorrido de la confirmación
Son tres comprobaciones antes de tocar el pedido: que el aviso sea auténtico, que el pago exista y que corresponda a ese pedido.
06
Configurar el webhook en el panel
- Entra al Panel del desarrollador y abre tu aplicación.
- En «Detalles de la aplicación», ve a Webhooks.
- Escribe la dirección de tu función: una para producción y otra para pruebas.
- Selecciona el evento de pagos.
- Guarda. Al guardar se genera la clave secreta de la aplicación.
También puedes indicar la dirección por cada cobro con el campo notification_url.
07
Qué trae el aviso
El aviso llega como JSON, un formato de texto para datos.
| Campo | Contenido |
|---|---|
type | Tipo de aviso, por ejemplo payment |
action | Qué ocurrió, por ejemplo payment.created o payment.updated |
data.id | El identificador del pago |
live_mode | Si viene de producción |
No trae el monto ni el estado del pago.
08
El aviso no es la prueba
El aviso solo dice «mira este pago». No dice si está aprobado.
09
Por qué verificar la firma
La dirección de tu webhook es pública. Cualquiera puede enviarle un POST que imite un aviso.
Mercado Pago agrega a cada aviso una cabecera x-signature, calculada con la clave secreta que solo conocen ellos y tú. Si tu función recalcula la firma y coincide, el aviso es auténtico.
Esa clave secreta es otro secreto: va en una variable de entorno del servidor.
10
Cómo se valida la firma
- Separa
x-signatureen sus dos partes:ts(la hora) yv1(la firma). - Toma la cabecera
x-request-idy el parámetrodata.idque viene en la dirección del aviso. - Arma el texto con la plantilla oficial.
- Calcula su HMAC SHA256 con la clave secreta, en hexadecimal.
- Compara con
v1. Si no coincide, descarta el aviso.
id:[data.id];request-id:[x-request-id];ts:[ts];11
Consulta el pago antes de creerlo
Con el identificador recibido, tu servidor pregunta a la API: GET /v1/payments/{id}. La respuesta trae status y status_detail, junto con los datos del pago.
Comprueba tres cosas:
- El estado es el de pago aprobado.
- La referencia externa del pago corresponde a un pedido tuyo.
- El monto pagado es igual al total del pedido.
Solo si las tres se cumplen, el pedido pasa a «pagado».
12
Qué hacer con cada estado
| Resultado de la consulta | Acción |
|---|---|
| Aprobado y coincide | Pedido a «pagado», descontar stock, enviar correo |
| Pendiente | No cambiar nada; llegará otro aviso |
| Rechazado o cancelado | Dejar el pedido sin pagar |
| Monto o referencia no coinciden | No marcar pagado; revisar a mano |
Los valores exactos de status están en la referencia de pagos. Pídele a Claude que los tome de ahí.
13
Responde rápido
Tu función debe contestar con código 200 o 201. Cualquier otra respuesta cuenta como aviso no recibido.
Mercado Pago espera 22 segundos en el primer envío. Si no confirmas, reintenta a los 15 minutos, 30 minutos, 6 horas, 48 horas y 96 horas del primer envío, esperando 5 segundos cada vez.
14
El mismo aviso puede llegar dos veces
Un pago genera más de un aviso: al crearse, al actualizarse y en cada reintento. También puede llegar antes de que el comprador vuelva a tu web.
Tu función debe ser idempotente: procesar el mismo aviso dos veces deja el mismo resultado que procesarlo una.
Sin eso, descuentas el stock dos veces y envías dos correos.
15
Cómo se logra la idempotencia
- El pedido cambia a «pagado» solo si su estado actual es «creado».
- El identificador del pago se guarda en el pedido y no puede repetirse en otro.
- El stock se descuenta y el correo se envía dentro de ese mismo cambio de estado.
16
La tabla de pedidos
| Campo | Para qué |
|---|---|
| Número de pedido | Tu referencia; viaja en external_reference |
| Estado | Creado, pagado, enviado, anulado |
| Identificador del pago | Unir el pedido con el pago real |
| Ítems con nombre y precio pagado | Historial que no depende del catálogo |
| Total y despacho | Lo que se cobró |
| Datos del comprador | Contacto y entrega |
17
Protege los pedidos con RLS
Los pedidos tienen nombres, correos y direcciones. La tabla lleva RLS activado y ninguna política para visitantes: desde el navegador no se puede leer ni escribir.
Solo tus funciones de servidor la usan, con la clave secreta de Supabase que viste en el módulo 7.
18
El correo de confirmación
Cuando el pedido pasa a «pagado», tu función envía dos correos con Resend, como en el módulo 7: uno al cliente con el detalle de su compra y otro a ti con el aviso de venta.
Al cliente dile qué compró, cuánto pagó, su número de pedido, qué pasa ahora y cómo contactarte.
Si el envío falla, el pedido sigue pagado. Registra el fallo para reenviar.
19
Probar con el simulador
En la misma pantalla de Webhooks hay un botón «Simular»: eliges la dirección, el tipo de evento y un identificador, y envías una prueba.
Sirve para comprobar que tu función recibe, valida la firma y responde 200.
No reemplaza la prueba completa: un pago de prueba que recorre preferencia, pago, aviso, pedido y correo.
20
Si un aviso no llegó
Los reintentos cubren caídas breves. Para el resto, la API permite conciliar:
GET /v1/payments/searchbusca pagos porexternal_reference.GET /merchant_orders/{id}agrupa las transacciones de una preferencia.
Con pocas ventas basta una rutina: una vez al día compara los pagos de tu cuenta de Mercado Pago con los pedidos «pagado» de tu base.
21
Marcar pagado en el retorno
La página de retorno puede consultar el estado del pedido en tu servidor y mostrarlo. Si todavía dice «creado», muestra «estamos confirmando tu pago».
22
Creerle al contenido del aviso
Al revisar el plan de Claude, busca las dos comprobaciones por nombre: validación de x-signature y consulta a /v1/payments/{id}. Si falta una, el plan no se aprueba.
23
Lo que te llevas
- El webhook es el aviso; la consulta a la API es la prueba.
- La firma
x-signaturedemuestra que el aviso viene de Mercado Pago. - Un pedido pasa a «pagado» si estado, referencia y monto coinciden.
- La función es idempotente: un aviso repetido no duplica nada.
- La tabla de pedidos no se lee desde el navegador.
24
Hazlo ahora
En 15 minutos:
- Configura la dirección de pruebas del webhook en el panel y guarda.
- Copia la clave secreta a una variable de entorno del servidor.
- Pídele a Claude, en modo plan, la función que valida la firma, consulta el pago y actualiza el pedido.
- Usa «Simular» y comprueba que tu función responde
200. - Envía el mismo aviso dos veces y confirma que el pedido no cambia la segunda vez.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026