Banco do Brasil - Pix Cobrança

Introdução

A integração entre o Sistema e o Banco do Brasil (BB) para o Pix Cobrança foi desenvolvida para oferecer uma solução robusta, escalável e segura para o recebimento de faturas com liquidação imediata.

O Pix Cobrança BB permite a geração dinâmica de QR Codes (EMV) atrelados a títulos financeiros. Diferente de uma transferência Pix estática, o Pix Cobrança possui controle de vencimento, juros, multas e conciliação automática via Webhook. Além disso, a integração suporta a modalidade de Pix Automático, que permite cobranças recorrentes totalmente automatizadas, funcionando como um "débito automático" moderno, sem as fricções burocráticas dos layouts de remessa/retorno convencionais — especialmente adequado ao mercado de assinaturas e provedores de internet.

Benefícios

• Liquidação Imediata: O saldo é disponibilizado na conta corrente da empresa em segundos após o pagamento.
• Conciliação Automatizada: Baixa automática de faturas no IXC através de comunicação via Webhooks.
• Segurança Criptográfica: Uso de autenticação mTLS (Mutual TLS) obrigatória, garantindo proteção ponta a ponta.
• Redução de Inadimplência: Facilidade de pagamento pelo cliente final via leitura de QR Code ou "Pix Copia e Cola", com suporte adicional a cobranças recorrentes automáticas via Pix Automático.
• Garantia de Receita: Redução drástica da inadimplência não intencional (esquecimento de boletos) através do Pix Automático.
• Fidelização e Conveniência: O cliente autoriza a recorrência apenas uma vez e as parcelas subsequentes são debitadas automaticamente.
• Gestão de Retentativas: Sistema inteligente de reapresentação de cobranças em caso de saldo insuficiente.

Acesso ao Formulário

Caminho: Sistema > Cadastros > Financeiro > Carteira de cobrança.

Visão Geral da Integração

O funcionamento macro da integração baseia-se na API oficial do Banco do Brasil (Padrão BACEN v2.0+). Quando uma fatura é gerada no IXC Provedor, o sistema consome os endpoints do BB para registrar a cobrança (gerando um txid único) e obter o "Pix Copia e Cola" (payload location).

Conceitos Importantes:

• TxID: Identificador único da transação gerado pelo Sistema (padrão alfanumérico) que vincula a cobrança no BB com o título no IXC.
• App Key (Developer Application Key): Chave exclusiva exigida pelo Banco do Brasil em todas as requisições, enviada no header gw-dev-app-key.

Para o Pix Automático, a arquitetura estende-se para o gerenciamento de Autorizações (Mandatos) e Cobranças Agendadas, seguindo o fluxo macro abaixo:

1. O recebedor (provedor) apresenta um QR Code ou Link (Payload) com informações de recorrência.
2. O pagador realiza a leitura no app do seu banco e, além de pagar a primeira parcela, aceita os termos do Pix Automático.
3. O BB gera um Token de Autorização (ID de Recorrência) e notifica o IXC.
4. O IXC armazena esse Token no contrato do cliente.
5. Nos meses seguintes, a Tarefa de Solicitação de Novas Ordens de Cobrança Pix solicita antecipadamente ao Banco do Brasil (ex: D-10) que agende o débito para a data do vencimento utilizando aquele Token.

Pré-requisitos

Para iniciar a configuração do Pix Cobrança Banco do Brasil no IXC, os seguintes requisitos devem ser rigorosamente cumpridos:

• Conta Corrente BB: Conta Pessoa Jurídica ativa no Banco do Brasil.
• Chave Pix Cadastrada: Uma chave Pix (preferencialmente CNPJ ou Aleatória) vinculada à conta corrente.
• Cadastro no Portal de Desenvolvedores BB: Acesso administrativo ao portal developers.bb.com.br para criação da aplicação.

Para a modalidade de Pix Automático, são exigidos adicionalmente:

• Contrato Específico com o BB: É necessário firmar o convênio/contrato comercial para a modalidade de recebimento Pix Automático junto ao gerente da conta no Banco do Brasil.
• Escopos Adicionais na API: A aplicação no portal Developers BB deve ter os escopos relacionados ao Pix Automático.
• Rotina de Ativação no IXC: A Tarefa de Ativação de recorrência Pix para contratos com ID de recorrência vinculado deve estar ativada no agendador de tarefas do sistema.

