Webhooks dos gateways
Como os gateways avisam a MinePag sobre pagamentos e o que acontece quando um aviso falha.
Quando um pagamento muda (aprovado, recusado, reembolsado, contestado), o gateway avisa a MinePag por webhook. É esse aviso que faz o pedido virar Pago em segundos e liberar a entrega.
Não confundir com os webhooks da loja
Esta página trata dos avisos que os gateways enviam para a MinePag. Para receber eventos da sua loja no seu próprio sistema, veja Webhooks para desenvolvedores.
Como cada gateway é configurado
| Gateway | Configuração | Como a MinePag confere o aviso |
|---|---|---|
| Efí | Automática: o webhook é registrado na chave Pix ao conectar. Boleto e cartão levam o endereço em cada cobrança. | Código de verificação próprio da conexão no endereço e, em Produção, origem nos servidores da Efí. |
| Mercado Pago (login pelo Mercado Pago) | Automática. | Assinatura x-signature com o segredo da aplicação MinePag. |
| Mercado Pago (credenciais) | Manual: você cadastra a URL na aplicação e cola a assinatura secreta. | Assinatura x-signature com a sua assinatura secreta. |
| PagBank | Automática: o endereço vai em cada pedido. | Assinatura do PagBank em cada aviso. |
| Stripe | Automática: a MinePag cria um endpoint na sua conta. | Cabeçalho Stripe-Signature, com tolerância de 5 minutos. |
Os passos de cada um estão nos guias: Efí, Mercado Pago, PagBank e Stripe.
O que a MinePag faz com cada aviso
Confere a autenticidade. Um aviso sem assinatura válida é recusado e aparece como Assinatura inválida na página da conexão.
Descarta repetições. Os gateways costumam reenviar o mesmo aviso. Cada aviso é processado uma vez só.
Consulta o gateway. A MinePag nunca confia no conteúdo do aviso: ela consulta o pagamento direto na API do gateway, com as suas credenciais, e só então atualiza o pedido.
Atualiza o pedido. Um pagamento confirmado deixa o pedido Pago e libera as entregas. Reembolsos e contestações seguem as regras de Reembolsos e contestações.
Avisos sobre vendas que não foram feitas pela MinePag (por exemplo, uma venda no seu app) são ignorados. Essas vendas entram em Vendas › Transações pela sincronização diária.
Acompanhar os avisos
Na página da conexão, a seção Avisos de pagamento (webhook) mostra se o webhook está registrado e a lista Últimos avisos recebidos:
| Estado | O que significa |
|---|---|
| Recebido | O aviso chegou e está sendo processado. |
| Processado | O aviso atualizou um pagamento da MinePag. |
| Ignorado | O aviso era sobre algo que a MinePag não precisa tratar, como uma venda feita fora da MinePag. |
| Falhou | O processamento falhou. A MinePag tenta de novo sozinha. |
| Assinatura inválida | O aviso não passou na conferência de autenticidade e foi descartado. |
Na página Gateways, cada conexão mostra quando chegou o último aviso ("Último aviso do gateway há 5 minutos") ou "Nenhum aviso do gateway ainda".
Quando um aviso não chega
Webhook é a forma rápida, mas não a única. A MinePag também consulta sozinha os pagamentos em aberto:
| Idade do pagamento | Intervalo entre consultas |
|---|---|
| Primeira hora | A cada 2 minutos |
| Primeiro dia | A cada 15 minutos |
| Depois disso | A cada 2 horas |
As consultas param 15 dias depois da criação do pagamento ou 5 dias depois do vencimento do boleto, o que vier por último. Por isso, mesmo sem webhook, um pagamento aprovado vira Pago, só que com alguns minutos de atraso.
Para conferir na hora um pagamento ainda em aberto, abra o pedido em Vendas › Pedidos e clique em Consultar gateway na seção Pagamentos.
Quando o processamento de um aviso falha, a MinePag responde com erro para o gateway reenviar e também tenta de novo sozinha, até 10 vezes.
Webhook pendente
Se a conexão aparece como Webhook pendente, os pagamentos continuam sendo confirmados pela consulta periódica, com atraso. Causas comuns:
- Mercado Pago com credenciais da aplicação: o webhook ainda não foi cadastrado no Mercado Pago ou a assinatura secreta não foi colada na MinePag. Siga a seção Avisos de pagamento (webhook) da página da conexão.
- Permissão faltando no gateway: na Efí, os escopos
webhook.writeewebhook.read; na Stripe, a gravação em Webhook Endpoints. - O gateway estava fora do ar no momento da conexão.
Na Stripe e na Efí, depois de corrigir a causa, clique em Registrar webhook de novo na seção Avisos de pagamento (webhook). A MinePag usa as credenciais guardadas, sem precisar trocá-las. Use o mesmo botão se alguém apagou o endpoint na Stripe ou trocou o webhook da chave Pix na Efí.
Para conferir se as credenciais guardadas continuam valendo (por exemplo, depois de ajustar as permissões no gateway), use Testar conexão. Veja também Problemas comuns.
Não altere o webhook criado pela MinePag
Na Stripe, não edite nem apague o endpoint "MinePag". Na Efí, não troque o webhook da chave Pix conectada. Se isso acontecer, os pagamentos passam a ser confirmados só pela consulta periódica até você usar Registrar webhook de novo.