← todos os posts
Tutorial 9 min de leitura

"Pix que cai e libera sozinho: o fluxo inteiro, do QR ao \"pago\" no seu banco de dados"

"O QR na tela é a parte fácil. As cinco peças que fazem o Pix virar \"pago\" sem você conferir comprovante no WhatsApp, e o teste que prova isso hoje."

"A IA até gera o código de integração. Mas gera ERRADO em metade das vezes, porque a documentação brasileira é escassa e desatualizada."

Já abri o post sobre cobrar em real com essa frase de um programador brasileiro no TabNews, em 2026. É a avaliação dele, não uma medição. Mas no Pix o mecanismo aparece de um jeito específico.

Você pede "coloca Pix no meu app". A IA entrega um QR code bonito na tela. O cliente paga. E aí uma de duas coisas acontece:

  • O app não fica sabendo. O cliente manda o comprovante no WhatsApp, você abre o extrato do banco, confere o valor e libera na mão. Às onze da noite.
  • O app libera rápido demais. A tela de "obrigado" libera o acesso, tenha o dinheiro chegado ou não.

O primeiro te transforma em funcionário do próprio app. O segundo te faz entregar de graça sem saber.

Não é você que não entendeu o Pix

O QR code é a única parte do Pix que aparece na tela, então é a única que a IA mostra. Todo o resto é uma conversa entre dois computadores que você nunca vê: o do Mercado Pago (ou de quem processa o pagamento) e o seu. Essa conversa está documentada, espalhada em quatro páginas, metade em inglês, com nome de campo em vez de explicação. Quem não sabe que ela existe não tem como pedir por ela.

Vou desenhar a conversa inteira. Uso o Mercado Pago porque conferi a documentação dele em 7 de outubro de 2026, mas as cinco peças valem pra qualquer provedor brasileiro. Muda o nome do campo, não a ideia.

As cinco peças

Peça 1: o pedido nasce no SEU banco de dados, antes do QR

Antes de falar com o Mercado Pago, o seu app grava uma linha no seu próprio banco de dados (o lugar onde o app guarda as informações): quem está comprando, o quê, quanto, e um status (a situação do pedido) que começa como aguardando.

Essa linha tem um número que é seu. Ele vai junto pro Mercado Pago, que chama isso de referência externa (external_reference), e volta em todo aviso. É o que permite, lá na frente, saber que o dinheiro que caiu é daquele pedido.

A IA costuma pular essa peça, e aí, quando o aviso chega, o app não tem com o que comparar.

Peça 2: quem pede o QR é o servidor, nunca o celular do cliente

O servidor é o computador onde o seu app roda, longe do cliente. É ele que pede a cobrança ao Mercado Pago, porque é ele que guarda a chave de acesso da sua conta (se a chave estivesse no celular do cliente, qualquer um poderia pegar; é o assunto das variáveis de ambiente).

No pedido de cobrança vão três coisas que importam:

  • o valor, que o servidor tira do SEU banco, e não do que a tela mandou;
  • o prazo de validade do QR. No Mercado Pago, o padrão é 24 horas, e dá pra mudar entre 30 minutos e 30 dias;
  • uma chave pra não cobrar duas vezes. O Mercado Pago exige um cabeçalho chamado X-Idempotency-Key, que garante, nas palavras da documentação, que "cada requisição seja processada apenas uma vez". Traduzindo: se o cliente apertar "pagar" duas vezes, sai uma cobrança, não duas.

O Mercado Pago responde com o QR, o código "copia e cola" e um status: action_required com o detalhe waiting_transfer. Ou seja: esperando o Pix.

Peça 3: o cliente paga, e no seu app nada acontece

O cliente lê o QR no app do banco dele e paga. E o seu app continua sem saber. A tela que o cliente está olhando também não sabe.

Por isso duas coisas nunca podem liberar acesso:

  • A tela de "obrigado". Ela só prova que alguém chegou naquela página.
  • O comprovante. Comprovante é uma imagem. Imagem não é o dinheiro na sua conta.

Quem pode dizer que o dinheiro chegou é só quem recebeu o dinheiro.

Peça 4: o aviso chega, e o servidor desconfia dele

Quando o Pix compensa, o Mercado Pago manda um aviso pro seu servidor (o webhook). O servidor faz quatro coisas, nesta ordem:

  1. Confere o carimbo. Todo aviso do Mercado Pago vem com uma assinatura num campo chamado x-signature, feita com uma chave secreta que só você e ele têm. O servidor confere a assinatura. Aviso sem carimbo válido é ignorado, porque qualquer um na internet pode mandar uma mensagem dizendo "pago" pro endereço do seu servidor.
  2. Pergunta de volta. Mesmo com carimbo, o servidor consulta o pedido no Mercado Pago, como a documentação indica. O aviso diz "algo mudou". A consulta diz o que é verdade agora.
  3. Compara com o pedido dele. A referência bate com um pedido aguardando? O valor pago é o valor do pedido? Se não bater, não libera e anota.
  4. Muda o status, uma vez só. O Mercado Pago espera resposta em 22 segundos e, sem ela, reenvia o aviso a cada 15 minutos; por isso o "caderno de recibos" do post anterior.

