Integração PIX: por que a API é a parte fácil (e o que realmente dá trabalho)

Sempre que começo uma integração PIX, lembro da mesma coisa: a API é só uma pequena parte do projeto.

Consumir o endpoint, gerar uma cobrança, receber um pagamento, isso costuma ser o trecho mais tranquilo. O trabalho de verdade começa quando entram webhooks, conciliação, devoluções e todos aqueles cenários que ninguém lembra durante o planejamento. E é exatamente aí que as integrações de pagamento estouram prazo ou geram surpresa em produção.

Neste artigo, vou destrinchar os três pontos que sempre valido antes de começar uma integração PIX e por que cada um deles importa mais do que a API em si.

A API é só o começo

Uma integração de pagamento não termina quando o pagamento é criado. Ela "vive" no que acontece depois: a notificação que chega (ou não chega), o valor que precisa bater no fim do dia, o cliente que pede a devolução, a chamada que chega duplicada. Tratar a API como o projeto inteiro é o erro que atrasa a maioria dos times.

Vamos aos três pontos.

1. Tratar o PIX como só mais um meio de pagamento

Não é. O PIX tem regras próprias que cartão e boleto não têm: fluxo de devolução (incluindo o Mecanismo Especial de Devolução, o MED, para casos de fraude), liquidação em segundos, disponibilidade 24/7 e identificadores específicos como o txid e o EndToEndId.

Quem trata o PIX como "só mais um meio de pagamento" acaba descobrindo essas diferenças em produção do jeito ruim. A integração em si costuma ser a parte fácil; o desafio aparece quando entram as devoluções, os webhooks e o tratamento de exceções que são específicos desse arranjo.

2. Deixar a conciliação para depois

Já vi equipes implementarem todo o fluxo de pagamento e só "lembrarem" da conciliação quando começaram a aparecer diferenças financeiras em produção. Nessa hora, normalmente ninguém está feliz.

Conciliação não é um passo do fim, é (tem que ser) requisito desde o início. Na prática, significa cruzar o que o seu sistema registrou com o extrato do PSP ou do banco, verificando cada transação por um identificador confiável (o EndToEndId é um bom candidato, porque identifica a transação de ponta a ponta). Sem isso, as divergências se acumulam silenciosamente e só aparecem no fechamento, quando já viraram um problema financeiro.

Um bom desenho de conciliação prevê: transações que não batem, pagamentos recebidos sem pedido correspondente, devoluções parciais e totais, e um painel de exceções que mostra só o que precisa de atenção humana.

3. Não tratar requisições duplicadas como um cenário normal

Esse é o ponto mais subestimado e o que mais gera "pagamento fantasma".

Há alguns dias, eu e meu sócio, o Cláudio Santos, tivemos uma conversa interessante com um parceiro comercial sobre resiliência de integração e idempotência. Em determinado momento, levantei uma questão:

"Como vocês estão tratando uma eventual duplicidade de chamadas no webhook?"

A resposta foi mais ou menos assim:

"Mas por que vocês enviariam a mesma informação duas vezes?"

E a minha resposta foi simples:

"A ideia é justamente não enviar. Mas trabalhamos com TI... falhas acontecem. Existem timeouts, retries, problemas de rede e processos de recuperação. Quanto mais preparada a integração estiver para esses cenários, menor o impacto quando eles acontecerem."

Em sistemas distribuídos, não trabalhamos com a expectativa de que tudo vai funcionar perfeitamente o tempo todo. Trabalhamos para que, quando algo der errado, o sistema continue consistente.

O que é idempotência (e por que ela salva o seu caixa)

Idempotência é a garantia de que processar a mesma mensagem duas vezes tem o mesmo efeito que processá-la uma vez. Aplicada a pagamentos: se o mesmo webhook chegar duas vezes, o cliente não é cobrado (nem creditado) duas vezes.

Na prática, dá para tratar isso assim:

• Use uma chave de idempotência. No PIX, o EndToEndId funciona como identificador natural da transação. Registre os eventos já processados por essa chave.
• Deduplique antes de processar. Ao receber um webhook, verifique se aquele evento já foi tratado. Se já foi, responda com sucesso e não repita o efeito.
• Responda de forma idempotente. O emissor do webhook espera uma confirmação; se ele não recebe (timeout), ele reenvia. Seu endpoint precisa aguentar esse reenvio sem duplicar nada.
• Assuma entrega "pelo menos uma vez". A maioria dos provedores de webhook garante at-least-once, não exactly-once. Ou seja: a duplicidade não é exceção rara, é comportamento esperado.

Timeouts acontecem. Retries acontecem. Webhooks podem ser entregues mais de uma vez. Se a integração não foi pensada para esses cenários desde o início, mais cedo ou mais tarde algum pagamento vai gerar uma surpresa.

Checklist: o que validar antes de integrar o PIX

Antes de escrever a primeira linha da integração, garanta resposta clara para estes pontos:

• Webhooks: como você trata reenvios, atrasos e entregas duplicadas.
• Idempotência: qual é a sua chave e onde você registra os eventos já processados.
• Conciliação: como e com que frequência você cruza seus registros com o extrato do PSP/banco.
• Devoluções: fluxo de devolução total e parcial, e tratamento do MED.
• Segurança: validação da origem do webhook e proteção dos dados.
• Observabilidade: visibilidade para detectar um problema pequeno antes que ele vire incidente.

Perguntas frequentes

Integrar o PIX é difícil?

A parte da API costuma ser simples. A complexidade está nos cenários ao redor: webhooks duplicados, conciliação, devoluções e tratamento de exceções. É aí que os projetos atrasam.

O que é idempotência em pagamentos?

É a garantia de que processar a mesma notificação mais de uma vez não gera efeito duplicado por exemplo, não credita o mesmo PIX duas vezes. É essencial porque webhooks podem ser entregues mais de uma vez.

Por que a conciliação do PIX é importante?

Porque é o que garante que o que o seu sistema registrou corresponde ao que de fato foi liquidado. Sem conciliação desde o início, divergências financeiras aparecem só no fechamento.

O que é o EndToEndId no PIX?

É o identificador único de ponta a ponta de uma transação PIX. Ele serve tanto para conciliar quanto como chave natural de idempotência ao tratar webhooks.

Precisa integrar o PIX com segurança?

Se a sua operação depende de pagamentos que não podem falhar, vale desenhar a integração para os cenários reais desde o início para não remendar depois. Fale com a T4tech e vamos conversar sobre a sua integração.