Configuração da Integração com o Banco do Brasil (Pix)

Este artigo mostra o passo a passo completo para habilitar o recebimento via Pix integrado ao Banco do Brasil, cobrindo o cadastro da aplicação no Portal Developers BB, a geração de credenciais, a configuração da conta bancária no Movisis e o envio do certificado digital necessário para autenticação mTLS.

Visão geral

A integração Pix com o Banco do Brasil é feita em duas frentes que precisam conversar entre si:

• Portal Developers BB — onde a aplicação é criada, as credenciais (Client ID, Client Secret e App Key) são geradas e o certificado digital é homologado.
• Movisis — onde a conta bancária é cadastrada com essas credenciais e o certificado é vinculado à loja.

O fluxo completo tem cinco etapas, que devem ser seguidas nesta ordem:

⏱️ Tempo estimado: 20 a 30 minutos, sem contar o tempo de aprovação do certificado (até 5 minutos) e a assinatura do termo de adesão para produção (depende do representante legal da empresa).

Pré-requisitos

Antes de começar, tenha em mãos:

• [ ] Acesso de administrador ao Portal Developers BB: https://acesso.bb.com.br/v2/login?appId=ipa-developers
• [ ] Certificado digital e-CNPJ modelo A1 da empresa, no formato .pfx ou .p12, com a senha em mãos
• [ ] O CNPJ do certificado deve ser exatamente o mesmo CNPJ da loja que será configurada no Movisis
• [ ] Chave Pix já cadastrada no Banco do Brasil como chave do recebedor
• [ ] Acesso ao Movisis com permissão em Parâmetros Financeiros e Parâmetros do Sistema

⚠️ Importante: essa integração é exclusiva para pessoa jurídica e exige credencial de autenticação mútua (certificado A1). Não é possível concluir o processo sem um certificado A1 válido.

Etapa 1 — Cadastrar a aplicação no Portal Developers BB

1. Acesse o site de cadastro: https://acesso.bb.com.br/v2/login?appId=ipa-developers
2. Clique no botão Criar nova aplicação e informe o nome e a descrição da aplicação.

3. Em Selecione as APIs desejadas, escolha o grupo APIs com contratação online pelo Portal Developers BB e marque a opção Pix (v2).

4. Clique em Criar para concluir o cadastro da aplicação.
5. Volte para a lista de aplicações e selecione a aplicação recém-criada.

6. Na tela de detalhes da aplicação, clique no card Credenciais.

Etapa 2 — Gerar as credenciais de acesso

O Portal Developers BB exige que as credenciais de ambiente de teste sejam geradas antes de liberar as credenciais de produção. Siga esta ordem:

1. Na aba Ambiente de teste, clique em Gerar credenciais.

2. O portal exibirá as credenciais geradas. Copie e guarde cada uma delas em um local seguro (todas elas são exibidas somente uma vez)

💡 Dica: use o botão Baixar todas as credenciais (TXT) para salvar uma cópia de backup antes de sair da tela.

⚠️ Se você perder o acesso às credenciais, será necessário gerar novas e substituir as antigas — a aplicação fica indisponível até a substituição.

Etapa 3 — Cadastrar a conta bancária no Movisis

3.1 Adicionar a conta bancária

1. No Movisis, acesse Parâmetros Financeiros → Contas Bancárias.
2. Clique em Adicionar e preencha o formulário Nova Conta com os dados obtidos na Etapa 2:

3. Clique em Salvar.

3.2 Vincular a conta à loja no Pix

1. Acesse Parâmetros Financeiros → Pix → Lojas.
2. Selecione a loja desejada e, no campo Escolha a conta para pagamento com Pix, selecione a conta criada no passo anterior.

3. Clique em Salvar.

Etapa 4 — Certificado digital (mTLS)

Esta é a etapa mais sensível do processo: o certificado precisa ser enviado primeiro na Movisis e depois homologado no Portal Developers BB.

4.1 Enviar o certificado A1 no Movisis

1. Acesse Parâmetros do Sistema → [selecione a loja] → Certificado Digital.
2. Clique em Enviar certificado.

3. Envie o arquivo do certificado (.pfx ou .p12 exportado com a chave privada) e informe a senha do certificado.

⚠️ Atenção: o certificado precisa ser o e-CNPJ da própria loja — o CNPJ do titular do certificado é conferido contra o cadastro da empresa vinculada à loja. Se os CNPJs não coincidirem, o envio será recusado.

