Page tree
Skip to end of metadata
Go to start of metadata


Índice


Visão geral

O MK erp possui integração com a API do PIX BB (Banco do Brasil), o que viabiliza a realização de pagamentos (QRcode e pix copia e cola) pelo SAC WEB e app do SAC Plus+. Nesta modalidade os valores Pix pagos pelos clientes são depositados diretamente na conta corrente do provedor no BB.

Com esta integração será possível: 

  • Disponibilizar QRcode para pagamentos dos clientes
  • Disponibilizar a linha do QRcode para pagamentos dos clientes
  • Receber pagamentos dos clientes automaticamente
  • Acompanhar as transações (geração do QRCode, pagamentos efetivados e rejeitados)

Pré Requisitos

Configurações


PROFILE BB

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 Homologação

Para realizar testes da integração antes de disponibilizar os pagamentos para todos os clientes é possível configurar chaves de homologaçã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:

  • Nome da aplicação: descrição identificativa (texto livre);
  • Descrição: descrição identificativa (texto livre);


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. Acesse a área Consultar Credenciais para copiar os dados:

 Configuração da profile de pagamento em ambiente de homologação

ACESSO: Configurações → Menu Financeiro → Submenu Profile de Pagamento → Boleto MK Ver. 2 - Edição, localize a profile do Banco do Brasil e então vai estar disponível a área PIX para inserir a configuração.

PIX BB

A área PIX fica disponível somente em profiles do Banco do Brasil

Nesta tela temos os seguintes campos:

  • Chave PIX: Chave da conta do Banco do Brasil adquirida no site do BB. Enquanto estiver fazendo testes em homologação utilize uma das chaves abaixo:
    1. 7f6844d0-de89-47e5-9ef7-e0a35a681615
    2. 3d94a38b-f344-460e-b6c9-489469b2fb03
    3. d14d32de-b3b9-4c31-9f89-8df2cec92c50
  • Credenciais: Seleção da credencial utilizada na conta/profile de pagamento;
  • Status: da profile, selecione a opção:
    • Homologação - Esta definição deve ser feita para que o provedor faça seus testes internos (com a chave pix e credenciais de homologação);
  • Hab. testes: Sim/Não;
  • Cliente Homologação: Cadastro que será utilizado para os testes enquanto estiver com o status de Homologação, então somente este cadastro vai poder fazer os pagamentos pelo SAC;
  • Testar comunicação: Teste de comunicação com o BB para confirmar se a chave e credenciais estão corretas;
  • Cadastrar credenciais PIX: ao clicar neste botão será aberta nova janela onde deve ser inserida a configuração.

  • Empresa: Em caso de multiempresa podem ser cadastradas credenciais específicas;
  • Developer Application Key: Chave adquirida no site do BB;
  • Client ID: Chave adquirida no site do BB;
  • Cliente Secret: Chave adquirida no site do BB;

Requisitos para o cliente/cadastro utilizado para os testes de pagamento

O Banco do Brasil tem um banco de dados com vários documentos disponíveis para testes. Então pode ser utilizado um cadastro com CPF ou CNPJ válidos. Mas, caso um destes documentos não esteja cadastrado na base do BB o QRcode não será gerado e na ferramenta Transações via Pix vai ficar registrado o retorno de erro: documento inválido.

Abaixo segue listagem de CPFs utilizados com a finalidade de desenvolvimento justamente para que possam realizar testes de pagamento:

  • 96050176876
  • 66779051870
  • 22902869150
  • 97965940132
  • 75069056123

 Testes de pagamento

Após inserir as chaves de homologação devem ser realizados alguns testes para verificar a configuração feita e a comunicação entre o mk erp e a API do BB.

 Testar comunicação

Para confirmar que as chaves de homologação estão corretas utilize a ferramenta Testar comunicação:

Este teste verifica se as chaves informadas na credencial estão corretas, se são do status selecionado (homologação) e se a comunicação com a API do BB está ok.

 Ativar ferramentas PIX no SAC WEB

Para gerar o teste de pagamento do cliente selecionado na profile em homologação o PIX deve ser ativo no SAC WEB. Veja na documentação: Habilitar/Desabilitar pagamentos por PIX no SAC WEB

 Testar a linha de pagamento gerada pelo QRcode

