Instalação e Configuração do Módulo Boleto Santander para WHMCS

Guia de configuração completo do Módulo Boleto Registrado Santander para WHMCS, aqui você encontra todos os passos necessários para ter o seu sistema de cobrança via Boleto Registrado Santander, integrando diretamente com a conta bancária da sua empresa.

Os passos a seguir abrangem todas condições, características técnicas e instruções para utilização da solução:

  1. Contratação do serviço cobrança Registrada XML no Santander

  2. Cadastro do certificado de segurança do site no Santander

  3. Configuração do certificado de segurança no servidor do WHMCS
  4. Instalação do módulo no WHMCS

  5. Configuração do módulo no WHMCS

  6. Tela de configurações do módulo no WHMCS

  7. Testes e Homologação no Santander

  8. Gerar Boletos em produção no WHMCS

1) Contratação do serviço de emissão XML no Santander

Módulo Boleto Registrado Santander para WHMCS troca informações da carteira de cobrança Registrada da conta da empresa no Santander, através de protocolo em XML. Para utilizar esse módulo no WHMCS é necessário ter conta Pessoa Jurídica no Banco Santander e contratar o serviço Cobrança Registrada Online XML, na contratação informe ao banco que sua empresa já possui integração (o módulo).

2) Cadastro do certificado de segurança no Santander

Após a contratação da carteira de cobrança para a conta da sua empresa no Santander, o banco irá solicitar que você envie o Certificado digital que deve ser de 2048 bits tipo “certificado client”, sendo ele obrigatório para o envio das informações em Produção e/ou Teste (o certificado de segurança do seu site [SSL] no formato .CER) para que o mesmo seja cadastrado no sistema do banco, esse certificado servirá para autenticar a troca de informações com o banco e garantir a troca segura de informações entre
o Banco e o seu WHMCS.

Recomendamos a contratação de um certificado de segurança com validade de pelo menos 3 anos, para evitar a necessidade de cadastrar um novo certificado no banco toda vez que o SSL do seu WHMCS for renovado.

Certificadoras Recomendadas pelo Santander para a aquisição do Certificado:

  • Nome das Certificadoras Recomendadas
  • AC Camerfirma S.A. SECOM Trust Systems CO.,LTD.
  • AddTrust AB Sonera
  • America Online Inc. Starfield Technologies, Inc.
  • Baltimore SwissSign AG
  • Certplus TC TrustCenter GmbH
  • Comodo CA Limited Thawte
  • Deutsche Telekom AG Thawte Consulting cc
  • DigiCert Inc Thawte Consulting cc
  • Entrust, Inc. thawte, Inc.
  • Entrust.net The Go Daddy Group, Inc.
  • Equifax Secure Inc. The USERTRUST Network
  • GeoTrust Inc. T-Systems Enterprise Services GmbH
  • GlobalSign Unizeto Technologies S.A.
  • GTE Corporation ValiCert, Inc.
  • KEYNECTIS VeriSign, Inc.
  • QuoVadis Limited

Importante: não é aceito certificado assinado pela própria empresa.

Com o certificado de segurança instalado no servidor do WHMCS e funcionando, a exportação do arquivo .CER que será enviado ao banco é muito simples:

Utilizando o Google Chome, com o certificado instalado no servidor, abra o site no Chrome, clique em alguma área da página > Inspecionar > Security > View certificate, ao abrir a visualização do certificado sobre a página, basta segura-lo e arrasta-lo para uma pasta do computador ou área de trabalho. Este gif animado mostra como fazer:
  • Acesse algum URL do WHMCS com o certificado instalado utilizando o Google Chrome;
  • Clique em alguma área da página com o botão direito do mouse, selecione > Inspecionar > Security > View certificate;
  • Ao abrir a visualização do certificado sobre a página, basta segura-lo e arrasta-lo para uma pasta do computador ou área de trabalho
  • Veja um exemplo nessa captura de tela animada:
  • Compacte o arquivo .CER exportado em um arquivo .ZIP envie ao banco.

Logo após o cadastramento do certificado no sistema de segurança do banco já será possível gerar os primeiros boletos em ambiente de testes para a homologação.

3) Configuração do certificado de segurança no servidor do WHMCS

Antes de iniciar a configuração do módulo é necessário configurar o certificado local do servidor do WHMCS, em resumo, para autenticar-se no sistema de segurança do banco será necessário apontar nas configurações do módulo um arquivo salvo no servidor do WHMCS composto pela chave privada (.KEY) + chave pública (.CRT), encriptadas por uma Passphrase em um arquivo .PEM.

