Índice do artigofaltam 3 min de leitura
Seu cliente escolhe o produto, confere o valor e aperta pagar. A tela fica girando. Passam alguns segundos e não aparece nem a confirmação nem um aviso de erro. Ele não sabe se o pagamento foi feito e faz o que qualquer pessoa faria: aperta de novo. Se a primeira tentativa já tinha passado, a mesma compra aparece duas vezes na fatura dele, e a reclamação chega à sua empresa.
Quem cobra por aplicativo, site ou sistema próprio já recebeu essa reclamação ou teme receber. Ela costuma ser tratada como azar, ou como descuido de quem apertou duas vezes. A segunda cobrança tem duas origens: a pessoa que aperta de novo e o aplicativo que repete o pedido sozinho quando a conexão falha. A Stripe, empresa de pagamentos usada por lojas e aplicativos, explicou em público como evita que o pedido repetido vire segunda cobrança.
Por que o sistema não sabe se cobrou?
Em 2017, o engenheiro Brandur Leach publicou no blog da Stripe como o sistema dela lida com isso. Um pagamento é uma conversa entre dois computadores pela internet, e a conexão pode cair em três pontos dessa conversa.
O seu aplicativo pede a cobrança ao provedor de pagamento, a empresa que processa a cobrança, como a Stripe. O provedor executa e responde. Leach descreve o que acontece quando essa conversa se interrompe em cada um dos pontos.
Nos dois últimos casos, o aplicativo vê a mesma coisa: nenhuma resposta.
Se o aplicativo tentar de novo e a cobrança já tiver acontecido, o cliente paga duas vezes. Leach recomenda tentar de novo, porque desistir também tem custo: a gente lê isso como a venda que se perde sem ninguém perceber. A cobrança dupla vira estorno e hora de atendimento. A venda perdida nem aparece no relatório.
O número que impede a segunda cobrança
Pense num restaurante. O garçom anota o pedido numa comanda numerada e leva à cozinha. Na dúvida se foi ouvido, ele volta e repete o pedido, mostrando a mesma comanda. A cozinha olha o número, vê que aquele pedido já foi lançado e dá a mesma resposta da primeira vez. Se o cliente, impaciente, chama outro garçom e pede de novo, a cozinha confere a mesma comanda e sai um prato só.
A saída que a Stripe descreve funciona assim. O seu aplicativo cria o número do pedido (o técnico chama de chave de idempotência) e manda junto com a cobrança, e o provedor de pagamento confere. Com esse número, o pedido pode ser repetido quantas vezes for preciso e o cliente é cobrado uma vez só.
Na prática, a gente cria o número quando o cliente abre a tela de pagamento, não a cada toque no botão. Assim o segundo clique chega com o mesmo número e também não vira segunda cobrança.
Sem o número do pedido
Duas cobranças na fatura- O cliente aperta de novo, ou o aplicativo repete sozinho
- O provedor trata como pedido novo
- Cobra outra vez
Com o mesmo número
Uma cobrança só- O pedido repetido leva o número da primeira vez
- O provedor reconhece o número
- Devolve a resposta guardada, sem cobrar
O nome técnico disso é idempotência: a operação pode ser repetida sem acontecer duas vezes. É a palavra que a sua equipe usa.
A Amazon usa o mesmo princípio nos próprios serviços de nuvem, como explica a Builders' Library, onde os engenheiros dela descrevem como os sistemas foram construídos.
O que o cliente vê também conta
A outra metade é a tela. A X-Apps, a empresa de software que escreve este blog, cuidou dela no BigPag, o aplicativo de uma conta digital. Antes, segundo o case, acompanhar o que já tinha sido pago dependia de memória e de prints.
No app, o pagamento passa por uma tela de conferir e outra de confirmar. Depois, ele aparece no extrato com o status, e o detalhe guarda o identificador e o comprovante pronto para compartilhar. Uma transferência não realizada já mostra o motivo, sem a pessoa precisar procurar o suporte. Com o status na tela, o cliente não precisa apertar pagar de novo para saber se pagou.
Quatro perguntas para quem cuida do seu sistema
Você não precisa saber como o número do pedido é criado nem onde ele fica guardado. Precisa saber se alguém pensou no assunto. Estas perguntas servem para a sua equipe ou para a empresa contratada:
- Se a resposta do provedor de pagamento não voltar, o nosso sistema tenta de novo? Boa resposta: sim, sozinho.
- Quando tenta, manda o mesmo número do pedido da primeira vez, e o nosso provedor de pagamento aceita esse número? Boa resposta: sim para as duas, e o que a gente recomenda é que o número nasça quando o cliente abre o pagamento.
- O que o cliente vê enquanto espera? Boa resposta: o botão trava e a tela avisa que o pagamento está em processamento.
- Se mesmo assim uma cobrança sair repetida, como a gente descobre e desfaz? Boa resposta: um relatório compara pedidos e cobranças, e o estorno sai no mesmo dia.
Se a sua empresa ainda vai escolher com quem processar os pagamentos, o texto sobre como escolher um provedor de pagamento para o aplicativo lista os cuidados dessa escolha, entre eles a tentativa de pagar duas vezes.
Fontes: Brandur Leach, "Designing robust and predictable APIs with idempotency", blog de engenharia da Stripe, 22/02/2017; Malcolm Featonby, "Making retries safe with idempotent APIs", Amazon Builders' Library, página sem data. Leitura em 13/11/2026.