Para que o BB faça a análise da linha de pagamento o QRcode para uma fatura do cliente em homologação deve ser gerado no SAC e então a linha pode ser copiada. Veja na documentação: Efetuar pagamentos pelo SAC WEB

Faça a cópia do código e então acesse a área de testes: Sandbox BB

Acesse o menu API's > Simula pagamento de boleto e Pix :

Clique para expandir a ferramenta pix e após clique sobre POST para visualizar a tela abaixo.



Copie o código gw-app-key para o campo string:

Clique então sobre a opção Try it out e cole o código do QRcode (copiado do SAC do mk) e cole entre as aspas conforme destacado no Request body > após clique em Execute:

Aguarde o retorno e então a área responses vai ser atualizada. O exemplo abaixo é de um teste OK, observe o retorno "Pagamento efetuado com sucesso" no Response body:


Após este teste em cinco minutos o pagamento será enviado para o mk. A análise pode ser feita no Painel de acompanhamento das transações via PIX.


Cadastro PIX BB em Produção

Após realizar os testes de pagamento as chaves podem ser alteradas para as de produção. O suporte do BB disponibiliza o manual abaixo com o passo e o seu gerente de contas também pode auxiliar:

No canal do YouTube do BB também está disponível um vídeo que explica o processo: Como criar uma aplicação e conseguir suas credenciais - Portal Developers BB | BB.

 Configuração da profile de pagamento em ambiente de produção

Após a configuração da conta em produção os dados na profile de pagamento BB v2 deve ser atualizados.

ACESSO: Configurações → Menu Financeiro → Submenu Profile de Pagamento → Boleto MK Ver. 2 - Edição, localize a profile do Banco do Brasil e então vai estar disponível a área PIX para inserir a configuração:

Importante

O cadastro dos dados de homologação e de produção é de responsabilidade exclusiva do provedor

Altere os seguintes campos:

  • Chave PIX: Em ambiente de Produção, o cliente deve criar sua própria chave através de seu Internet Banking. É essa chave que vai ser informada no MK (recomendamos que utilize a opção de gerar chave aleatória);
  • Credenciais: Seleção da credencial utilizada na conta/profile de pagamento. Clique em Cadastrar credenciais PIX para alterar os dados para as novas chaves de produção;
  • Status: agora selecione a opção:
    • Produção - Para quando a integração estiver em produção de fato (com a chave pix e credenciais de produção);
  • Hab. testes: Não;
  • Cliente Homologação: Retire o cadastro do cliente;
  • Testar comunicação: Teste de comunicação com o BB para confirmar se a chave e credenciais estão corretas;
  • Cadastrar credenciais PIX: ao clicar neste botão será aberta nova janela onde deve ser inserida a configuração com as novas chaves de produção;

Habilitar/Desabilitar pagamentos por PIX no SAC WEB e app novo SAC+

ACESSO: Configurações → SAC → Configuração SAC→ Pagamento PIX:

ACESSO: Configurações → SAC → Configuração SAC→ MOBILE NOVO SAC PLUS → Checkout Pix = Sim

IMPORTANTE

Caso já esteja utilizando o novo app do SAC+ e mesmo assim nesta tela não esteja visível a opção Checkout Pix entre em contato com o nosso suporte para que seja inserido.

Efetuar pagamentos pelo SAC WEB

Ao acessar o SAC WEB o cliente vai visualizar um novo botão "Pagar com PIX" no menu Pagamentos.

Importante

Os pagamentos pelo PIX ficarão disponíveis no SAC somente para faturas geradas na profile BB V2 configurada com a chave PIX

Nesta área temos as seguintes informações:

  • Fatura que será paga: código da fatura selecionada;

  • Descrição: descrição da fatura selecionada;

  • Vencimento: data de vencimento da fatura selecionada;

  • Valor (R$): valor original da fatura selecionada;

  • Desconto (R$): valor de desconto da fatura (gerado pela tabela de descontos associada ao contrato);

  • Multa (R$): valor de multa caso a fatura vencida (gerado pela % definida na configuração do sistema);

  • Acréscimo (R$): valor de acréscimo caso a fatura vencida (gerado pela % definida na configuração do sistema);

  • Dias de atraso: total de dias em atraso da fatura vencida;

  • Valor reajustado: valor atual (caso a fatura tenha desconto ou acréscimo e multa).