4. Aguarde a confirmação de que o certificado foi cadastrado com sucesso. A tela passará a exibir os dados do certificado ativo (titular, CNPJ, emissor, validade) e a seção Cadeia para o Portal do Banco do Brasil.

5. Clique em Baixar cadeia completa para baixar o arquivo com a cadeia de certificados (certificado da empresa + autoridades intermediárias).

📅 O certificado enviado tem prazo de validade (normalmente cerca de 4 meses, conforme o emissor). Anote a data de vencimento exibida na tela e programe a renovação com antecedência para evitar interrupção nos recebimentos via Pix.

4.2 Enviar o certificado no Portal Developers BB

1. No Portal Developers BB, volte aos detalhes da aplicação e clique no card Certificados.
2. Em Como utilizar meus certificados nas APIs e Webhook do BB?, na seção Para consumir APIs, clique em Enviar certificado.

3. Clique em Importar cadeia completa e selecione o arquivo baixado no Movisis (passo 4.1.5). Depois, clique em Enviar.

4.3 Acompanhar o status do envio

1. No card Histórico de envios, acompanhe a situação do certificado enviado.
2. A atualização do status pode levar até 5 minutos. Clique em Atualizar para verificar.

✅ Assim que a situação exibir o check verde, a integração já está totalmente configurada no ambiente de testes (DEV) e pode ser enviada para produção.

Etapa 5 — Enviar a aplicação para produção

1. Na tela de detalhes da aplicação, clique em Enviar para produção.

2. Identificação da empresa — informe o CNPJ, clique em Pesquisar e confirme se a razão social está correta.

⚠️ Depois de confirmar, não será possível alterar o CNPJ. Caso necessário, será preciso criar uma nova aplicação.

3. Contato da aplicação — informe e-mail e telefone de contato.
4. Revisão da aplicação — confira o CNPJ, a razão social, as APIs vinculadas e os dados de contato antes de confirmar.

5. Contratação — clique em Concluir. A aplicação ficará com o status Aguardando aprovação até que o representante legal da empresa assine o termo de adesão, pelo Portal Developers BB ou pelo aplicativo BB Digital PJ.

ℹ️ Após a assinatura do termo de adesão, a aplicação é enviada automaticamente para produção — não é necessária nenhuma ação adicional no Portal Developers BB.

Checklist rápido

• [ ] Aplicação criada no Portal Developers BB com a API Pix (v2) contratada
• [ ] Credenciais de teste geradas e salvas (App Key, Client ID, Client Secret)
• [ ] Conta bancária cadastrada no Movisis em Parâmetros Financeiros → Contas Bancárias
• [ ] Conta vinculada à loja em Parâmetros Financeiros → Pix → Lojas
• [ ] Certificado A1 enviado no Movisis (mesmo CNPJ da loja)
• [ ] Cadeia completa baixada no Movisis e importada no Portal Developers BB
• [ ] Status do certificado aprovado (✅) no Histórico de envios
• [ ] Aplicação enviada para produção e termo de adesão assinado

Perguntas frequentes

O que é a “chave Pix” solicitada no cadastro da conta no Movisis?
É a chave Pix cadastrada no Banco do Brasil como chave do recebedor da loja (pode ser CNPJ, e-mail, telefone ou chave aleatória, conforme o que foi registrado no banco).

Posso usar um certificado A1 de outro CNPJ, diferente do CNPJ da loja?
Não. O certificado precisa pertencer ao mesmo CNPJ da loja configurada nos parâmetros — o Portal Developers BB valida essa correspondência.

O status do certificado não atualizou depois de 5 minutos. O que fazer?
Clique em Atualizar no card Histórico de envios. Se o status continuar pendente por muito mais tempo que o esperado, verifique se o arquivo importado foi realmente a cadeia completa baixada no Movisis, e não apenas o certificado da empresa isolado.

Quanto tempo leva para a aplicação ir para produção?
Depende exclusivamente da assinatura do termo de adesão pelo representante legal da empresa, no Portal Developers BB ou no BB Digital PJ. Após a assinatura, a liberação é automática.

O que acontece quando o certificado digital vence?
A integração para de autenticar (mTLS) até que um novo certificado seja enviado. Repita a Etapa 4 com o certificado renovado antes da data de vencimento exibida no Movisis.

💬 Dúvidas ou dificuldades? Entre em contato com o suporte Movisis através da nossa central de atendimento:
suporte.movisis.com.br