Processo de Integração e Homologação

Para realizar a integração e homologação da API Pix Cobrança do Banco do Brasil no sistema, siga os passos abaixo:

Homologação

Dados bancários necessários para a integração:

001 - Banco do Brasil (API)

• 1 - Número da agência com dígito?
• 2 - Número da conta com dígito?
• 3 - Número do Convênio / Beneficiário ou Cedente?
• 4 - Pix chave?
• 5 - Pix Client ID?
• 6 - Pix Client secret?
• 7 - Developer Aplication Key?
• 8 - Este convênio bancário é totalmente novo ou já foi usado para emissão?

Coleta de dados concluída!

Agora que você reuniu todas as informações necessárias, entre em contato com o suporte da IXC Soft. Nossa equipe dará continuidade ao processo para finalizar a homologação da sua carteira de cobrança.

Dica!

Caso tenha dúvida sobre algum dos dados bancários, consulte o(a) Gerente de sua Conta Bancária.

Passo a passo para obter as Credenciais da API Pix Cobrança

Informação!

Para a homologação da carteira de API Pix Cobrança do Banco do Brasil, você também precisa gerar o Client-ID e o Client secret, que são as credenciais da aplicação da API no site Developers do Banco do Brasil:

1. Acesse o Developers Banco do Brasil.
2. Faça login com sua conta. Você estará no ambiente Aplicações.
3. Clique em CRIAR NOVA APLICAÇÃO.
4. Insira um nome e uma descrição para a sua aplicação e prossiga.
5. No tópico chamado Selecione as APIs desejadas, marque os escopos de funcionalidade da API.
6. Neste caso, selecione os escopos:
   • COBRANÇAS
   • PIX
7. No final da página, clique no botão Criar. Você será redirecionado ao menu de Aplicações.
8. A aplicação criada estará com o status Em teste. Clique sobre a aplicação que acabou de criar para acessar seus detalhes.
9. Confirme se os dados e escopos de API da aplicação foram selecionados corretamente, e então clique no botão ENVIAR PARA PRODUÇÃO.
10. Siga os passos pedidos e insira suas informações para seguir com a contratação das chaves em produção.
11. Após concluir a contratação dentro do aplicativo criado, clique em Credenciais e localize as seguintes chaves:
    • App Key - No sistema: Developer application key.
    • Client ID - Client ID.
    • Client Secret - Client secret.
12. Copie estas chaves ou as obtenha via arquivo, clicando no botão BAIXAR TODAS AS CREDENCIAIS [TXT]. Estas são as credenciais a serem utilizadas na homologação de sua carteira de cobrança.
13. Fim.

Coleta de dados concluída!

Agora que você reuniu todas as informações necessárias, entre em contato com o suporte da IXC Soft. Nossa equipe dará continuidade ao processo para finalizar a homologação da sua carteira de cobrança.

Configuração no IXC Provedor

Criando a Carteira

Com as credenciais em mãos, configure a Carteira de Cobrança no Sistema.

1. Acesse o menu Sistema > Cadastros > Financeiro > Carteira de Cobrança.
2. Clique em Novo.
3. Na aba principal, defina:
   • Descrição: Defina o nome da carteira.
   • Conta: Crie a conta responsável por guardar as informações bancárias.
   • Tipo de recebimento: Escolha a opção Pix.
   • Enviar e-mail para cliente ao gerar: Selecione Não, pois exige e-mail cadastrado no cliente e envia a fatura automaticamente para registro no banco (por isso, não é recomendado utilizar).
   • Validar filial na venda: Marque como Sim.
   • Planejamento analítico: Utilize 240, ou cadastre um novo código.

Criando a conta

• Conta: Dê um nome à conta.
• Tipo da Conta: Escolha a opção Banco.
• Data de abertura: Indique a data do dia da configuração da conta.
• Planejamento analítico: Para mais informações, acesse: Contas Contábeis Analíticas.
• Filial: Escolha o ID da filial para à qual a Conta e a Carteira serão vinculadas.

Na aba seguinte, Banco:

• Banco: Selecione o ID da instituição bancária, conforme o cadastro nacional. Para o Banco do Brasil, utilize:
  • 001 - Banco do Brasil S.A.