O certificado PEM, para funcionar, precisa ter toda a cadeia de certificado mais a chave privada. Você pode verificar isso editando o arquivo PEM. Ele deve conter o seguinte:

  •  3 pares de chaves BEGIN CERTIFICATE / END CERTIFICATE: uma para cada certificadora do certificado;
  • A chave PRIVATE KEY.

Geralmente quando se cria o PEM a partir do .CRT e .KEY ele não é criado com toda a cadeia e pode não funcionar no acionamento do endpoint do serviço de cobrança.

O processo é criar primeiro um arquivo .PFX. Depois importa-lo e exportá-lo novamente marcando para exportar com toda a cadeia de caracteres e aí sim, converter oPFX para PEM.

Para os passo a seguir é necessário ter OpenSSL instalado no servidor e acesso shell para executar o OpenSSL via linha de comando/terminal. Se você não entender os passos a seguir consulte um programador.

  1. gere o certificado PFX a partir do arquivo .CRT e .KEY executando o comando a seguir:
    openssl pkcs12 -export -out domain.name.pfx -inkey domain.name.key -in domain.name.crt
  2.  Converta o PFX para PEM com o comando abaixo:
    openssl pkcs12 -in domain.name.pfx -out domain.name.pem
  3. Adicione uma Passphrase ao arquivo .PEM. A Passphrase é uma senha, deve conter apenas letras e números, grave-a em lugar seguro pois ela será necessária nas configurações do módulo (passo 5). Para adicionar uma Passphrase a um certificado existente, contando que ele não esteja protegido por uma passphrase, execute o comando:
    openssl rsa -aes256 -in domain.name.pem -out domain.name.encrypted.pem mv domain.name.encrypted.pem domain.name.pem

 Armazene a Passphrase e o caminho do arquivo gerado para a configuração do módulo no passo 5.

4) Instalação do módulo no WHMCS

  1. Baixe a versão mais recente do módulo na sua área do cliente;
  2. Descompacte o arquivo .zip e transfira o arquivogofasboletosantander.php e a pasta /gofasboletosantander/ para a pasta /modules/gateways/ da instalação do WHMCS.
  3. Logado como admin, no painel administrativo do WHMCS, navegue até Opções > Pagamentos > Portais para Pagamento;
  4. Na aba "All Payment Gateways" localize o módulo (CTRL + F) "Gofas - Boleto Santander" e clique para ativar. Logo após a ativação do módulo você será direcionado para a sua tela de configurações do módulo, localizada na página Opções > Pagamentos > Portais para Pagamento > aba "Manage Existing Gateways".

5) Configuração do módulo no WHMCS

A seguir você pode conferir a lista completa de todas as configurações do módulo, sua finalidade e como configurar cada opção.

