← todos os posts
Tutorial 9 min de leitura

"Cobrar em real: o que a IA erra em Pix, cartão e nota fiscal"

O "pagamento aprovado" é a parte fácil. Os oito estados que ninguém testa é que derrubam o app — e o mais caro deles chega sem fazer barulho nenhum.

Um desenvolvedor brasileiro resumiu o assunto de hoje melhor do que eu conseguiria:

"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."

É a avaliação dele num fórum, não uma medição — ninguém contou quantas integrações saem erradas. Mas a explicação está certa, e é o que interessa: a IA aprendeu com o que estava escrito na internet. Sobre cobrar com cartão nos Estados Unidos existe uma montanha de material. Sobre Pix, nota fiscal de serviço e regra brasileira que muda todo ano, existe pouco, espalhado e velho.

Ou seja: justamente no assunto em que o erro tira dinheiro do seu bolso, ela é mais fraca. Este post é sobre conferir isso sozinho.

O caminho feliz engana

Peça pra IA colocar pagamento no app e ela entrega isto:

cliente clica em pagar
        ↓
tela de pagamento
        ↓
"Pagamento aprovado 🎉"
        ↓
acesso liberado

Funciona. Você testa, aprova, publica.

E aqui está o problema: isso é uma fatia pequena do sistema de cobrança. O resto são os caminhos que não terminam em festa, e cada um é um jeito diferente de perder dinheiro ou perder cliente.

Os oito estados que quase ninguém testa

Escreva os oito num papel. É o seu roteiro.

  1. Recusado — banco negou. O cliente vê o quê? Consegue tentar com outro cartão?
  2. Aviso atrasado — o pagamento passou, o aviso demorou dois minutos. O cliente ficou dois minutos olhando pra tela sem acesso.
  3. Aviso duplicado — o mesmo pagamento avisado duas vezes. Voltamos nele; é o pior da lista.
  4. Cancelamento — o acesso cai na hora (errado) ou no fim do período já pago (certo)?
  5. Troca de plano — subiu ou desceu no meio do mês. Cobra a diferença? Devolve?
  6. Estorno — você devolve o dinheiro. O acesso sai junto, ou o cliente fica com os dois?
  7. Contestação — o cliente reclama no banco dele, não com você. O dinheiro sai antes da conversa.
  8. Assinatura expirada — o cartão venceu, a cobrança do mês falhou. O acesso fica aberto até quando?

Nenhum desses oito aparece no caminho feliz. Se você só testou "paguei e entrei", testou um de nove.

Primeiro, uma palavra que você precisa ter: o aviso

Quando alguém paga, o seu app não fica sabendo sozinho — quem sabe é o sistema de pagamento. Então ele manda um aviso pro seu app: "o pagamento tal foi aprovado". Seu app recebe e libera o acesso. (Em inglês isso se chama webhook, e é assim que estará escrito em todo tutorial que você achar.)

Esse aviso é a peça mais frágil de tudo, e onde mora o erro mais caro.

O erro mais caro é o mais silencioso: o aviso repetido

Os números das próprias empresas explicam o mecanismo melhor que qualquer analogia.

O Mercado Pago documenta que o seu app tem 22 segundos pra confirmar que recebeu o aviso. Sem essa confirmação, o sistema entende que o aviso se perdeu e reenvia a cada 15 minutos até obter resposta.

Olha o que isso significa. Seu app recebeu o aviso, liberou o acesso, mandou o e-mail de boas-vindas, gerou a nota — e levou 25 segundos pra terminar. De fora, isso é indistinguível de um app que não recebeu nada. Quinze minutos depois chega o mesmo aviso. Seu app libera de novo, manda o e-mail de novo, gera outra nota. Ninguém vê erro em lugar nenhum.

A Stripe é ainda mais explícita. Duas frases da documentação dela, pra ler devagar:

"Ocasionalmente, os endpoints de webhook podem receber o mesmo evento mais de uma vez."

"A Stripe não garante a entrega dos eventos na ordem em que foram gerados."

Ela também documenta que insiste por até três dias. Ou seja: não é defeito nem azar seu. Aviso repetido e fora de ordem é o funcionamento normal e documentado do sistema — cobrança que não foi construída contando com isso está errada desde o primeiro dia, mesmo enquanto parece funcionar.

A recomendação da própria Stripe é a solução inteira: guarde os identificadores dos avisos já processados e não processe de novo o que está na lista.

Como pedir isso sem saber programar

É um caderno de recibos: cada aviso tem um número, e antes de agir o app olha se o número já está no caderno. Se estiver, ignora. Peça exatamente assim:

"Antes de processar qualquer aviso de pagamento, grave o identificador do evento numa tabela e verifique se ele já foi processado. Se já foi, responda com sucesso e não faça nada. Responda o aviso imediatamente e faça o trabalho pesado depois. Me diga como eu testo isso mandando o mesmo aviso duas vezes."

A última frase é a que importa: peça o teste junto. Sem ela você tem só a palavra da IA de que está tratado, que é o tipo de resposta que não vale nada.