• Agência: Preencha o número da sua agência.
• Dígito verificador da agência: Informe o dígito após o número da agência.
• Número da conta: Informe o número da conta bancária.
• Dígito verificador da conta: Informe o dígito verificador da conta.
• Caso alguma informação for “x”, preencha com letra maiúscula X.

Configurações Pix

1. Navegue para a aba Configurações Pix:
   • Pix Gateway: Selecione Banco do Brasil.
   • Pix Ambiente: Produção.
   • Pix chave: Insira a chave cadastrada no BB (exatamente como cadastrada no banco).
   • Developer App Key (BB): Insira a chave gerada no portal do desenvolvedor.
   • Pix Client ID: Cole o Client ID.
   • Pix Client Secret: Cole o Client Secret.
2. Pix URL callback: Após salvar a carteira, clique no botão Gerar URL Pix. O IXC fará uma requisição para o BB, registrando a rota de callback (webhook).
3. Enviar cobrança Pix pelo WhatsApp: Ativa a funcionalidade de envio do Template Cobrança Pix, exclusivo da integração com o Opa! Suite. Habilitando este parâmetro, um novo campo ficará visível e obrigatório:
   • Tipo da chave Pix: Selecione na lista a opção que corresponde ao Tipo da chave PIX do gateway que será utilizada (CPF/CNPJ, E-mail, Telefone ou Chave Aleatória).
   • Chave Pix: Insira a chave Pix principal que está configurada e é utilizada pela sua conta na instituição financeira correspondente a esta carteira de cobrança.

Para mais detalhes da funcionalidade e configuração, verifique em Enviar Template Cobrança Pix via WhatsApp com o Opa! Suite.

4. Utilizar Pix recorrente: Com essa configuração, sempre que o cliente final efetuar um pagamento via Pix, será exibida em seu aplicativo bancário a opção de ativar a recorrência (opcional), permitindo que as próximas cobranças sejam realizadas automaticamente nos vencimentos seguintes.
   • Sim: ao marcar como Sim, ao finalizar o pagamento via Pix, o cliente receberá uma solicitação para ativar a recorrência, permitindo a cobrança automática nos próximos vencimentos.
   • Não: ao manter marcado como Não, a funcionalidade do Pix automático (recorrente) não estará disponível ao cliente final.
5. Ativando o parâmetro acima, também ficará visível o parâmetro Repetir tentativa de cobrança para Pix recorrente, marque-o conforme necessário:
   • Sim: ao marcar como Sim, a cobrança recorrente poderá realizar uma nova tentativa de débito, caso aconteça algum erro na primeira tentativa.
   • Não: ao marcar como Não, a cobrança Pix tentará debitar somente uma vez.
6. Após configuração destes parâmetros, a carteira já está pronta para seguir emitindo as cobranças Pix com a inclusão da recorrência.
7. Fim.

Link Gateway na Cobrança

O Sistema captura automaticamente a URL do boleto fornecida pela API do Banco do Brasil e grava sua informação no campo Link gateway no Contas a Receber, aumentando a eficiência no atendimento e alinhando com as funcionalidades de outras integrações.

• Caminho: Receber > Contas a Receber > Editar registro
• Funcionalidade: A URL do boleto será capturada e preenchida automaticamente no campo Link gateway.
• Impacto: Facilita o fluxo de trabalho para atendimento ao cliente, permitindo o envio rápido de segundas vias de boletos por e-mail ou WhatsApp.

Juros/Multas/Desconto

• Juros %: Valor padrão permitido por lei: 0.033% (acima deste, pode ser considerado abusivo).
• Multa %: Valor padrão permitido por lei: 2%.
• Desconto até o vencimento R$: Informe o valor do desconto em Reais caso o pagamento ocorra até o vencimento.
• Desconto até o vencimento %: Informe o desconto em Porcentagem para pagamento até o vencimento.

Para mais informações, acesse: Juros, Multas e Desconto.

Instruções

Informação:

• A API do Banco do Brasil permite até 165 caracteres ao todo.
• Não há limite de linhas, mas cada linha deve ter até 55 caracteres.
• Atenção: não são permitidos caracteres de escape (\r ou \n).

• Instrução 1:

Após vencimento juros R$ #juro# ao dia.

• Instrução 2:

Após vencimento multa R$ #multa#.

Aviso!