VALIDADE DO QRCODE

O QRCODE tem comportamentos diferentes para o prazo de validade de acordo com o status da fatura:

  1. Fatura pendente: o QRCODE é válido até às 23:59h do dia do vencimento da fatura;
  2. Fatura vencida: o QRCODE é até às 23:59h do dia atual.

Efetuar pagamentos pelo app novo SAC+

A mesma configuração que ativa o pagamento pelo SAC WEB também habilita para os clientes no app novo SAC+. Basta acessar a ferramenta de pagamentos e clicar em PAGAR FATURA:

Selecione a forma de pagamento pelo Pix e clique para efetuar o pagamento:



Ficam disponíveis duas opções:

  • COPIAR CÓDIGO PIX - faz a copia da chave para que o cliente possa utilizar no app que desejar para fazer o pagamento;
  • COMPARTILHAR CÓDIGO PIX - abre a bandeja de opções do smartphone para que a chave possa ser compartilhada pelo app que o cliente desejar (Whats, Telegram, etc);


Gerar/enviar pix copia e cola pelo painel do cliente

Além do SAC WEB e app novo SAC+ a partir da release 108.52 é possível gerar o QRcode e obter ou enviar por e-mail a linha de pagamento do pix copia e cola pelo painel do cliente.

Atenção

Assim como no SAC a geração do QRcode só vai ficar disponível para faturas que tenham sido geradas com a profile de pagamento configurada com as chaves de homologação ou produção.

ACESSO: módulo Financeiro → Painel do cliente → duplo clique sobre o cliente → Faturas a receber

Selecione a fatura e clique na ferramenta Pix no canto inferior da tela. Caso a fatura ainda não tenha chave gerada uma mensagem vai informar:

Basta confirmar que então o QRcode será gerado. Nesta tela então serão habilitadas duas opções:

Copiar código Pix

O código Pix será copiado para a área de transferência do operador, para que seja enviado como desejar.

Enviar código Pix por email

Será enviado para o cliente um email com o código Pix para que seja efetuado o pagamento. O email vai seguir o seguinte padrão:

  • será enviado pela conta default da empresa/multiempresa;
  • será considerado o(s) email(s) definido(s) no cadastro do cliente;
  • o corpo do email é padrão e contém as informações do nome do cliente, número da fatura, data de vencimento da fatura, código pix e data de expiração (validade) do código de pagamento (às 23:59h do dia de vencimento da fatura):

Painel de acompanhamento das transações via PIX

ACESSO: módulo Financeiro → Transações via PIX

Para o acompanhamento das transações via PIX temos os seguintes painéis: 

Transações com sucesso dos últimos 7 dias

Transações com erro (últimos 30 dias)

Todas as transações executadas com sucesso

Todas as transações que geraram erro

Transações com sucesso dos últimos 7 dias

Neste painel o operador poderá visualizar as transações em que foi gerado o QRCODE no SAC WEB ou app SAC+ e também os pagamentos realizados nos últimos 7 dias.

TRANSAÇÕES GERADAS

Transações geradas: esse status indica que o QRCODE foi gerado pelo cliente no SAC WEB ou app SAC+. Então o relatório mostra tanto faturas que somente tiverem o QRcode gerado quanto pagamentos já realizados, a coluna Status informa qual é a operação.

Para cada transação teremos as seguintes informações: 

  • Código: identificação da transação 
  • Fatura: código identificativo da fatura 
  • Gerado em: data em que o QRCODE foi gerado
  • Status: status da operação ATIVA ou CONCLUIDA. ATIVA significa que o QRcode foi gerado pelo cliente no SAC WEB/Apps, CONCLUÍDA significa que o pagamento foi reaalizado.
  • Cliente: nome do cliente da operação
  • Doc. Cliente: documento do cliente da operação
  • Valor da fatura: valor da fatura do cliente (já atualizado em caso de acréscimo por atraso)
  • Pago em: data de pagamento (pois o QRcode pode ser gerado em um dia no SAC e pago em outro)
  • Pagador: informação sobre o pagante, pois a fatura pode ser liquidada pelo PIX de pessoa diferente do titular
  • Doc Pagador: documento do pagante
    • Profile: profile de pagamento da fatura

    • Operador: onde o QRcode foi gerado (SAC WEB/App)

    • Id transação: identificação específica da transação enviada para o BB

    • Válido até: data de validade do QRcode (período em que o cliente pode fazer o pagamento utilizando o mesmo código/chave, após ele deve gerar novo no SAC WEB/App)

    • Produção: informa se a transação foi feita em produção ou homologação

