API Pix e Pix Automático: o que a empresa precisa para receber com baixa automática

A API trabalha com duas espécies de cobrança. A cobrança imediata (recurso /cob) serve para o pagamento no ato: checkout de loja virtual, balcão, totem. Ela é criada com PUT /cob/{txid} e tem um prazo de expiração em segundos. Se o sistema não informar esse prazo, o manual define 86.400 segundos, ou seja, 24 horas a partir da criação.

A cobrança com vencimento (recurso /cobv) atende mensalidades, faturas e boletos que migram para o Pix. Ela exige data de vencimento, dados do devedor e um campo que diz por quantos dias corridos depois do vencimento a cobrança ainda aceita pagamento. Juros, multa, desconto e abatimento são informados na criação, e quem calcula o valor final a pagar é o PSP, seguindo as regras do manual. Se o vencimento cair em fim de semana ou feriado para o pagador, ele é prorrogado para o dia útil seguinte.

No QR Code estático, todos os dados ficam dentro da própria imagem: chave Pix obrigatória e, opcionalmente, valor, identificador da transação e um texto livre. Ele não é gerado pela API Pix. O identificador nesse caso tem até 25 caracteres, e o banco não tem como garantir que ele não se repita, porque o código nunca foi registrado. A consistência da conciliação fica inteiramente com o recebedor, e a API só permite consultar os Pix recebidos com determinado txid.

O QR Code dinâmico contém uma URL que o aplicativo do pagador consulta no momento da leitura. É ali que ficam valor, vencimento, juros e demais dados da cobrança.

O txid é o identificador que amarra o pagamento à cobrança. Nas cobranças criadas pela API, ele deve ter de 26 a 35 caracteres, só letras sem acento e dígitos, e é único por CPF ou CNPJ do recebedor dentro do mesmo PSP. Um txid não pode ser reutilizado nem depois que a cobrança foi cancelada, e uma cobrança imediata e uma com vencimento não podem compartilhar o mesmo txid.

O manual explica por que vale a pena o sistema gerar o próprio txid: é isso que garante a idempotência. Se a chamada de criação falhar por timeout, o sistema repete o PUT com o mesmo txid e não corre o risco de criar duas cobranças para a mesma venda. Na cobrança imediata é possível delegar a geração do txid ao PSP, mas o próprio Banco Central avisa que, nesse caso, a idempotência não é garantida.

O Manual de Padrões para Iniciação do Pix obriga o PSP a implementar OAuth 2.0 com TLS mútuo (mTLS), no fluxo Client Credentials, sobre TLS 1.2 ou superior. Na prática, o sistema da empresa apresenta um certificado digital na conexão e recebe um token de acesso vinculado a esse certificado. O servidor do banco confere se o certificado usado na chamada é o mesmo ao qual o token foi emitido, o que impede o uso de um token vazado a partir de outra máquina.

Sobre a origem do certificado, o manual diz que ele pode ser emitido pelo próprio PSP ou por autoridades certificadoras externas, conforme cada PSP definir. Certificados autoassinados pelo cliente não devem ser aceitos. Por isso, antes de comprar qualquer certificado, confirme com o banco qual formato ele exige; muitos entregam o certificado no próprio portal de desenvolvedor.

O client_id fica vinculado ao CPF ou CNPJ do recebedor, e cada credencial recebe escopos que limitam as operações permitidas. Certificado, client_id e segredo movimentam dinheiro: devem ficar em cofre de segredos, nunca no repositório de código, com troca programada antes do vencimento do certificado.

Com webhook, o PSP avisa o sistema quando o Pix é liquidado, sem consultas repetidas. A configuração é feita por chave Pix, com PUT /webhook/{chave}, e só Pix associados a um txid geram notificação. Um Pix feito por digitação da chave, sem txid, não chega pelo webhook, e o sistema precisa de outra rotina para tratá-lo.

As notificações trafegam por canal mTLS, e o Banco Central recomenda usar os mesmos certificados da API. Mesmo assim, trate cada notificação como um aviso e confirme o pagamento consultando a API (GET /pix/{e2eid} ou GET /cob/{txid}) antes de dar baixa. Isso protege contra chamadas forjadas e contra notificações repetidas, que devem ser processadas sem gerar baixa em dobro. Guarde o endToEndId de cada Pix recebido e use-o como chave única no banco de dados.