Se adicionar mais linhas de instrução, insira também as variáveis de leitura correspondentes em Imprimir instruções quando...

Para mais informações, acesse: Instruções da Carteira de Cobrança.

Impressão

• Layout de impressão: Utilize um dos modelos disponíveis para a modalidade Pix Cobrança.

Para mais informações, acesse: Layouts de Impressão.

Logs carteira de cobrança

Aba destinada ao armazenamento dos logs de criação e alteração dos Gateways e APIs.

É importante ressaltar que, mesmo que a autenticação falhe, a carteira de cobrança será salva, e o log detalhado será registrado para posterior investigação.

Dica!

Para mais informações sobre a aba Logs carteira de cobrança, consulte em:

• Logs Carteira de Cobrança

Configurando o Webhook

1. Acesse o Developers Banco do Brasil.

2. Clique na sua aplicação para acessar os detalhes.

3. Clique no botão Webhook.

4. Clique na aba Eventos e depois em Cadastrar Evento.

5. Selecione o convênio de cobrança e preencha com os seguintes dados:

   • URL: Cole a URL Webhook gerada na carteira de cobrança do sistema.
   • E-mail: Informe um e-mail para receber informações da API do banco.
   • Tipo de evento: Marque a opção BAIXA OPERACIONAL.

6. Após preencher os dados, clique em Salvar.

7. Clique em URLs.

8. Em URL de Callback, insira a mesma URL que foi informada anteriormente.

9. Finalize clicando no botão Editar.

Fluxo Operacional

O ciclo de vida de uma cobrança Pix no Banco do Brasil através do IXC segue o seguinte modelo:

1. Emissão: Ao gerar o título para o cliente (ex: Fatura Mensal), o IXC cria um txid.
2. Registro (PUT /cob): O ERP envia os dados (valor, devedor, calendário de expiração) para o Banco do Brasil. O BB responde com o Payload Location (URL do QR Code).
3. Exibição: O cliente visualiza o QR Code na Central do Assinante, Fatura impressa ou via link do WhatsApp.
4. Liquidação: O cliente efetua o pagamento. O Banco Central processa a transação para o Banco do Brasil.
5. Notificação (Webhook): O BB realiza um POST na URL do IXC Provedor informando os dados do recebimento (valor, horário, txid, endToEndId).
6. Conciliação Interna: O IXC localiza o título pelo txid, verifica o endToEndId para evitar duplicidade (Idempotência), liquida o título e gera a movimentação de Contas a Receber.

Webhooks e Retornos

A integração prioriza o fluxo assíncrono (Webhooks) para maior performance.

• Segurança do Webhook: O BB valida se o certificado apresentado pelo servidor do IXC Provedor (na URL de callback) é confiável e suporta TLS 1.2+.
• Estrutura de Retorno: O payload do BB envia um array de objetos pix, onde o IXC processa a chave txid e valor.
• Contingência (Rotina de Consulta): Caso o provedor de internet do IXC sofra uma queda e o Webhook do BB falhe, existe a Rotina Consulta Recebimento Cobranças API Pix no IXC. Ela efetua um GET buscando transações por período (Data Inicial / Data Final) para reconciliar pagamentos órfãos.

Segurança, Logs e Monitoramento

• Armazenamento Seguro: As chaves (Secret e App Key) são salvas criptografadas no banco de dados do IXC.
• Logs de Comunicação: Toda comunicação (Request e Response) fica registrada no painel de logs do título no IXC.

Problemas Comuns e Soluções

Problema / Erro	Possível Causa	Solução
Erro 401 - Não Autorizado	App Key incorreta ou Token expirado	Verifique se a Developer Aplication Key copiada do portal BB está correta no IXC.
Webhook não recebe (Faturas não baixam)	URL inacessível pelo Banco do Brasil	Garanta que o IP público do Sistema não possui restrições de Firewall (GeoIP block, Cloudflare com regras estritas) para IPs do Banco do Brasil.
Chave Pix não encontrada	Divergência de cadastro	A chave inserida na carteira deve ser exatamente a mesma associada à conta BB e liberada na API.

Ativando a Carteira de Cobrança no Sistema

Após configurar sua carteira, é necessário vinculá-la de uma das seguintes formas:

• Hotsite (Central do Assinante): Configurando a carteira nos parâmetros gerais do sistema no Hotsite, todos os clientes da base poderão utilizá-la para efetuar pagamentos através da Central do Assinante.
• Alternativa de Pagamento: Vinculando a carteira a uma Alternativa de Pagamento, é possível incluí-la dentro de carteiras de cobrança específicas. Isso permite, por exemplo, restringir o pagamento via Pix a um grupo específico de clientes ou criar diferentes opções de pagamento com carteiras que possuem condições distintas, como descontos até o vencimento.

Configurando a Carteira no Hotsite - Central do Assinante

1. Acesse o menu Sistema.
2. Entre no submenu Hotsite.
3. Vá até a pasta Configurações.
4. Clique em Configuração Geral.
5. Acesse a aba Financeiro.
6. Na seção Pix, configure os seguintes parâmetros:
   • Habilitar Pix: Marque esta opção para ativar o pagamento via Pix na sua Central do Assinante.
   • Carteira de cobrança (Pix): Vincule a carteira Pix criada, tornando-a a carteira Pix padrão do sistema.
7. Clique em Salvar para finalizar.

Configurando a Carteira como Alternativa de Pagamento

1. Cadastre uma Alternativa de Pagamento, conforme as instruções em Configurações Alternativas de Pagamento.
2. No menu Sistema > Cadastros > Financeiro > Carteira de Cobrança, localize a carteira na qual deseja implementar a alternativa.
3. Clique em Editar.
4. No campo Configuração de alternativa de pagamento, insira o ID ou utilize a Lupa para localizar o cadastro da Alternativa criada.
5. Clique em Salvar para concluir a configuração.

Concluído!

Somente clientes cuja carteira padrão do contrato contenha a Alternativa de Pagamento vinculada ao Pix poderão efetuar pagamentos por meio dessa opção.

Pix Automático

O Pix Automático é uma funcionalidade complementar à carteira Pix Cobrança do Banco do Brasil que representa a inovação do Banco Central para facilitar cobranças recorrentes. Diferente do Pix Cobrança avulso, o Pix Automático permite que o IXC debite diretamente a conta do pagador nas datas de vencimento acordadas, mediante uma Autorização Prévia (Mandato) concedida pelo cliente via aplicativo bancário.

Importante!

Detalhes de funcionamento - Pix Automático

• Requer autorização prévia do pagador para que a cobrança recorrente seja debitada automaticamente;
• Funciona para valores fixos ou variáveis, definidos pelo recebedor a cada ciclo de cobrança;
• O agendamento e débito ocorrem conforme as regras estabelecidas pelo Banco Central e pelo PSP do pagador;
• Em caso de saldo insuficiente, podem ocorrer novas tentativas de cobrança, conforme política definida pelo recebedor;
• O cancelamento da autorização impede débitos futuros, mas não afeta pagamentos já agendados;
• Pode ser integrado via QR Code Composto ou solicitações diretas de autorização, seguindo as jornadas definidas no Manual de Padrões do Pix;
• Diferencia-se do Pix tradicional por não exigir a execução manual da transação a cada pagamento.

Passo a Passo: como configurar o Pix Automático - Banco do Brasil

1. Acesse o menu Sistema > Cadastros > Financeiro > Carteira de Cobrança
2. Selecione a carteira de cobrança de Pix Banco do Brasil desejada, e clique em Editar
3. Siga para a aba Configurações Pix
4. Localize o parâmetro Utilizar Pix recorrente e marque-o como Sim:
   • Sim: ao marcar como Sim, ao finalizar o pagamento via Pix, o cliente receberá uma solicitação para ativar a recorrência, permitindo a cobrança automática nos próximos vencimentos.
   • Não: ao manter marcado como Não, a funcionalidade do Pix automático (recorrente) não estará disponível ao cliente final.
5. Ativando o parâmetro acima, também ficará visível o parâmetro Repetir tentativa de cobrança para Pix recorrente, marque-o conforme necessário:
   • Sim: ao marcar como Sim, a cobrança recorrente poderá realizar uma nova tentativa de débito, caso aconteça algum erro na primeira tentativa.
   • Não: ao marcar como Não, a cobrança Pix tentará debitar somente uma vez.
6. Após configuração destes parâmetros, a carteira já está pronta para seguir emitindo as cobranças Pix com a inclusão da recorrência.
7. Fim.

