Pular para o conteúdo principal

24/08/2026

Suporte a mTLS na integração Pix com o Banrisul no Cidadão Web​

O Banrisul passou a exigir autenticação mútua (mTLS ou Mutual TLS, protocolo em que cliente e servidor validam um ao outro por certificado digital antes de trocar dados) nos endpoints da sua API Pix. Além da atualização das URLs de acesso, cada requisição financeira agora precisa apresentar um certificado digital do cliente (arquivo PFX) para ser validada pelo banco. Sem essa adequação, municípios que usam o Banrisul como convênio Pix teriam o serviço de emissão de Pix interrompido.

Agora, o sistema envia automaticamente o certificado digital PFX configurado pelo município em cada requisição que exigir autenticação mútua e não há mudança na forma como o Pix é gerado ou consultado, apenas na camada de segurança da comunicação com o banco, o formato das cargas de envio e resposta (payloads) continua o mesmo.

Enquanto o certificado e a senha não estiverem configurados, a emissão de Pix continua pelo fluxo anterior, sem mTLS. A partir do momento em que ambos estiverem configurados, o sistema passa a usar automaticamente o novo fluxo com mTLS.

Como configurar

  1. Acesse Cadastros > Convênios no Cidadão Web.
  2. No campo de banco, selecione Febraban, o Banrisul não aparece como opção individual; a integração segue o padrão Febraban.
  3. Habilite a opção Realizar configuração do Pix pelo Cidadão Web Fly.
  4. Informe as informações solicitadas e envie o certificado.
  5. Salve as configurações.

novidade

Se o certificado estiver ausente, expirado ou inválido, o Banrisul rejeita a conexão ainda na camada de transporte. O sistema registra o erro técnico para auditoria e retorna uma mensagem de falha de comunicação segura para o operador, sem impactar a emissão de guias e boletos (como IPTU e Guias Diversas), que segue seu fluxo normal independente do resultado do Pix.

ATENÇÃO
  • Se o certificado estiver ausente, expirado ou inválido, o Banrisul rejeita a conexão ainda na camada de transporte. Nesse caso, o sistema registra o erro técnico detalhado para fins de auditoria e retorna uma mensagem de falha de comunicação segura para o operador.
  • Falhas na integração Pix não impactam a emissão de guias e boletos (como IPTU e Guias Diversas), a emissão segue seu fluxo normal independente do resultado da geração do Pix. Apenas o pagamento via Pix fica indisponível até a configuração correta do certificado.