O que muda no Itaú
Portal: Itaú for Developers — devportal.itau.com.br. O client_id e o token chegam pelo gerente; o portal é usado para emitir/gerir o certificado.
client_id + um token temporário, gera você mesmo a chave privada e o pedido de certificado (CSR), e precisa de 3 credenciais separadas (PIX, Pagamentos e Cobrança), cada uma com seu próprio certificado.
| Campo no sistema | De onde vem | Itaú |
|---|---|---|
| Client ID | gerente / portal do banco | ✓ (1 por produto) |
| Client Secret | emissão no portal | ✓ (1 por produto) |
| Certificado (PEM) | arquivo .crt emitido no portal | ✓ (1 por produto) |
| Chave privada (PEM) | arquivo .key — você gera (CSR) | ✓ |
| Chave PIX recebedora | sua chave PIX da conta | ✓ (no bloco PIX) |
1 · Solicitar ao banco
Pelo gerente da conta / OfficerCash, solicite:
- Habilitar o SISPAG na conta PJ (necessário para pagamentos / PIX enviado).
- Credenciais para os 3 produtos: Pix Recebimentos, Pix Pagamentos (depende do SISPAG) e Cobrança com o escopo unificado BOLECODE (boleto + PIX no mesmo título).
- O manual de Pix Pagamentos (não é público) — define os caminhos e a idempotência do envio.
- Confirme o que existe de webhook (o Itaú normalmente só notifica PIX recebido; PIX enviado e boleto pago não têm webhook — é esperado).
client_id + um token temporário (chega em ~1 dia útil, validade curta — cerca de 7 dias). Gere o certificado assim que o token chegar, senão ele expira e o processo recomeça.
2 · Gerar o certificado (repetir por produto)
Você faz isto 3 vezes, porque o Itaú emite credenciais e certificado separados por produto.
O Itaú assina um certificado a partir de um CSR que você gera. Use RSA 2048 e, no campo CN (Common Name), exatamente o seu client_id.
# 1) chave privada (guarde com cuidado — é a "Chave privada (PEM)" do sistema) openssl genrsa -out itau_pix.key 2048 # 2) CSR com CN = client_id (troque os demais campos pela sua empresa) openssl req -new -key itau_pix.key \ -subj "/CN=SEU_CLIENT_ID/OU=SUA_EMPRESA/L=SAO PAULO/ST=SP/C=BR" \ -out itau_pix.csr
C600 / C800). O CN do CSR precisa ser idêntico ao client_id do produto.
- Informe o Client Secret / token temporário para gerar o token de emissão.
- Envie o CSR / preencha os campos de identificação solicitados.
- Gere o certificado e baixe o
.crt. - No fluxo de PIX regulatório, a resposta da emissão também traz o client_secret definitivo do produto. Guarde-o.
.crt só pode ser baixado uma vez — não saia da tela antes de concluir o download.
Ao final, para cada produto, você terá: client_id + client_secret + .crt (certificado) + .key (a chave gerada no passo 2).
3 · Cadastrar no sistema
Na conta, defina Integração bancária → Itaú e salve. Em "Gerenciar credenciais" aparecem 3 blocos:
- PIX (recebimentos) — Client ID, Secret, Certificado, Chave privada + Chave PIX recebedora
- Pagamentos (PIX enviado) — Client ID, Secret, Certificado, Chave privada
- Cobrança (boletos) — Client ID, Secret, Certificado, Chave privada
Em cada bloco use os valores daquele produto. No bloco Cobrança, mantenha Emitir boletos em modo validação (teste) marcado durante a homologação e desmarque só para emitir boletos reais.
4 · Webhook, homologação e ativação
A tela mostra 1 URL de webhook (PIX recebido). O registro no Hub de Notificação do Itaú — primeiro em homologação, depois em produção — é conduzido junto com o administrador da plataforma; você só precisa ter salvado as credenciais do bloco PIX antes. Não há webhook de boleto nem de PIX enviado — é normal.
- Homologação primeiro: o sandbox usa um JWT de teste (sem mTLS); a produção usa OAuth2 + mTLS. Valide PIX recebido em homologação e boleto em modo validação.
- Produção: desmarque "Emitir boletos em modo validação" e marque Integração ativada (em produção) na conta.
Renovação dos certificados
itau:pix). Renove dentro da janela permitida pelo Itaú (últimos ~30 dias) do produto indicado no alerta e atualize Certificado e Chave privada daquele bloco.
Dúvidas comuns
- Por que 3 credenciais?
- O Itaú emite credenciais e certificado separados por produto: PIX (recebimentos), Pagamentos (PIX enviado) e Cobrança (boletos). Cada bloco no sistema corresponde a um produto.
- CSR e CN
- O CSR é o pedido de certificado que você gera (RSA 2048). O CN precisa ser idêntico ao
client_iddo produto — se divergir, dá erro de autenticação. - Erro
403/C600/C800 - Quase sempre é o certificado ausente no handshake ou o CN do CSR diferente do
client_id. - "Modo validação (teste)" na Cobrança
- Emite boletos de homologação. Mantenha marcado durante os testes e desmarque só para emitir boletos reais.
- Sem webhook de boleto / PIX enviado
- É esperado: o Itaú só notifica PIX recebido. O restante o sistema confere consultando o banco de novo.