WHMCS - Pix

Gerencianet Integration Module for Official WHMCS - Version 1.0.0

The Gerencianet module for WHMCS allows you to generate charges to be paid via Pix through our API. In addition, it allows you to receive payments with QrCode or using the Copy and Paste code, this through the transparent checkout.

important

This module only includes payments using Pix. For payments via Boleto, see the page WHMCS - Boletos

This is the Official Integration Module provided by Gerencianet for WHMCS. With it, the person responsible for the WHMCS account can receive payments via Pix and, as soon as the charge has a payment confirmation or is canceled, Gerencianet sends an automatic notification to WHMCS.

caution

For correct operation, we recommend that you read this document carefully and do exactly what is described regarding the necessary configurations in our module, including paying attention to the requirements of PHP versions of the server and WHMCS.


1. System requirements

  • PHP version: 7.2
  • WHMCS version: 8.0.x to 8.2.x The complete requirements for WHMCS you can find here.
important

Os requisitos do sistema foram definidos de acordo com os nossos testes. Se seu sistema não se encaixa nos requisitos, não significa que o módulo não vai funcionar em seu WHMCS, mas sim, que não testamos no mesmo ambiente. Portanto, não garantimos o funcionamento deste módulo em ambientes diferentes dos citados acima.


2. Installation of the Gerencianet Module for WHMCS - Pix

  1. Faça o download da última versão do módulo;

  2. Descompacte o arquivo baixado;

  3. Copie o arquivo gerencianetpix.php e a pasta gerencianetpix, para o diretório /modules/gateways da instalação do WHMCS;

  4. Altere as permissões do arquivo copiado utilizando o comando abaixo chmod 777 modules/gateways/gerencianetpix.php

  5. Altere as permissões da pasta copiada utilizando o comando abaixo chmod 777 modules/gateways/gerencianetpix/ -R

  6. Copie o arquivo gerencianetpix.php, disponível no diretório callback, para o diretório modules/gateways/callback. Ele deve estar no caminho: modules/gateways/callback/gerencianetpix.php

  7. Altere as permissões do arquivo copiado utilizando o comando abaixo chmod 777 modules/gateways/callback/gerencianetpix.php

  8. Copie o arquivo gerencianetpix.php, disponível no diretório hooks, para o diretório includes/hooks. Ele deve estar no caminho includes/hooks/gerencianetpix.php

  9. Altere as permissões do arquivo copiado utilizando o comando: chmod 777 includes/hooks/gerencianetpix.php

  10. Crie uma pasta na raiz do seu servidor e insira seu certificado na pasta. Vale lembrar que seu certificado deve estar no formato .pem. Você encontra o passo a passo de conversão na sessão: Converter certificado .p12 para .pem

Ao final da instalação, os arquivos do módulo Gerencianet devem estar na seguinte estrutura no WHMCS:

includes/hooks/
|- gerencianetpix.php
modules/gateways/
|- callback/gerencianetpix.php
|- gerencianetpix/
|- gerencianetpix.php

Converter certificado .p12 para .pem

Todas as requisições devem conter um certificado de segurança que será fornecido pela Gerencianet dentro da sua conta, no formato PFX(.p12). Essa exigência está descrita na integra no manual de segurança do PIX.

Caso ainda não tenha seu certificado, basta seguir o passo a passo do link a seguir para gerar um novo: Clique Aqui

Para converter seu certificado de .p12 para .pem, basta utilizar o conversor de certificados disponibilizado pela Gerencianet no link: Clique aqui

3. Configurações do Módulo Gerencianet para WHMCS

Dentro do painel administrativo do WHMCS, acesse o menu Setup > Payments > Payment Gateways. No campo Active Module, escolha a opção Gerencianet. A tela mostrada abaixo será exibida. Dentro do formulário, você deverá preencher os seguintes campos:

Tela de Configuração

  1. Client_Id Produção: Deve ser preenchido com o client_id de produção de sua conta Gerencianet. Este campo é obrigatório e pode ser encontrado no menu "API" -> "Minhas Aplicações". Em seguida, selecione sua aplicação criada, conforme é mostrado no link;

  2. Client_Secret Produção: Deve ser preenchido com o client_secret de produção de sua conta Gerencianet. Este campo é obrigatório e pode ser encontrado no menu "API" -> "Minhas Aplicações". Em seguida, selecione sua aplicação criada, conforme é mostrado no link;

  3. Client_Id Desenvolvimento: Deve ser preenchido com o client_id de desenvolvimento de sua conta Gerencianet. Este campo é obrigatório e pode ser encontrado no menu "API" -> "Minhas Aplicações". Em seguida, selecione sua aplicação criada, conforme é mostrado no link;

  4. Client_Secret Desenvolvimento: Deve ser preenchido com o client_secret de desenvolvimento de sua conta Gerencianet. Este campo é obrigatório e pode ser encontrado no menu "API" -> "Minhas Aplicações". Em seguida, selecione sua aplicação criada, conforme é mostrado no link;

  5. Sandbox: Caso seja de seu interesse, habilite o ambiente de testes da API Gerencianet;

  6. Debug: Neste campo é possível habilitar os logs de transação e de erros da Gerencianet no painel WHMCS;

  7. Certificado Pix Deve ser preenchido com o caminho do certificado salvo em seu servidor no passo 10 da instalação;

  8. Desconto: Informe o valor de desconto que deverá ser aplicado ao pix gerado exclusivamente pela Gerencianet;

  9. Validade da Cobrança Deve ser informado o período de validade em dias da cobrança PIX;

  10. Mtls Entenda os riscos de não configurar o mTLS acessando o link https://gnetbr.com/rke4baDVyd.

Chave Pix

Caso a sua chave Pix esteja cadastrada como número de telefone, não se esqueça de seguir o padrão definido pelo BACEN informando +55 DDD e o número, exemplo: +5531988887777

caution

Importante salientar que as cobranças geradas em sandbox não são válidas e não podem ser pagas.

É importante saber que as palavras Sandbox, Ambiente de Homologação e Ambiente de Desenvolvimento, no contexto da Gerencianet, são sinônimos no sentido de fazerem referência ao local de testes que oferecemos em que você pode testar à vontade sua integração com a API.


4. Erros Comuns de Integração

Antes mesmo do módulo tentar gerar uma cobrança alguns campos requisitados na integração passam por uma validação. Os erros que esta validação podem retornar são:

  • Nome Inválido: O nome informado pelo cliente final é muito curto, assim, deve ser informado o nome completo;

  • E-mail Inválido: O email informado pelo cliente final é inválido (não segue o padrão xxxxx@xxxx.com) ou não existe;

  • Telefone Inválido: O telefone informado pelo cliente final não existe ou o DDD está incorreto;

  • Documento Inválido: O número do CPF/CNPJ do cliente final é invalido;

  • Documento Nulo: O campo referente ao CPF e/ou CNPJ do cliente não existe no WHMCS ou não está preenchido;

  • Razão Social Inválida: A Razão Social é inválida. O cliente deve digitar no campo "Empresa" do WHMCS o nome empresarial que consta na Receita Federal;

  • Razão Social Nula: O campo "Empresa" do WHMCS não está preenchido;

  • Erro Inesperado: Houve algum erro na integração. Provavelmente você não preencheu todos os campos do módulo corretamente, ou a versão do PHP do WHMCS não é compatível com a API Gerencianet. Você deverá ativar o modo Debug do módulo para saber mais detalhes.

Ainda que nenhum destes erros de validação sejam retornados, a API Gerencianet poderá retornar erros referentes à geração da cobrança. Para interpretar os retornos da API e, claro, corrigir possíveis erros de validação de dados ou outros similares, acesse a página "Interpretando Erros da API".


5. Suporte e Sugestões

Sua sugestão de novas ideias e implementações para o módulo da Gerencianet para WHMCS é muito importante. Portanto, caso você tenha alguma ideia, entre em contato com a nossa equipe. Iremos analisar sua sugestão e avaliar a possibilidade de implantação.

Caso você tenha alguma dúvida, entre em contato conosco pelo site Gerencianet.