| Painel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Índice
|
O MK erp possui integração com a API do Pix Banco do Brasil V2. Nesta modalidade os valores Pix pagos pelos clientes são depositados diretamente na conta corrente do provedor. O processo de uso da API Pix V2 do BB exige que o provedor gere certificados específicos que devem ser utilizado no internet banking e no mk erp. Nesta documentação vamos passar sugestões para que faça a geração destes certificados e como ativar a configuração da profile de pagamento.
Pré Requisitos
- Sistema na versão 109.64.5 ou superior
- Profile V2 homologada do BB
- Certificado digital .PFX
- Cadeia completa do certificado (pois será necessário utilizar as certificações)
- Extração da chave privada .PEM do certificado
- Extração da chave pública .PEM do certificado
Os certificados autorizados pelo BB para a autenticação mútua são do tipo A1, em formato .pem, com a cadeia inteira (Certificado > Intermediarias > Raiz), emitidos por uma CA válida.
Extraindo as chaves do certificado digital
| Dica |
|---|
| Não é obrigatório seguir este modelo para exportação das chaves, caso tenha conhecimento de outras formas de geração, pode ignorar as etapas abaixo. Documentação de auxílio do Banco do Brasil: Autenticação Mútua de Certificados (MTLS) |
- Acesse o disco local C em seu computador e crie uma pasta chamada OpenSSL, dentro desta pasta crie uma nova chamada SSL. O diretório deve ser exatamente este: C:\OpenSSL\SSL
- Faça o download do OpenSSL clicando neste link, a versão é a 1.1 Portable. Extraia da pasta compactada e salve no seu computador no diretório de sua preferência. No exemplo abaixo foi salvo dentro da pasta Documentos:
Na mesma pasta onde salvou o OpenSSL (a pasta vai ficar com o nome OpenSSL-1.1.1h_win32) coloque o seu certificado digital (caso o nome do certificado tenha espaçamentos na descrição é recomendado que renomeie ele e retire os espaços):
Abra o terminal openssl como administrador:
Extraindo a chave pública
Execute no terminal:
| Informações |
|---|
| pkcs12 -in "CertificadoDoProvedor.pfx" -nokeys -out "ChavePublica.pem" |
Onde:
- CertificadoDoProvedor.pfx - substitua pelo nome e extensão do seu certificado digital
- ChavePublica.pem - substitua pelo nome que deseja utilizar para a chave pública
Após rodar o comando o terminal vai solicitar a senha do certificado:
Basta informar e então se estiver correta a chave publica vai ser criada dentro da mesma pasta OpenSSL-1.1.1h_win32.
Extraindo a chave privada
Execute no terminal:
| Informações |
|---|
| pkcs12 -in "CertificadoDoProvedor.pfx" -nocerts -out "ChavePrivada.pem" -nodes |
Onde:
- CertificadoDoProvedor.pfx - substitua pelo nome e extensão do seu certificado digital
- ChavePrivada.pem - substitua pelo nome que deseja utilizar para a chave privada
Após rodar o comando o terminal vai solicitar a senha do certificado:
Basta informar e então se estiver correta a chave pública vai ser criada dentro da mesma pasta OpenSSL-1.1.1h_win32:
Abra o arquivo (pode utilizar o Bloco de Notas, Notepad++ ou qualquer programa que leia arquivos .txt) e remova o cabeçalho: linhas 1,2 e 3, conforme exemplos abaixo:
Salve desta forma:
| Dica |
|---|
Ao visualizar os certificados instalados na guia Caminho de Certificação é possível identificar facilmente o nome de cada arquivo necessário como no exemplo abaixo:
|
...
| Painel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Índice
|
O MK erp possui integração com a API do Pix Banco do Brasil V2. Nesta modalidade os valores Pix pagos pelos clientes são depositados diretamente na conta corrente do provedor. O processo de uso da API Pix V2 do BB exige que o provedor gere certificados específicos que devem ser utilizado no internet banking e no mk erp. Nesta documentação vamos passar sugestões para que faça a geração destes certificados e como ativar a configuração da profile de pagamento.
| Informações |
|---|
| Contratações da API PIX do BB realizadas a partir de Junho/2023 pertencem a modalidade V2. Caso tenha criado a aplicação antes desta data então a sua API é do modelo V1, veja o passo a passo de como configura-la no ERP em PIX: Banco do Brasil API V1. |
Pré Requisitos
- Sistema na versão 109.64.5 ou superior
- Profile V2 homologada do BB
- Certificado digital .PFX
- Cadeia completa do certificado (pois será necessário utilizar as certificações)
- Extração da chave privada .PEM do certificado
- Extração da chave pública .PEM do certificado
Os certificados autorizados pelo BB para a autenticação mútua são do tipo A1, em formato .pem, com a cadeia inteira (Certificado > Intermediarias > Raiz), emitidos por uma CA válida.
Extraindo as chaves do certificado digital
| Dica |
|---|
| Não é obrigatório seguir este modelo para exportação das chaves, caso tenha conhecimento de outras formas de geração, pode ignorar as etapas abaixo. Documentação de auxílio do Banco do Brasil: Autenticação Mútua de Certificados (MTLS) |
- Acesse o disco local C em seu computador e crie uma pasta chamada OpenSSL, dentro desta pasta crie uma nova chamada SSL. O diretório deve ser exatamente este: C:\OpenSSL\SSL
- Faça o download do OpenSSL clicando neste link, a versão é a 1.1 Portable. Extraia da pasta compactada e salve no seu computador no diretório de sua preferência. No exemplo abaixo foi salvo dentro da pasta Documentos:
Na mesma pasta onde salvou o OpenSSL (a pasta vai ficar com o nome OpenSSL-1.1.1h_win32) coloque o seu certificado digital (caso o nome do certificado tenha espaçamentos na descrição é recomendado que renomeie ele e retire os espaços):
Abra o terminal openssl como administrador:
Extraindo a chave pública
Execute no terminal:
| Informações |
|---|
| pkcs12 -in "CertificadoDoProvedor.pfx" -nokeys -out "ChavePublica.pem" |
Onde:
- CertificadoDoProvedor.pfx - substitua pelo nome e extensão do seu certificado digital
- ChavePublica.pem - substitua pelo nome que deseja utilizar para a chave pública
Após rodar o comando o terminal vai solicitar a senha do certificado:
Basta informar e então se estiver correta a chave publica vai ser criada dentro da mesma pasta OpenSSL-1.1.1h_win32.
Extraindo a chave privada
Execute no terminal:
| Informações |
|---|
| pkcs12 -in "CertificadoDoProvedor.pfx" -nocerts -out "ChavePrivada.pem" -nodes |
Onde:
- CertificadoDoProvedor.pfx - substitua pelo nome e extensão do seu certificado digital
- ChavePrivada.pem - substitua pelo nome que deseja utilizar para a chave privada
Após rodar o comando o terminal vai solicitar a senha do certificado:
Basta informar e então se estiver correta a chave pública vai ser criada dentro da mesma pasta OpenSSL-1.1.1h_win32:
Abra o arquivo (pode utilizar o Bloco de Notas, Notepad++ ou qualquer programa que leia arquivos .txt) e remova o cabeçalho: linhas 1,2 e 3, conforme exemplos abaixo:
Salve desta forma:
| Dica |
|---|
|
No exemplo abaixo vamos iniciar pela raiz do certificado:
- selecione e clique na opção Exibir Certificado
- acesse então a aba Detalhes > Copiar para Arquivo...
No assistente para copiar o arquivo selecione a opção X.509 codificado na base 64 (*.cer)
Avance e salve o arquivo. Repita o processo com os certificados intermediários.
| Dica |
|---|
Salve os arquivos no seu computador com descrições que encontre facilmente pois eles serão utilizados no portal do BB! |
Montando o conteúdo para o portal do BB
Abra os arquivos certificados raiz e intermediários com um leitor de .txt (como Bloco de Notas, ou Notepad++). Você deve visualizá-los dessa forma:
| Dica |
|---|
Caso o conteúdo esteja criptografado é porque não foi copiado no formato X.509 codificado na base 64 (*.cer), neste caso faça novamente conforme orientações acima! |
O certificado raiz está pronto para ser utilizado. Já os certificados intermediários precisam ser unificados em um único arquivo. O processo é bem simples, basta copiar e colar o conteúdo no programa leitor de txt (um abaixo do outro) e salvar o registro. Exemplo:
Configurações do Pix BB
| Informações | ||
|---|---|---|
| ||
Atenção! Caso não tenha nenhuma profile do Banco do Brasil no layout v2 homologada em seu sistema entre em contato com a equipe de suporte a homologação bancária para iniciar o processo. |
Cadastro PIX BB em Produção
Deve ser utilizada uma conta (profile BB v2) já cadastrada no sistema, só é necessário solicitar o Client ID, Client Secret e Developer Api Key da conta. A solicitação é feita pelo Portal Developers BB . Ao acessar o portal faça a criação da conta de testes preenchendo as seguintes informações:
...
Selecione a opção APIs com contratação online pelo Portal Developers BB e após marque a opção PIX:
Para avançar clique em CRIAR.
No menu Produção preencha os dados e confirme a API escolhida:
...
marque a opção PIX:
Para avançar clique em CRIAR.
No menu Produção preencha os dados e confirme a API escolhida:
Ao finalizar clique em SOLICITAR PRODUÇÃO, aceite os termos do contrato (ou solicite ao representante da empresa). No canal do YouTube do BB também está disponível um vídeo que explica o processo: Como colocar uma aplicação em produção.
Credenciais de produção
No menu lateral acesse a opção Credenciais para copiar as informações conforme exemplo abaixo:
Veja que na imagem estão selecionadas as credencias de Teste, no seu caso deve estar selecionada a opção Produção. No ERP vão ser utilizados:
- client_id
- client_secret
- developer_application_key
Upload dos certificados
No menu lateral acesse a Certificados e informe o CNPJ do provedor:
...
- Certificado da empresa - conteúdo da chave pública (extraída do certificado digital));
- Certificado do intermediário - conteúdos copiados dos certificados intermediários;
- Certificado Raiz do intermediário certificado - conteúdo copiado da raiz do certificado;Raiz do certificado - conteúdos copiados do certificado intermediário. Nesta área o BB vai verificar o conteúdo dos 2 certificados, então copie e cole todo o conteúdo de um deles e após do outro (a ordem aqui não interfere no resultado)
Abaixo exemplo do portal do BB das informações preenchidas:
Após clicar em SALVAR o portal do BB vai verificar se os dados estão corretos. Caso exista alguma inconsistência uma mensagem vai informar qual dos certificados deve ser ajustado.
...
| Informações | ||
|---|---|---|
| ||
O cadastro dos dados de homologação e de produção é de responsabilidade exclusiva do provedor! |
Preencha os seguintes campos:
- Chave PIX: chave da conta do Banco do Brasil adquirida no site do BB (pode ser o CNPJ, um e-mail, telefone, chave aleatória...).
- Credenciais: seleção da credencial utilizada na conta/profile de pagamento. Clique em Cadastrar credenciais PIX para inserir os dados de produção;
- Status: selecione a opção:
- Produção
- Hab. testes:
- Sim: pode utilizar esta opção para realizar um teste de pagamento, dessa forma a geração do QRcode vai ser permitida somente para um cadastro selecionado como Cliente Homologação;
- Não: liberado para todos os clientes;
- Cliente Homologação: selecione o cadastro do cliente que deseja utilizar para o teste de pagamento;
- Testar comunicação: teste de comunicação com o Sicoob para confirmar se a chave e credenciais estão corretas (clique para executar somente após inserir os dados conforme instruções abaixo);
- Versão API: selecione a opção 'Versão 2'
- Cadastrar credenciais PIX: ao clicar neste botão será aberta nova janela onde deve ser inserida a configuração com as chaves de produção;
- client_id - chave adquirida no site do BB;
- client_secret - chave adquirida no site do BB;
- developer_application_key -chave adquirida no site do BB;
- path_cert_client - chave pública .PEM extraída do certificado digital do provedor;
- path_key_client - chave privada .PEM extraída do certificado digital do provedor
Testar comunicação
Para confirmar que as credenciais estão corretas utilize a ferramenta Testar comunicação:
Este teste verifica se as chaves informadas na credencial estão certas e se os certificados tiveram o upload feito corretamente!
| Informações | ||
|---|---|---|
| ||
Pronto! A sua profile está em produção! Veja as configurações, ferramentas e recursos que pode utilizar: Pagamentos via PIX |
...