Integração Banco do Brasil

A integração com o Banco do Brasil liga a conta PJ da sua empresa ao sistema. As cobranças das vendas saem como PIX ou como boleto registrado com QR Code PIX, e o dinheiro cai direto na conta, pela tarifa que você já tem com o banco.

O que a integração faz

PIX. Gera a cobrança com QR Code e copia e cola. A chave PIX é a da conta do Banco do Brasil.
Boleto registrado com PIX. O boleto é registrado no banco na hora, com QR Code PIX. O sistema gera o PDF do boleto, e o cliente paga pelo código de barras ou pela linha digitável.
Baixa automática. O sistema consulta o banco e dá baixa no pedido quando o pagamento aparece.
Cancelamento. Cancelar a transação no sistema baixa o boleto no banco, ou remove a cobrança PIX, e ela deixa de aceitar pagamento.

A integração não processa cartão. Para cartão, use um gateway (veja Integrações de Pagamento).

O que você precisa antes de começar

Item	Onde conseguir	Para quê
Client ID, Client Secret e Application Key	Portal Developers BB, na aplicação da empresa	PIX e boleto
Chave PIX da conta no Banco do Brasil	Aplicativo ou internet banking do banco	PIX
Certificado digital A1 (e-CNPJ) da empresa, em arquivo .pfx ou .p12, com a senha	Certificadora da empresa	PIX em produção
Convênio de cobrança (7 dígitos), carteira e variação da carteira	Contrato de cobrança, com o gerente da conta	Boleto

Quem só vai cobrar por PIX não precisa do convênio. Quem só vai emitir boleto não precisa do certificado.

Passo 1: criar a aplicação no Portal Developers BB

A aplicação é da sua empresa: ela é criada no portal por quem representa a empresa e fica vinculada ao CNPJ titular da conta e do convênio. As credenciais dela são as que entram no sistema.

Acesse o Portal Developers BB e entre com o usuário da empresa.
Crie uma aplicação e adicione a API Pix, a API Cobranças (boleto) ou as duas, conforme o que vai usar.
Na aba Credenciais, copie o Client ID, o Client Secret e a Application Key (no portal ela aparece como developer_application_key).
Para cobrar de verdade, clique em Enviar para produção, confirme o CNPJ da empresa (depois de confirmado, ele não pode ser trocado) e conclua a contratação. Use as credenciais de produção: as de teste só funcionam no ambiente de homologação.
Para o PIX em produção, o banco precisa conhecer o certificado A1 da empresa. Isso é feito depois de conectar, no Passo 3.

Passo 2: conectar no sistema

No menu lateral, clique em Sistema e em Integrações.
Busque por “Banco do Brasil” e clique em Conectar.
Preencha a janela:

Campo	O que informar
Nome da conexão	Como a conta aparece nas telas do sistema
Client ID e Client Secret	As credenciais da aplicação
Application Key (developer_application_key)	A chave da aplicação. Sem ela a conexão não é validada
Certificado Digital e Senha do Certificado	O arquivo .pfx ou .p12 do e-CNPJ e a senha. Obrigatório para PIX em produção
Ambiente de Conexão	Produção para cobrar de verdade, Homologação para testar

Clique em Conectar e testar conexão. O sistema pede um acesso ao banco com as credenciais: se elas estiverem erradas, a mensagem do banco aparece na tela.

Passo 3: enviar o certificado ao banco

Este passo vale só para o PIX em produção: o banco só aceita a cobrança com um certificado que ele já conhece. O sistema entrega os arquivos prontos para o cadastro, sem a chave privada e sem a senha.

Em Sistema > Integrações, abra a conexão do Banco do Brasil já salva com o certificado.
No quadro Certificado enviado nesta conexão, clique em Baixar certificados para o Portal BB.
A lista aparece na ordem de envio: Certificado da empresa, os intermediários e o Certificado raiz. Em cada linha, clique em Baixar para salvar o arquivo .cer, ou em Copiar para colar o conteúdo no portal.
No Portal Developers BB, abra a aplicação, entre em Certificados e envie cada certificado, na ordem da lista.
Aguarde o banco mostrar o envio como concluído. Só então o PIX de produção passa a funcionar.

Se aparecer o aviso de que o arquivo não traz os certificados da autoridade certificadora até a raiz, o .pfx enviado está incompleto. Peça à certificadora o arquivo com a cadeia completa e envie-o de novo na conexão.

O botão aparece para quem tem a permissão Baixar certificado, no grupo Sistema/Integrações. Quando o certificado for renovado, repita este passo com o novo.

Passo 4: ligar à forma de pagamento

Conectar não basta: cada forma de pagamento precisa apontar para a integração.

