← todos os posts
Tutorial 5 min de leitura

"Autópsia: o Pix caiu, o app não liberou, e o cliente mandou o comprovante 3 vezes"

"O cliente pagou, o app não liberou e o comprovante chega pela terceira vez. Onde quebrou, em três telas, e o que responder pra ele enquanto isso."

Sexta, nove da noite. Chega no WhatsApp um comprovante de Pix de R$ 47. Vinte minutos depois, o mesmo. Depois, o terceiro, com um "???".

O cliente pagou, o app não liberou, e você não sabe se o problema está no banco dele, no Mercado Pago ou no app.

"A IA até gera o código de integração. Mas gera ERRADO em metade das vezes."

A frase é de um programador brasileiro no TabNews, avaliação dele e não medição (já usei ela aqui). Aqui ela vira cena: o QR funcionou, o dinheiro andou, e a parte que ninguém vê falhou em silêncio. O caso é montado, mas cada pedaço dele é um defeito que existe.

Não foi o banco do cliente

O Manual de Tempos do Pix, do Banco Central (versão 7.0), diz que um Pix tem no máximo 40 segundos pra ser liquidado, e que "transações que não forem liquidadas dentro desse limite de tempo serão rejeitadas". A exceção é a suspeita de fraude, que pode segurar o Pix até 30 minutos em horário comercial e 60 fora dele, e aí é o banco do cliente que avisa.

Traduzindo: se o comprovante é verdadeiro, o dinheiro chegou em segundos. O que falhou foi o aviso entre quem recebeu o dinheiro e o seu app. E isso não é desatenção sua: é a parte do Pix que não aparece em tela nenhuma.

A autópsia, em três telas

Esse aviso se chama webhook: o recado que o Mercado Pago manda pro seu servidor (o computador onde o app roda) dizendo "o pedido tal mudou". O fluxo inteiro tá aqui. Agora é achar onde quebrou, em três telas.

Tela 1: o dinheiro está na sua conta do Mercado Pago?

Procure o pagamento pelo valor e horário. Não confie na imagem do WhatsApp: imagem se edita.

  • Está lá: siga pra tela 2.
  • Não está: o cliente pagou em outro lugar. O caso clássico: ele copiou uma chave Pix sua de outra conversa, o dinheiro foi pro seu banco e o Mercado Pago nunca soube. Confira o extrato.

Tela 2: o Mercado Pago avisou o seu app?

Em Suas integrações, escolha a aplicação e clique em Webhooks. É o painel de notificações: cada aviso aparece com o status da entrega (sucesso ou falha) e, clicando, o código que o seu servidor respondeu. Filtre pelo horário do pagamento:

O que o painel mostra Onde quebrou
Nenhum aviso naquele horário O endereço de aviso não está cadastrado no modo real. Na configuração, o Mercado Pago pede o endereço na aba Modo de produção; se só o de teste foi preenchido, o app real nunca recebe nada
Falha com código 401 ou 403 O seu servidor recusou o carimbo (a assinatura do aviso). Quase sempre é a chave secreta de teste rodando no app real, um caso de variável de ambiente
Falha com código 404 O endereço não existe mais. Você mudou de domínio ou republicou e o caminho mudou
Falha com código 500, ou sem resposta O servidor quebrou ao processar, ou demorou mais que os 22 segundos que o Mercado Pago espera
Sucesso O aviso chegou. O defeito está dentro do seu app: siga pra tela 3

Tela 3: o que diz a linha do pedido no seu banco de dados?

  • Está "aguardando": o aviso chegou e o app não reconheceu o pedido. Quase sempre a referência própria não foi junto da cobrança, ou o valor não bateu.
  • Está "pago" e o acesso continua fechado: a área paga está olhando pra outro lugar que não esse status.
  • O pedido nem existe: o app criou a cobrança sem gravar o pedido antes.

Cada linha dessas é um pedido específico pra IA. "Conserta o Pix" faz ela mexer em tudo. "O painel de notificações mostra falha 401 no horário tal; verifique se a chave secreta de assinatura em produção é a da aplicação em modo real" faz ela mexer numa coisa.

O que dizer pro cliente, agora

Se a tela 1 mostrou o dinheiro, responda antes de consertar qualquer coisa:

"Recebi seu pagamento, tá confirmado aqui. Tivemos uma falha na liberação automática e já liberei seu acesso manualmente. Desculpa a espera, e obrigado por avisar."

Três regras pra liberar à mão:

  1. Libere mudando o status no banco pra "pago", nunca criando um atalho. Atalho vira porta aberta.
  2. Anote numa folha: cliente, valor, horário, e "liberado à mão".
  3. Depois do conserto, volte na folha. Sem resposta de sucesso, o Mercado Pago reenvia o aviso a cada 15 minutos, e segue tentando depois da terceira vez, mais espaçado. Quando o conserto entrar, os atrasados chegam. Se o app não sabe ignorar pedido já pago, é problema novo.

Faça hoje, antes do primeiro cliente reclamar

Abra Suas integrações → Webhooks e clique em Simular. Escolha o endereço do modo real, o tipo de evento, e mande um aviso de teste. O painel mostra o que o seu servidor respondeu. Erro ali é a falha de sexta à noite achada numa terça de manhã.

E uma vez por semana, olhe o Painel de monitoramento, no mesmo menu lateral. Desde fevereiro de 2026 ele mostra quantos avisos foram enviados, processados e quais falharam. Falha que ninguém viu é cliente que vai mandar comprovante.

A parede e as vizinhas

Essa autópsia acha o defeito depois que ele aconteceu. Provar que o fluxo funciona antes do cliente (pagar com valor mínimo, não pagar, pagar duas vezes) é outro teste, e ele depende de outra pergunta: o servidor, o banco e as chaves são seus, e você separa o de teste do real?

Cobrar dos primeiros clientes é uma das dez perguntas que separam protótipo de produto, e vem depois de ter código, banco e login nas suas mãos. As três telas desse post só servem se você tem acesso a elas.

Fontes