O recebimento de pagamento do site da minha empresa tem esse caderno de recibos justamente porque eu descobri, do jeito chato, que o aviso chega repetido bem mais do que a intuição sugere.

O teste que você faz hoje: force a recusa

Todo sistema de pagamento tem um modo de teste com cartões falsos. Na Stripe, a documentação oficial lista estes:

4242 4242 4242 4242   aprovado
4000 0000 0000 0002   recusado (recusa genérica)
4000 0000 0000 9995   recusado por saldo insuficiente
4000 0000 0000 9987   cartão perdido
4000 0007 6000 0002   cartão brasileiro (Visa, em real)

Validade: qualquer data futura. Código de segurança: três dígitos quaisquer.

Todo mundo testa o primeiro. Quase ninguém testa o segundo. E é o segundo que mostra se o app está pronto:

  • A mensagem de erro saiu em português, ou apareceu um texto em inglês do sistema de pagamento?
  • Dá pra tentar com outro cartão, ou o cliente ficou preso numa tela sem saída?
  • Ficou um pedido meio criado no banco de dados, ocupando lugar como se fosse venda?
  • Chegou e-mail de boas-vindas pra quem não pagou?

Se alguma dessas respostas te surpreendeu, você encontrou dinheiro parado no chão — cartão recusado é comum, não é exceção.

As armadilhas que são só nossas

Agora o que a IA erra por ser brasileiro. Está tudo na documentação oficial, e nada disso ela te avisa por conta própria.

Pix tem teto, e ele é baixo. Na Stripe, cada Pix vai de R$ 0,50 a no máximo R$ 3.000. Produto mais caro que isso não fecha por Pix — e o cliente descobre no meio do pagamento.

Pix recorrente não é a mesma coisa que Pix. A Stripe documenta que o Pix Automático, o de cobrança repetida, não está disponível para contas brasileiras: no Brasil, só pagamento único. Se o seu app é assinatura mensal, esse é o momento de descobrir — não depois da página de vendas pronta.

Pix tem contestação, e você não se defende. Muita gente escolhe Pix acreditando que é dinheiro irreversível. A documentação é dura: o cliente pode contestar no banco dele, e "você não pode contestar essas contestações" — se o parceiro aceitar, o valor sai da sua conta. Reembolso feito por você, aliás, vale até 90 dias; depois disso o botão não existe mais.

O nome no extrato do cliente não é o seu. O texto que você escolhe pra aparecer na fatura é ignorado no Pix: quem aparece como destinatário é o processador parceiro. Traduzindo: seu cliente abre o aplicativo do banco, vê um nome que nunca ouviu falar e te manda mensagem perguntando que cobrança é aquela. Não é bug. É um e-mail que você precisa escrever antes de acontecer.

Conta fora do Brasil tem imposto no meio. Compra internacional paga com Pix leva IOF de 3,5%, e por padrão quem paga é o cliente — o valor no aplicativo dele fica maior que o preço anunciado.

Nota fiscal: a regra mudou há um mês

A nota fiscal de serviço passou a ter padrão nacional, com um emissor único do governo. A obrigatoriedade de emitir por ele, para quem é do Simples Nacional, estava marcada para 1º de setembro de 2026 e foi adiada para 1º de novembro de 2026 pela Resolução CGSN nº 191, de 4 de agosto de 2026.

Repare na data: essa mudança tem semanas. Nenhum modelo de IA tem isso decorado com confiança — e a resposta errada vai soar exatamente tão segura quanto a certa.

Obrigação fiscal você confirma no site do governo ou com o seu contador, sem exceção. A IA serve pra escrever o código que chama o emissor. Não serve pra dizer se você precisa emitir.

E o erro mais bobo de todos

As chaves de acesso do sistema de pagamento que funcionavam na sua máquina não vão junto quando você publica: elas ficam guardadas fora do código e precisam ser configuradas de novo no serviço onde o app roda. O sintoma é cruel — tudo funciona no teste, e no ar o botão de pagar não faz nada. Isso aparece muito em relato de quem conserta app feito com IA no Brasil; é o que a comunidade anda dizendo, não é medição, e bate com o que eu vejo.

O irmão desse erro é pior: publicar com a chave de teste em vez da real. O cliente paga, a tela dá parabéns, e o dinheiro não existe.

O checklist antes de cobrar do primeiro cliente

[ ] Testei o cartão recusado, não só o aprovado
[ ] O mesmo aviso chegando duas vezes libera acesso UMA vez
[ ] Meu app responde o aviso em menos de 22 segundos
[ ] Cancelamento tira o acesso no fim do período, não na hora
[ ] Estorno tira o acesso junto
[ ] Sei o teto do Pix e o meu preço cabe nele
[ ] Sei o que meu cliente vê no extrato do banco dele
[ ] As chaves no ar são as reais, e estão configuradas no serviço certo
[ ] Confirmei a regra de nota fiscal no site do governo ou com contador

Nove linhas, uma tarde. Do outro lado dela você para de descobrir problema de cobrança por mensagem de cliente irritado. Quem cobra dinheiro dos outros tem obrigação de conhecer os caminhos que não terminam em festa — e isso é competência de dono, não de programador.

Fontes