Documentação Webhook MercadoPago

📋 Visão Geral

Como Funciona

O webhook do MercadoPago é responsável por receber notificações de mudança de status dos pagamentos da loja virtual. Quando um cliente paga um pedido, o MercadoPago envia uma notificação para nosso sistema automaticamente.

Fluxo Completo:

Cliente finaliza pedido → Redireciona para checkout MercadoPago
Cliente paga → MercadoPago processa o pagamento
Status muda → MercadoPago envia webhook para nosso sistema
Sistema processa → Atualiza status do pedido na loja
Comissão calculada → Split automático entre loja e Mais PDV

⚡ Características

Tempo real: Notificações instantâneas
Idempotente: Não duplica processamento
Seguro: Validação de origem
Auditável: Logs completos

🔔 Endpoint do Webhook

POST /webhook/mercadopago/{store_alias}/{order_id}

Endpoint que recebe notificações do MercadoPago

Parâmetros da URL:

`store_alias`	Alias único da loja (ex: "lojadojose")
`order_id`	ID numérico do pedido

Exemplo de URL:

https://maispdv.com/webhook/mercadopago/lojadojose/123

⚠️ HTTPS Obrigatório: MercadoPago só envia para URLs HTTPS

Payload Recebido

Estrutura padrão enviada pelo MercadoPago

Headers:

Content-Type: application/json
User-Agent: MercadoPago WebHook 1.0
X-Request-Id: abc123...

Body (Pagamento Aprovado):

{
    "id": 123456789,
    "live_mode": false,
    "type": "payment",
    "date_created": "2025-09-24T15:30:00.000-04:00",
    "user_id": "987654321",
    "api_version": "v1",
    "action": "payment.updated",
    "data": {
        "id": "123456789"
    }
}

Campos Importantes:

`type`	Deve ser "payment" (outros são ignorados)
`data.id`	ID do pagamento no MercadoPago
`live_mode`	false = sandbox, true = produção
`action`	Ação que gerou o webhook

Resposta do Sistema:

{
    "processed": true,
    "order_id": 123,
    "status": "paid",
    "message": "Webhook processado com sucesso"
}

Mapeamento de Status

Como os status do MercadoPago são convertidos para nosso sistema

Status MercadoPago	Status Sistema	Descrição	Ação
approved	paid	Pagamento aprovado	✅ Pedido liberado
pending	pending	Aguardando pagamento	⏳ Aguardando
rejected	failed	Pagamento rejeitado	❌ Pedido cancelado
cancelled	cancelled	Pagamento cancelado	🚫 Pedido cancelado
refunded	refunded	Pagamento estornado	↩️ Estorno processado

🔐 Segurança e Validações

Validações Implementadas

Store válida: Verifica se loja existe e está ativa
Pedido válido: Confirma que pedido pertence à loja
Rate limiting: Máximo 60 requests/minuto por IP
Idempotência: Evita processamento duplicado
Tipo de webhook: Só processa webhooks "payment"

Logs de Auditoria

Todo webhook é registrado na tabela webhook_logs:

Payload completo recebido
Resposta enviada de volta
Status HTTP da resposta
Timestamp de processamento

Configuração no MercadoPago

Para configurar o webhook no painel do MercadoPago:

Acesse Integrações → Webhooks
Clique em Criar webhook
Cole a URL:
https://maispdv.com/webhook/mercadopago/SEU_ALIASPEDIDO_ID
Selecione eventos: Payments
Teste a conectividade

💡 Dica Importante

O sistema registra automaticamente a URL do webhook ao criar pagamentos. Não é necessário configurar manualmente na maioria dos casos.

🧪 Testando o Webhook

Teste Manual (cURL)

Simule um webhook do MercadoPago:

# Webhook de pagamento aprovado
curl -X POST https://maispdv.com/webhook/mercadopago/lojateste/123 \
  -H "Content-Type: application/json" \
  -H "User-Agent: MercadoPago WebHook 1.0" \
  -d '{
    "id": 123456789,
    "live_mode": false,
    "type": "payment",
    "date_created": "2025-09-24T15:30:00.000-04:00",
    "user_id": "987654321",
    "api_version": "v1",
    "action": "payment.updated",
    "data": {
        "id": "123456789"
    }
}'

Resposta Esperada:

HTTP/1.1 200 OK

{
    "processed": true,
    "order_id": 123,
    "status": "paid",
    "message": "Webhook processado com sucesso"
}

Dados de Teste

Use essas configurações para testes em sandbox:

Store Alias:	`lojateste`
Order ID:	`123` (qualquer ID válido)
Payment ID:	`123456789`

Monitoramento

Para acompanhar os webhooks:

Logs Laravel: storage/logs/laravel.log
Webhook Logs: Tabela webhook_logs
Status Pedidos: Painel administrativo

⚠️ Ambiente de Teste

Certifique-se de usar credenciais sandbox (tokens que começam com "TEST-") para evitar transações reais durante testes.

🚨 Códigos de Erro e Troubleshooting

Código	Erro	Causa Provável	Solução
200	OK	Webhook processado com sucesso	✅ Funcionando corretamente
400	Bad Request	Dados inválidos no payload	Verificar estrutura do JSON enviado
404	Not Found	Loja ou pedido não encontrado	Verificar alias da loja e ID do pedido
429	Too Many Requests	Rate limit excedido	Aguardar 1 minuto antes de tentar novamente
500	Internal Server Error	Erro no código do sistema	Verificar logs Laravel e configurações MP

Problemas Comuns

🔴 "Loja não encontrada"

Verificar se alias da loja está correto na URL
Confirmar se loja está ativa (enabled = true)
Checar se loja pertence à empresa correta

🔴 "Pedido não encontrado"

Verificar se ID do pedido existe
Confirmar se pedido pertence à loja informada
Checar se pedido não foi deletado

🔴 "Configuração MercadoPago inválida"

Verificar se PaymentType "MercadoPago" existe
Confirmar access_token e public_key válidos
Testar credenciais no ambiente correto

Debug e Monitoramento

📊 Logs do Sistema

# Ver logs em tempo real
tail -f storage/logs/laravel.log | grep MercadoPago

# Buscar webhook específico  
grep "Webhook MercadoPago" storage/logs/laravel.log

🔍 Query WebhookLog

-- Últimos webhooks recebidos
SELECT * FROM webhook_logs 
ORDER BY created_at DESC 
LIMIT 10;

-- Webhooks com erro
SELECT * FROM webhook_logs 
WHERE status_code >= 400;

💡 Dica de Debugging

Use o payment_id do webhook para consultar diretamente na API do MercadoPago e comparar com os dados salvos no sistema.

💳 Webhook MercadoPago - Mais PDV