Configurar notificações
As notificações via Webhooks, também conhecidas como web callbacks, são um método eficaz que permite que os servidores do Mercado Pago enviem informações em tempo real quando ocorre um evento específico relacionado à sua integração. Em vez de o seu sistema consultar constantemente as atualizações, os webhooks permitem a transmissão passiva e automática de dados entre o Mercado Pago e sua integração por meio de uma requisição HTTPS POST, otimizando a comunicação e reduzindo a carga no servidor.
A seguir, veja um passo a passo para receber notificações de pagamento em suas integrações de Payouts. Uma vez configuradas, as notificações via webhook serão enviadas sempre que houver alguma atualização no tópico informado, incluindo a criação de uma transação ou mudanças de status durante o processamento.
Por meio do campo config.notification_url, você pode configurar as notificações via webhook ao fazer a chamada de criação de um payout. Basta preenchê-lo com a URL onde deseja receber as atualizações.
notification_url, como localhost/ ou 127.0.0.1, com ou sem porta especificada. Utilize um servidor com domínio nomeado (DNS) ou um IP de desenvolvimento acessível externamente, para que o Mercado Pago possa enviar as notificações corretamente.curl--data '{ ... "config": { "notification_url": "https://link-your-webhook-notification.com" } ... }'
| Campo | Tipo | Descrição | Obrigatório | Exemplo |
config | Object | Body. Objeto que reúne as configurações do payout. | Obrigatório para as notificações | - |
config.notification_url | String | Body. URL onde você receberá notificações de eventos relacionados à transação, como mudanças de status. | Obrigatório para as notificações | https://link-your-webhook-notification.com |
Veja a seguir exemplos das mensagens retornadas quando um evento ocorre.
Mensagem ao criar uma transação:
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" }
Mensagem ao atualizar uma transação:
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" }
O atributo payout.id corresponde ao ID do payout, id é o ID da transação e status indica o status atual de processamento da transação.
Ao receber uma notificação em sua plataforma, o Mercado Pago espera uma resposta para validar que o recebimento ocorreu corretamente. Retorne um HTTP STATUS 200 (OK) ou 201 (CREATED). O tempo de espera para essa confirmação é de 22 segundos. Se essa resposta não for enviada, o sistema entenderá que a notificação não foi recebida e fará uma nova tentativa de envio a cada 15 minutos até receber a resposta. Após a terceira tentativa, o prazo é estendido, mas os envios continuam acontecendo.
Depois de responder à notificação e confirmar seu recebimento, você pode obter todas as informações sobre o recurso notificado enviando uma solicitação ao endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET. Com essas informações, você poderá realizar as atualizações necessárias.