A própria documentação do Mercado Pago resume o espírito: espere a notificação "antes de realizar ações irreversíveis, como enviar uma remessa ou liberar acesso".

Peça 5: o acesso olha pro SEU banco de dados, e só pra ele

A área paga faz uma pergunta só: "o status deste pedido, no meu banco, é pago?".

E o pedido que nunca é pago também precisa de fim. O QR vence (pelo prazo da peça 2), o Mercado Pago marca o pedido como canceled, e o seu banco tem que mostrar expirado. Se não, você acumula pedido fantasma e não sabe mais quanto vendeu.

A tabela de tradução

É isso que você confere com o olho, sem ler código. À esquerda, o que o Mercado Pago diz (pela página de estados da documentação). À direita, o que o seu banco de dados deveria mostrar:

O Mercado Pago diz O seu banco deveria dizer O acesso
action_required / waiting_transfer aguardando fechado
processed / accredited (aprovado e creditado) pago aberto
canceled (cancelado ou venceu sem pagamento) expirado fechado
processed / refunded ou refunded (devolvido) devolvido fechado de novo

Quatro linhas. Se o seu app só conhece a segunda, ele conhece um quarto do Pix.

O que fazer hoje: a ordem pra IA e o teste que prova

Primeiro, peça o fluxo inteiro, com a prova junto. Cole isto na ferramenta que você usa:

"Quero o pagamento por Pix neste fluxo: (1) grave o pedido no banco com status 'aguardando' e uma referência própria antes de criar a cobrança; (2) crie a cobrança pelo servidor, com o valor tirado do banco, prazo de validade de 30 minutos e chave de idempotência; (3) nunca libere acesso pela tela de retorno; (4) ao receber o aviso, valide a assinatura, consulte o pedido no provedor, confira referência e valor, e mude o status uma vez só, ignorando aviso repetido; (5) quando o pedido vencer sem pagamento, marque 'expirado'. Use a tabela de estados oficial do provedor. No fim, me diga onde no painel do banco de dados eu vejo o status de cada pedido."

A última frase te dá olhos. Sem ela, você só tem a palavra da IA.

Depois, os três testes. Todos no modo de teste, com as credenciais de teste do Mercado Pago (em Suas integrações, nos dados da aplicação, na parte de testes). Pegue uma folha e escreva:

[ ] Teste 1: paguei e liberou sozinho
[ ] Teste 2: não paguei e virou "expirado"
[ ] Teste 3: abri a página de "obrigado" sem pagar e NÃO liberou

Teste 1, o pagamento que cai. A documentação do Mercado Pago tem um jeito oficial de simular Pix pago: no ambiente de teste, um pedido cujo comprador tem o primeiro nome APRO nasce action_required e depois muda sozinho pra aprovado. Peça à IA: "crie um pedido de teste com o comprador de primeiro nome APRO". Aí, com o painel do banco de dados aberto, olhe o status daquele pedido. Ele tem que ir de aguardando pra pago sem você encostar em nada. Se ficou parado, o aviso não está chegando, e você descobriu antes do cliente.

Teste 2, o pagamento que não vem. Crie um pedido de teste comum, não pague, e volte depois do prazo de 30 minutos. Peça à IA pra consultar aquele pedido no Mercado Pago e te dizer o status de lá. Se lá diz canceled e no seu banco ainda está aguardando, o seu app não fica sabendo das vendas que não aconteceram, e é isso que você manda corrigir.

Teste 3, o atalho. Crie um pedido, não pague, e abra direto a página de "obrigado" (ou recarregue a página de retorno). O acesso tem que continuar fechado. Se abriu, a peça 3 está errada, e esse é o mais caro dos três.

Três marcas na folha, uma tarde. Do outro lado, o Pix cai às onze da noite e você está dormindo.

Esta é uma parede, e ela tem vizinhas

O status pago mora no seu banco de dados. Se a regra do banco deixa o próprio cliente editar o pedido dele, ele escreve pago sozinho e as cinco peças não servem pra nada. Isso é regra de acesso, o assunto do "é só ligar o RLS". As chaves de teste precisam virar as reais na hora de publicar. E falta o dia em que o Pix cai e o app não libera mesmo assim, com o cliente mandando o comprovante pela terceira vez.

Cobrar dos primeiros clientes é uma das dez perguntas que separam protótipo de produto, e ela vem depois de outras: o código é seu, o banco é seu, o login protege, dá pra voltar pra ontem. Pix ligado num app que ainda não é seu é dinheiro entrando numa casa com a porta de trás aberta. A ordem existe. Esse post foi um degrau dela.

Fontes