Com essa configuração, sempre que o cliente final efetuar um pagamento via Pix, será exibida em seu aplicativo bancário a opção de ativar a recorrência (opcional), permitindo que as próximas cobranças sejam realizadas automaticamente nos vencimentos seguintes.

Tarefa de Ativação de Recorrência

Após a ativação dos parâmetros de recorrência na carteira de cobrança, é fundamental ser configurada a tarefa de recorrência. Esta tarefa será a responsável por realizar a criação da cobrança a partir da recorrência ativa em contratos no Sistema. Ela será executada diariamente, e aplicará a criação da cobrança para todos as cobranças recorrentes com vencimento de até 10 dias, a partir da data de sua execução.

Abaixo, acompanhe o passo a passo de configuração da tarefa:

Tarefa - Ativação de Recorrência

Configurando:

1. Vá até o menu Ferramentas.

2. Clique em Ferramentas.

3. Acesse Agenda de tarefas.

4. Clique em Novo.

5. Em Tarefa, selecione Ativação de recorrência Pix para contratos com ID de recorrência vinculado.

   • Minuto (0-59):

     • Tipo: Selecione a opção Valor

     • Valor: Insira o número 0

   • Hora (0-23):

     • Tipo: Selecione a opção Valor

     • Valor: Insira o número 1

   • Dia do mes (1-31):

     • Tipo: Selecione a opção Valor

     • Valor: Não preencher

   • Mes (1-12):

     • Tipo: Selecione a opção Valor

     • Valor: Não preencher

   • Dia da semana (0-6) 0=dom, 1=seg...:

     • Tipo: Selecione a opção Valor

     • Valor: Não preencher

6. Finalize clicando no botão Salvar.

Finalizado! Com a configuração acima, a tarefa fica configurada para executar todos os dias às 01:00 da manhã.

Cancelamento de Pix Recorrente

O sistema possui lógica para cancelar automaticamente a recorrência do Pix quando houver alteração da data de vencimento em contratos através da Alteração Wizard ou Assistente de Alteração de Contrato. Este procedimento assegura o cumprimento das regras de funcionamento e registro de cobranças estabelecidas pela integração com o gateway de pagamento.

Regras de Funcionamento

1. Quando o parâmetro do Pix recorrente está ativo, ao realizar um pagamento via Pix o cliente receberá em seu aplicativo bancário uma solicitação opcional para ativar a recorrência.
   • Se o pagador ativar a recorrência, o ID da recorrência será gravado no contrato recorrente ou de origem vinculado ao boleto, no campo Token.
2. A cobrança recorrente só será disponibilizada se o boleto estiver vinculado a um contrato recorrente (financeiro convencional) ou a um contrato de origem (novo conceito financeiro). Boletos de financeiro avulso ou sem contrato vinculado seguirão o fluxo normal de pagamento via Pix Cobrança.
3. No Sistema, é necessário configurar a tarefa de recorrência do Pix, que será responsável por executar as cobranças recorrentes com vencimento de até 10 dias a partir da data de sua execução. Ao executar, as informações da criação da cobrança serão registradas no histórico boleto, incluindo a requisição do sistema e resposta da instituição financeira (request e response).
4. Quando a cobrança recorrente for liquidada, a instituição deve enviar um webhook ao Sistema, realizando o recebimento da cobrança (contas a receber). Se o pagamento não ocorrer, a recorrência deverá ser cancelada, com base no webhook de cancelamento enviado pela Banco do Brasil. Ao cancelar, será desvinculado o ID da recorrência no Contrato, e serão canceladas as cobranças recorrentes, caso existam.

Aviso! No recebimento, cancelará as cobranças vinculadas a outras integrações:

• Pedido de baixa para remessa e retorno
• Requisição de cancelamento para Gateways e APIs
• Requisição de cancelamento para Pix cobrança Banco do Brasil

5. Quando a cobrança recorrente for comunicada (registrada) e o boleto for recebido manualmente ou por integração, cancelado ou renegociado, será enviada uma requisição de cancelamento da recorrência.
6. Quando o contrato possuir uma recorrência ativa, não serão iniciadas novas requisições de recorrência, mesmo que o pagamento seja realizado por Pix cobrança.
7. Quando o contrato estiver vinculado a uma recorrência de cartão de crédito, não será criada uma nova recorrência caso o pagamento seja feito via Pix.
8. Quando um boleto vinculado a uma recorrência Pix for pago com cartão de crédito, não será permitida a ativação da recorrência de cartão de crédito.