Clique em Vendas, depois em Pagamentos e em Formas de Pagamento.
Abra (ou crie) a forma do tipo PIX ou Boleto e vá para a aba Pagamento Online.
No campo Integração, escolha a conexão do Banco do Brasil.
No PIX, preencha a Chave PIX da conta do Banco do Brasil.
No boleto, preencha Convênio de cobrança, Carteira e Variação da carteira, com os números do contrato de cobrança. Os três são obrigatórios e levam só números: sem eles a forma de pagamento não salva.
Ative Disponível no checkout online e salve.

Faça isso uma vez para o PIX e outra para o boleto. A empresa com mais de um convênio cria uma forma de pagamento de boleto para cada um, todas ligadas à mesma conexão. O passo a passo completo da tela está em Integrações de Pagamento.

Como a baixa acontece

Nesta integração o pagamento não chega por aviso do banco. É o sistema que consulta o Banco do Brasil:

PIX: a cobrança pendente é consultada a cada sincronização automática das transações, até ser paga ou expirar.
Boleto ainda não vencido: é consultado a cada 6 horas.
Boleto vencido que ainda aceita pagamento: é consultado a cada sincronização automática.

Para não esperar, abra Vendas > Pagamentos > Transações, selecione a transação e clique em Sincronizar: o sistema consulta o banco na hora.

Regras e limites

Convênio: a cobrança pelo sistema usa convênio de 7 dígitos.
Número do boleto: é gerado pelo sistema, dentro do convênio informado na forma de pagamento.
Boleto em PDF: o banco registra o boleto e não fornece o arquivo. O sistema gera o PDF, com a linha digitável e o código de barras que o banco devolveu, no layout Boleto bancário dos relatórios, que pode ser personalizado. Na tela de pagamento o cliente clica em Abrir Boleto para ver o PDF ou em Copiar para levar a linha digitável ao aplicativo do banco dele. A mesma tela mostra o QR Code PIX do boleto e o botão Copiar do código PIX. O QR Code não aparece no PDF.
Link do boleto: abre sem login enquanto a cobrança está pendente. Depois de paga ou cancelada, o link mostra o aviso “Este boleto não está mais em aberto”.
Pagador do boleto: o banco exige nome, CPF ou CNPJ e endereço com CEP. Com o cadastro do cliente incompleto, o banco recusa o boleto e a mensagem dele aparece na tela.
Pagador do PIX: o cliente vai identificado pelo nome e pelo CPF ou CNPJ. Quando falta um dos dois (por exemplo, no checkout configurado para não pedir o CPF/CNPJ), a cobrança é gerada sem identificar o pagador, o que o banco aceita no PIX.
Pagamento depois do vencimento: sem prazo configurado, o banco recusa o boleto vencido. Com Dias para pagar após o vencimento preenchido, aceita até o fim do prazo. Veja Formas de Pagamento.
Juros e multa: nesta integração o boleto sai sem juros e multa, e o sistema não deixa salvar a forma de pagamento do boleto com Juros ao mês (%) ou Multa (%) preenchidos.
Certificado: quando o e-CNPJ vencer, envie o novo na conexão e repita o envio ao banco, senão o PIX para de funcionar. Certificado já vencido não é aceito na conexão: a tela recusa o arquivo e mostra a data em que ele venceu.

Problemas comuns

“A Application Key (gw-dev-app-key) é obrigatória”: o campo Application Key ficou em branco na conexão.

O PIX de produção é recusado mesmo com o certificado na conexão: o banco ainda não conhece o certificado. Envie os arquivos de Baixar certificados para o Portal BB no portal do banco (Passo 3).

O PIX falha pedindo certificado: a conexão está em Produção sem o certificado digital. Envie o arquivo e a senha na conexão.

O boleto falha pedindo convênio, carteira ou variação: a forma de pagamento do boleto foi salva antes de ser ligada ao Banco do Brasil e ficou sem os números do contrato de cobrança. Abra a forma, preencha os três campos na aba Pagamento Online e salve.

“Cliente não possui autorização para alguns dos Escopos solicitados”: a aplicação no Portal Developers BB não tem a API que a cobrança usa. O PIX precisa da API Pix e o boleto da API Cobranças. Adicione a API que falta à aplicação.

O banco recusa as credenciais: confira se as credenciais são do mesmo ambiente escolhido em Ambiente de Conexão e se a aplicação já foi aprovada para produção.

“Boleto em processamento (registrado há menos de 30 minutos)” ao cancelar: o banco só aceita a baixa do boleto 30 minutos depois do registro. Espere esse tempo e cancele a transação de novo.

O cliente pagou e o pedido continua em aberto: use Sincronizar na transação. Se o banco ainda mostrar o boleto em aberto, a compensação não terminou.

Veja também

Hub de Integrações: conectar, pausar e excluir uma conexão
Integrações de Pagamento: como escolher banco ou gateway
Transações: acompanhar e sincronizar as cobranças