Configurar notificaciones
Las notificaciones mediante Webhooks, también conocidas como web callbacks, son un método eficaz que permite que los servidores de Mercado Pago envíen información en tiempo real cuando ocurre un evento específico relacionado con tu integración. En lugar de que tu sistema consulte constantemente las actualizaciones, los webhooks permiten la transmisión pasiva y automática de datos entre Mercado Pago y tu integración mediante una solicitud HTTPS POST, optimizando la comunicación y reduciendo la carga del servidor.
A continuación, mira un paso a paso para recibir notificaciones de pago en tus integraciones de Payouts. Una vez configuradas, las notificaciones vía webhook se enviarán cada vez que haya alguna actualización sobre el tema informado, incluida la creación de una transacción o cambios de estado durante el procesamiento.
Mediante el campo config.notification_url, puedes configurar las notificaciones vía webhook al realizar la llamada para crear un payout. Simplemente complétalo con la URL donde deseas recibir las actualizaciones.
notification_url, como localhost/ o 127.0.0.1, con o sin puerto especificado. Utiliza un servidor con dominio nombrado (DNS) o una IP de desarrollo accesible externamente, para que Mercado Pago pueda enviar las notificaciones correctamente.curl--data '{ ... "config": { "notification_url": "https://link-your-webhook-notification.com" } ... }'
| Campo | Tipo | Descripción | Requerido | Ejemplo |
config | Object | Body. Objeto que reúne las configuraciones del payout. | Requerido para las notificaciones | - |
config.notification_url | String | Body. URL donde recibirás notificaciones de eventos relacionados con la transacción, como cambios de estado. | Requerido para las notificaciones | https://link-your-webhook-notification.com |
A continuación, encontrarás ejemplos de los mensajes devueltos cuando ocurre un evento.
Mensaje al crear una transacción
json{ "created_date": "2026-01-29T15:20:25.470+00:00", "external_reference": "MP0197", "id": "TOP01KKYN1QY2SS1MKAY4E5KM8WZ6", "last_updated_date": "2026-01-29T15:20:25.470+00:00", "payout": { "external_reference": "MP0197", "id": "POP01KKCFKH9J2C8TQSQZM4R3Z22C", "notification_url": "https://link-your-webhook-notification.com" }, "status": "approved" }
Mensaje al actualizar una transacción
json{ "created_date": "2026-01-29T15:20:25.470+00:00", "external_reference": "MP0197", "id": "TOP01KKYN1QY2SS1MKAY4E5KM8WZ6", "last_updated_date": "2026-01-29T15:20:25.470+00:00", "payout": { "external_reference": "MP0197", "id": "POP01KKCFKH9J2C8TQSQZM4R3Z22C", "notification_url": "https://link-your-webhook-notification.com" }, "status": "success", "status_detail": "accredited" }
El atributo payout.id corresponde al ID del payout, id es el ID de la transacción y status indica el estado actual de procesamiento de la transacción.
Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recepción fue correcta. Devuelve un HTTP STATUS 200 (OK) o 201 (CREATED). El tiempo de espera para esta confirmación es de 22 segundos. Si esta respuesta no se envía, el sistema entenderá que la notificación no fue recibida y hará un nuevo intento de envío cada 15 minutos hasta recibir la respuesta. Después del tercer intento, el plazo se extiende, pero los envíos continúan realizándose.
Después de responder a la notificación y confirmar su recepción, puedes obtener toda la información sobre el recurso notificado enviando una solicitud al endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET. Con esta información, podrás realizar las actualizaciones necesarias.