DICA

Fique atento às colunas disponibilizadas para o painel, algumas podem estar por padrão ocultas. Saiba mais em Visualização de Dados na Grade/Tela


Transações com erro (últimos 30 dias)

Neste painel o operador poderá visualizar as transações que obtiveram erro nos últimos 30 dias, ou seja, os pagamentos via PIX que não foram efetivados. 

Para cada transação com erro teremos as seguintes informações: 

  • Código: identificação da transação 

  • Fatura: código identificativo da fatura

  • Data da transação: data da tentativa de pagamento ou geração do QRcode

  • Operação: pagamento ou geração do QRcode

  • Descrição: detalhes sobre a rejeição

  • Cliente: nome do cliente

  • Doc. Cliente: documento do cliente

  • R$ transação: valor

    • Profile: profile de pagamento da fatura

    • Operador: onde o QRcode foi gerado (SAC WEB/App)

    • Status code: detalhamento do código da rejeição enviado pelo BB
    • Status erro: detalhamento do status da rejeição enviado pelo BB

Todas as transações executadas com sucesso

Neste painel o operador poderá visualizar todas as transações em que foi gerado o QRCODE no SAC WEB ou app SAC+ e também os pagamentos realizados.

Todas as transações que geraram erro

Neste painel o operador poderá visualizar todas as transações que obtiveram erro, ou seja, os pagamentos via PIX que não foram efetivados. 

Analisando códigos de erros

As rejeições são enviadas pelo BB com códigos de erros que facilitam a identificação. Todas estão listadas no manual abaixo:


Execução da rotina de pagamentos via PIX

O sistema faz a checagem automática dos pagamentos realizados. Essa análise é executada em uma rotina periódica. 

Informação importante

A execução da rotina de checagem de pagamentos é feita automaticamente de 5 em 5 minutos.

Então se um cliente realizar o pagamento agora em 5 minutos a transação estará disponível para análise no sistema e, se for efetivada com sucesso, a fatura é imediatamente liquidada. Para a execução correta da rotina é necessário que o servidor tenha comunicação com os webservices do Banco do Brasil. Se por algum motivo a rotina não for executada pode ser feita uma busca por data para análise imediata das transações:


  • Data: basta preencher o período de data que deseja consultar as transações.

Conciliando pagamentos feitos via Pix

ACESSO: Financeiro → Gerenciador de fluxo de caixas → Liquidações via Pix

Neste painel o operador poderá visualizar as transações realizadas com sucesso nos últimos 30 dias (pagamentos via PIX que foram efetivados). Neste menu podem ser utilizadas as seguintes ferramentas:

Alterar intervalo de datas da exibição

Gerar conciliação dos registros selecionados

  • Alterar intervalo de datas da exibição: por padrão esta tela mostra as transações dos últimos 30 dias, clicando nesta opção é possível escolher se deseja ampliar o filtro ou utilizar um período de data personalizado;

  • Gerar conciliação dos registros selecionados: ferramenta para conciliar o valor pago pelo cliente na conta bancária de destino. São abertas as seguintes opções: 
    • Conta para recebimento: em qual conta será creditado o valor;
    • Data recebimento: qual a data do recebimento;
    • Valor recebimento: valor recebido e que será creditado na conta. 

Após finalizar esta conciliação o valor da fatura será visualizado em Movimentações de Contas Bancárias.


Visualizar as transações no painel do cliente

ACESSO: Financeiro → Painel do cliente → Faturas a receber → Duplo clique sobre a fatura:

Analisar o histórico das faturas

  • Sucesso ao gerar cobrança PIX - essa operação indica que o QRCode foi gerado no SACWEB ou APP SAC+:

  • Sucesso ao atualizar cobrança PIX - essa operação indica que um QRCode foi gerado anteriormente e expirou (não foi pago dentro do prazo) e o cliente fez a geração de um novo código:

  • Liquidação - essa operação mostra os detalhes do pagamento efetivado:

  • No labels