Com um txid próprio por cobrança, o pagamento recebido aponta direto para o pedido ou a fatura, e a baixa acontece sem intervenção humana. Uma rotina diária que compara os Pix recebidos no período (GET /pix com início e fim) com as baixas registradas pega o que escapou do webhook.

A devolução é solicitada com PUT /pix/{e2eid}/devolucao/{id}, em que o id é gerado pelo sistema da empresa e deve ser único para aquele Pix. Um mesmo Pix aceita várias devoluções parciais, desde que a soma não ultrapasse o valor original. A devolução passa pelos estados EM_PROCESSAMENTO, DEVOLVIDO ou NAO_REALIZADO, e o sistema deve consultar o resultado antes de informar o cliente, já que falta de saldo, por exemplo, impede a liquidação.

O Pix Automático entrou em funcionamento em 16 de junho de 2025. Com uma única autorização prévia do pagador, o recebedor passa a cobrar mensalidades, assinaturas e contas de consumo sem que cada pagamento precise ser aprovado. O valor pode ser fixo ou variável; no variável, o pagador pode definir um teto, e o banco dele rejeita cobranças acima desse limite.

A recorrência (/rec) descreve o contrato: recebedor, objeto da cobrança, periodicidade, data inicial e política de novas tentativas. A autorização pode ser pedida de quatro formas, numeradas de 1 a 4 no manual. Na primeira, o recebedor envia uma solicitação de confirmação (/solicrec) que aparece no aplicativo do banco do pagador, sem QR Code. Nas outras três, o pagador lê um QR Code composto, que pode trazer só a recorrência, a recorrência com o primeiro pagamento imediato ou a recorrência junto de uma cobrança com vencimento.

Depois de autorizada a recorrência, cada fatura vira uma cobrança recorrente (POST /cobr), sem QR Code. Duas diferenças pesam no desenho do sistema. O Pix Automático não usa chave Pix, então a cobrança precisa dos dados bancários completos de recebedor e pagador. E a instrução de pagamento deve chegar ao banco do pagador entre 2 e 10 dias corridos antes da data de liquidação, que tem de coincidir com o vencimento. Por isso cada cobrança precisa ser gerada com essa antecedência.

A política de retentativa é escolhida na recorrência: sem novas tentativas, ou até três tentativas em dias diferentes dentro de sete dias corridos após a data prevista. Há webhooks específicos para acompanhar recorrências (/webhookrec) e cobranças recorrentes (/webhookcobr). Pagador e recebedor podem cancelar a autorização unilateralmente, e o sistema precisa registrar o cancelamento para parar de emitir cobranças.

Os problemas mais frequentes em produção nascem de decisões tomadas no início da integração:

• Gerar o txid a cada tentativa de chamada, o que cria cobranças duplicadas quando a rede falha.
• Dar baixa apenas com base no corpo do webhook, sem consultar a API para confirmar valor e situação.
• Esperar pelo webhook para Pix feitos sem txid, que nunca geram notificação.
• Tratar o estado CONCLUIDA como quitação da dívida. Ele só indica que a cobrança não aceita novos pagamentos; a baixa deve partir do Pix recebido, com valor conferido.
• Deixar o certificado vencer sem aviso, o que derruba a emissão de cobranças e o recebimento de webhooks ao mesmo tempo.
• Emitir a cobrança do Pix Automático no dia do vencimento, fora da janela de 2 a 10 dias exigida pelo banco do pagador.

Antes de escrever a primeira linha de código, alguns itens precisam estar resolvidos com o banco e com a equipe interna:

• Conta PJ com chave Pix em um PSP que ofereça a API Pix e, se for o caso, o Pix Automático.
• Adesão à API no portal do banco, com client_id, segredo e escopos adequados a cada aplicação.
• Certificado para o mTLS no formato que o banco exige, com data de renovação registrada.
• Acesso ao ambiente de homologação do banco e plano de testes para cob, cobv, webhook e devolução.
• Endpoint HTTPS para o webhook, preparado para mTLS e para receber notificações repetidas.
• Regra definida para gerar txid único por cobrança e para guardar o endToEndId de cada Pix.
• Rotina diária de conferência entre Pix recebidos e baixas registradas.

A Tox já integrou sistemas à API Pix de bancos, com criação de cobranças, recebimento por webhook e baixa automática. Se a sua empresa quer tirar a conciliação do Pix das mãos do financeiro, podemos avaliar o sistema atual e o banco escolhido e indicar o caminho de integração.