Configurações Referentes ao Banco e Beneficiário

  1. Chave de Licença: Campo para inserir a chave de licença fornecida no memento da aquisição do módulo;
  2. Beneficiário(Opcional) Campo para inserir o nome da empresa da forma que está cadastrada no banco, esse será o nome do beneficiário impresso no Boleto. Deixe em branco para utilizar o nome da empresa definido nas configurações gerais do WHMCS;
  3. Endereço(Obrigatório) Endereço completo da empresa da forma que está cadastrada no banco. Exemplo: Nome da Rua/Avenida, 909, Complemento (se houver) - Nome do Bairro;
  4. CEP(Obrigatório) CEP da empresa da forma que está cadastrada no bancoExemplo: 11680-000;
  5. UF(Obrigatório) Código de duas letras que representa o estado do beneficiário. Exemplo: SP;
  6. Cidade(Obrigatório) Cidade do Beneficiário. Exemplo: Ubatuba;
  7. Documento: (Obrigatório) CNPJ do Beneficiário. Exemplo: 12.345.678/0001-09.
  8. Agência(Obrigatório) Número da Agência onde a empresa possui conta, geralmente 4 dígitos (Somente Números).
  9. Dígito da Agência(Opcional) Dígito da Agência, se exigido pelo banco, se não, deixe em branco (Somente Números).
  10. Conta(Obrigatório) Número da conta bancária do Beneficiário, (Somente Números).
  11. Dígito da Conta(Opcional) Dígito da Conta  bancária do Beneficiário (Somente Números).
  12. Carteira(Obrigatório) Código da carteira de cobrança, padrão é 102, possíveis valores são 101, 102, 157, 158, 175;
  13. Convênio(Obrigatório) Código de convênio fornecido pelo banco, geralmente 7 números. Deixe em branco caso não informado pelo Banco;
  14. Estação(Obrigatório) Referente ao endpoint do webservice do banco. Padrão é 1SBB. Não altere o valor padrão caso não informado pelo Banco;
  15. Variação da Carteira(Opcional) Variação da Carteira, com hífen. Padrão é -019. Não altere o valor padrão caso não informado pelo Banco;
  16. IOS(Opcional) IOS fornecido pelo Banco. Deixe em branco caso não informado pelo Banco;
  17. Aceite(Obrigatório) Padrão é N. Use S para "SIM" ou N para "NÃO". Não altere o valor padrão caso não informado pelo Banco;
  18. Espécie do Documento(Obrigatório) O valor padrão é RC. Possíveis valores DM, DS, NP, NR, RC, AP, CH, ND, OUT. Não altere o valor padrão caso não informado pelo Banco;
  19. Nº de dias após o vencimento para baixa(Obrigatório) Quantidade de dias após o vencimento para baixa/devolução do título. Consulte na agência o padrão do perfil do convênio do beneficiário e configure com o valor exato de dias informado por sua agência bancária.
  20. Certificado SSL: (Obrigatório) Insira o caminho completo para o certificado digital do seu WHMCS, o mesmo certificado .pem criado no passo 3 (Configuração do certificado de segurança no servidor do WHMCS). Ex.: /var/www/html/cert/domain.name.pem. As permissões do arquivo devem ser CHMOD 644;
  21. Passphrase(Obrigatório) Insira a senha do certificado .pem, definida no passo 3 (Configuração do certificado de segurança no servidor do WHMCS).

Configurações Referentes ao Módulo

  1. Modo Diagnóstico / Debug:  (Opcional) Cuidado! Marque essa opção para exibir na Fatura os dados "crus" gerados pelo módulo e pela API interna do WHMCS. Essa funcionalidade foi criada para coletar informações necessárias sempre que necessário diagnosticar erros, nunca use essa opção em produção.
  2. Modo Testes / Sandbox(Opcional) Use essa opção para utilizar o webservice do Santander em modo de testes, é necessário gerar boletos em modo de testes para enviar ao banco para concluir a homologação do seu sistema;
  3. Administrador do WHMCS:  (Obrigatório) Insira o nome de usuário ou ID do administrador com permissão de uso da API interna do WHMCS;
  4. Valor da tarifa por Boleto(Opcional) Insira o valor da comissão paga ao Banco a cada Boleto com pagamento confirmado. Essa informação servirá para calcular e preencher o campo "Taxas" (fee) da lista de transações do WHMCS. Use ponto(.) para separar casas decimais, ex.: 1.5;
  5. Valor mínimo do Boleto(Opcional) Insira o valor mínimo da fatura para permitir pagamento via Boleto, 5 equivale à R$5,00 e 5.50 equivale à R$ 5,50. O valor mínimo padrão é R$5,00;
  6. Dias adicionais para nova data de vencimento(Opcional) Número de dias que serão somados a data do vencimento do Boleto ao gerar segunda via ou ao gerar o boleto de uma fatura que já venceu. Essa opção aplica-se apenas a Faturas vencidas, faturas que ainda não venceram sempre irão gerar Boletos com a mesma data de vencimento da Fatura. Exemplo: se o valor desse campo é 3, o cliente acessa no dia 10/01/2018 uma fatura que já venceu, a data de vencimento do boleto gerado será dia 13/01/2018.
  7. Enviar email em caso de erro(Opcional) Adicione o ID do departamento de suporte que será notificado em caso de erro nas transações. Deixe em branco para desativar;
  8. Diretório do painel do WHMCS(Opcional) Insira o nome personalizado do diretório do painel administrativo do WHMCS, caso ele tenha sido renomeado no arquivo configuration.php. Mais informações;

Campos Personalizados dos Clientes

Antes de configurar as opções a seguir, certifique-se de ter criado e configurado corretamente os Campos Personalizados de Clientes que se aplicam às regras de negócio da sua empresa. Observações importantes:

  • Apenas o campo CPF é obrigatório;
  • A Ordem de Exibição dos Campos Personalizados de Clientes é diferente do ID dos Campos Personalizados, nunca adicione o ID dos campos personalizados, sempre use o número da Ordem;
  • Veja onde encontrar a "Ordem de Exibição" dos Campos Personalizados de Clientes;
  • A Ordem de Exibição dos Campos sempre deve iniciar com 0 (zero).