Cenários de Uso

Cenário de Sucesso (Fluxo Perfeito):

O cliente contrata plano de 100 Mega. No primeiro pagamento avulso, ele aceita o Pix Automático em seu app (Bradesco, Nubank, Itaú, etc). No mês 2, a tarefa do IXC gera a instrução de débito 10 dias antes. No vencimento, o valor debita da conta do cliente, entra no BB do provedor, o webhook avisa o IXC e a internet do cliente permanece ativa.

Cenário de Exceção (Falta de Limite/Saldo):

Vencimento dia 15. No dia 15, a transação retorna rejeitada. Dia 16 (madrugada), o IXC reagenda para o dia 17. Dia 17 falha novamente. O IXC tenta até o limite de 3 vezes (parametrizado). Após isso, a fatura fica vencida no IXC, e o cliente sofre bloqueio parcial/total de internet conforme a régua de cobrança padrão do sistema, precisando pedir a 2ª via.

Problemas Comuns e Tratativas - Pix Automático

Sintoma	Diagnóstico e Resolução
Tarefas de cobrança não estão sendo criadas	Verifique se a Agenda de Tarefas do IXC está rodando. Valide também se o Token (ID Recorrência) consta na aba de Integrações do Contrato do cliente.
Erro "Consentimento Inválido/Expirado" da API do BB	O cliente revogou a autorização em seu banco. Solução: Limpar o token no Sistema e instruir o cliente a ativar novamente na próxima fatura avulsa.
Cobrança automática liquidada com valor sem juros em atraso	Comportamento esperado. O Pix Automático, assim como o Débito em Conta, não cobra juros sobre as retentativas dentro da janela configurada.

FAQ - Pix Automático

FAQ

Se o pagamento falhar no vencimento, posso cobrar os juros na retentativa?

• R: Não. A especificação do Banco Central para o Pix Automático determina que a cobrança ocorra pelo valor de face da parcela registrada no momento do agendamento prévio. Para cobrar juros, a fatura deverá ser paga de forma avulsa (Pix Cobrança, Boleto).

A tarefa de Ativação do Pix Recorrente pode rodar a qualquer hora?

• R: Recomenda-se rodar nas madrugadas (ex: 01:00h) para evitar concorrência no banco de dados e garantir que os processamentos do Banco do Brasil em D-1 recebam os lotes de solicitações da maneira mais otimizada possível.

Observações Técnicas e de Arquitetura

• Idempotência: A integração do IXC envia identificadores únicos no body da requisição para garantir que, caso ocorra timeout (falha de rede) entre o IXC e o Banco do Brasil, o reenvio da requisição pela rotina não crie duas programações de débito para o mesmo vencimento.
• Conflitos de Meios: Um contrato não pode ter Pix Automático e Recorrência de Cartão de Crédito ativos simultaneamente. O Sistema fará o controle dessa trava de segurança.

Conclusão

A integração do Pix Cobrança Banco do Brasil no IXC Provedor é uma evolução tecnológica que moderniza o fluxo de recebíveis das empresas. O uso de mTLS, Webhooks e a estrutura oficial da API do BB garantem uma operação resiliente, automatizada e sem necessidade de intervenção humana (zero touch) no processo de conciliação.

A camada adicional do Pix Automático revoluciona o contas a receber do provedor, trazendo previsibilidade de caixa extrema. Com a correta parametrização dos Webhooks, APIs (Client ID, Secret, App Key e mTLS) e Agendador de Tarefas do IXC, todo o ciclo de autorização, débito e conciliação atua de maneira autônoma, reduzindo o custo operacional de emissão de boletos a zero.

Leia Também

• Contas a Receber
• API Banco do Brasil
• Carteira de Cobrança
• Integrações Bancárias - Carteira de Cobrança
• Integrações Bancárias - Pix Automático
• Integrações Bancárias - Pix Cobrança
• Integrações Bancárias - Débito Automático
• Integrações Bancárias - Cartão de Crédito
• Pix Automático (Guia)
• Pix (Manual do Pix)
• Pix Automático - Banco Central do Brasil (Artigo)
• FAQ Pix Automático - Banco Central do Brasil