Com os devidos campos personalizados criados, vamos às configurações do módulo:

  1. Ordem de Exibição do campo CPF/CNPJ(Obrigatório) Insira a Ordem de Exibição do Campo Personalizado de Clientes criado para coletar o CPF do cliente. Esse mesmo campo pode ser utilizado também para coletar o CNPJ do cliente, o módulo vai detectar automaticamente se o seu WHMCS possui apenas um Campo Personalizado de Cliente para CPF e CNPJ;
  2. Ordem de Exibição do campo CNPJ(Opcional) Insira a Ordem de Exibição do Campo Personalizado de Clientes criado para coletar apenas o CNPJ do cliente. Deixe em branco se o seu WHMCS possui apenas um campo para CPF e CNPJ. O valor dessa opção nunca pode ser igual ao da opção anterior;

Exibição da Fatura e do Boleto

  1. Logotipo do Boleto(Opcional) Insira o URL da imagem que será usada como Logotipo da Empresa no cabeçalho boleto. Deixe em branco para utilizar como logotipo o arquivo logo.png utilizado nas faturas em pdf, localizado no diretório /assets/img/logo.png do seu WHMCS;
  2. Imagem do Botão(Opcional) Insira o URL da imagem que será usada como botão "Visualizar Boleto" (tamanho recomendado: 160x43px);
  3. Observações(Opcional) Mensagem direcionada exclusivamente ao cliente, exibida antes do demonstrativo do Boleto. Máximo 125 caracteres;
  4. Exibir linha Digitável do Boleto(Opcional) Exibe a linha digitável do Boleto na Fatura, logo abaixo do botão "Visualizar Boleto". A linha digitável é a representação numérica do código de barras, que pode ser utilizado para realizar o pagamento via internet banking;
  5. Redirecionar para o Boleto(Opcional) Redireciona o cliente diretamente para o URL do boleto ao acessar a fatura. Ideal para oferecer link direto para o Boleto em conjunto com o módulo Auto Login para WHMCS;

Instruções do Boleto

O texto nas linhas de instrução do Boleto devem ser direcionadas exclusivamente ao Caixa do Banco, nunca use as linhas de instruções para mensagens direcionadas ao cliente. Para exibir no Boleto mensagens direcionadas ao cliente, use o campo "Observações" citado anteriormente;

Insira de 1 a 5 linhas de instruções, respeitando as regras do seu Banco/Agência e as regras de previstas na legislação regulamentadora referente a multas e juros.

6) Tela de configurações do módulo no WHMCS

Clique para ampliar:

7) Testes e Homologação no Santander

Após concluir os passos descritos anteriormente, crie uma conta de cliente de testes no WHMCS, crie 5 faturas com o módulo Gofas Boleto Santander definido como portal de pagamento, depois acesse cada uma das faturas logado com o cliente para gerar os respectivos boletos. Após gerar os boletos, salve-os em formato PDF e envie-os ao banco para homologação.

Após a aprovação do banco e liberação do webservice para uso em produção, acesse as configurações do módulo no WHMCS, desmarque a opção Modo Testes / Sandbox e clique em salvar.

8) Gerar Boletos em produção

Com o sistema homologado, apto a emitir Boletos registrados e com a opção Modo Testes / Sandbox desativada, gere um novo boleto de testes, dessa vez em modo produção, pague-o pelo Internet Banking, aplicativo móvel do banco ou em qualquer banco e casa lotérica, no dia seguinte o valor recebido estará disponível na conta bancária da sua empresa. 🎉

Esses são os passos essenciais para iniciar a criação de boletos registrados diretamente com o banco Santander através do Módulo Boleto Registrado Santander para WHMCS. Caso você tenha alguma dúvida ou dificuldade em qualquer ponto da configuração do módulo, abra um ticket de suporte na área do cliente enviando o debug completo gerado ao acessar uma fatura, quando a opção "Debug" está ativada nas configurações do módulo. Se você tiver sugestões de melhorias nas instruções contidas nesse guia deixe seu comentário a seguir.

Deixe seu Comentário

Você precisa fazer login para comentar.

This site uses Akismet to reduce spam. Learn how your comment data is processed.