WHMCS - Boletos

Gerencianet Integration Module for Official WHMCS - Version 0.3.1

The Gerencianet's module for WHMCS allows you to generate and create boletos with registration (registered boleto) through our API. In addition, it allows you to receive payments through transparent checkout.

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

Biggest versions than 0.2.7 of the Gerencianet/WHMCS module, the automatic WHMCS callback was made available to Gerencianet in cases of cancellation and due date update. Therefore, whenever an invoice is canceled in WHMCS it is automatically canceled in Gerencianet, and whenever the invoice has a modified due date, the Gerencianet boleto also has its due date updated.

To activate the automatic callback from WHMCS to Gerencianet, follow the 5th step in the 2. Installation of the Gerencianet Module for WHMCS.

Bolix

If you have activated Bolix in your Gerencianet account, the charges generated by our module/plugin will already come with the pix on the ticket. More details about Bolix and how to activate it, click here.

IMPORTANT

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.


Get straight to the point - use the table of contents below and see directly what you need:

  1. System requirements

  2. Installation of the Gerencianet Module for WHMCS

  3. Gerencianet's Module Settings for WHMCS

  4. How to cancell a charge

  5. How to update de due date of a charge

  6. WHMCS discount

  7. Common Integration Errors

  8. Gerencianet module developed by Gofas (Gerencianet's Partnership for WHMCS)

  9. Support and Suggestions


1. System requirements

  • PHP version: 5.4.39 to 7.0.3
  • WHMCS version: 6.0.4 to 7.1.1
IMPORTANT

The system requirements were defined according to our tests. If your system doesn't fit the requirements, it doesn't mean that the module won't work on your WHMCS, but that we don't test it in the same environment. Therefore, we do not guarantee the operation of this module in environments other than those mentioned above.

You can also check out the Gerencianet's module for WHMCS developed by our official partner Gofas in this link, which is compatible with higher versions of WHMCS and PHP.


2. Installation of the Gerencianet Module for WHMCS

  1. Download the module latest version;

  2. Unzip the downloaded file;

  3. Copy the file gerencianetcharge.php and the folder gerencianet_lib, availables in the folder gn-api-whmcs of our module, to the directory modules/gateways of the WHMCS installation;

  4. Copy the file gerencianetcharge.php, available in gn-api-whmcs/callback from our module, to the directory modules/gateways/callback of the WHMCS installation. It must follow the model modules/gateways/callback/gerencianetcharge.php

  5. Copy the file gerencianet.php, available in gn-api-whmcs/hooks from our module and paste in the directory /includes/hooks of the WHMCS installation. It must follow the model includes/hooks/gerencianet.php.

The Gerencianet module files must follow the same structure in WHMCS, as shown below:

includes/hooks/
| gerencianet.php
modules/gateways/
| callback/gerencianetcharge.php
| gerencianet_lib/
| gerencianetcharge.php

3. Gerencianet Module Settings for WHMCS

alt text


Within the WMCS administrative panel, access the menu Setup > Payments > Payment Gateways. No campo Active Module, chose the option Gerencianet. The screen shown above will be displayed. In the form, you must fill the following fields:

1. Client_Id Produção: It must be filled in with the production Client_Id of your Gerencianet account. This field is mandatory and can be found in the menu API > Minhas Aplicações. Then select the created application as shown in this link;

2. Client_Secret Produção: It must be filled in with the production Client_Secret of your Gerencianet account. This field is mandatory and can be found in the menu API > Minhas Aplicações. Then select the created application as shown in this link;

3. Client_Id Desenvolvimento: It must be filled in with the development Client_Id of your Gerencianet account. This field is mandatory and can be found in the menu API > Minhas Aplicações. Then select the created application as shown in this link;

4. Client_Secret Desenvolvimento: It must be filled in with the development Client_Secret of your Gerencianet account. This field is mandatory and can be found in the menu API > Minhas Aplicações. Then select the created application as shown in this link;

5. Identificador da Conta: It must be filled in with the identifier of your Gerencianet account. This field is required. Check where to find it on your platform (Identificador da Conta);

6. Usuário administrador do WHMCS:It must be filled in with the WHMCS administrator user. You must use the same user that the WHMCS administrator uses to log into the administrative area of your account. This field is mandatory;

7. Desconto do Boleto: Inform the discount amount that should be applied to tickets generated exclusively by Gerencianet. This information is optional;

8. Tipo de desconto: Inform the type of discount (percentage or fixed amount) that should be applied to the boletos generated exclusively by Gerencianet. This information is optional;

9. Numero de dias para o vencimento da cobrança: Inform the number of days for the Gerencianet boleto to expire after the charge is generated. If the field is empty, the value is 0;

10. Nome do campo referente ao CPF e/ou CNPJ: The name of the field that the WHMCS administrator created to receive the CPF and/or CNPJ of the end customer must be informed. This field is mandatory and, if you haven't created it yet, go to the WHMCS admin panel at Setup > Custom Client Fields and configure a field to receive these values. Ex: "CPF/CNPJ";

11. Valor mínimo da fatura: In this field, the minimum amount of the charge in WHMCS must be informed so that the Gerencianet boleto is generated. So, if you want to limit the generation of transactions in Gerencianet for WHMCS invoices with values greater than R$ 7.00, for example, you must fill in this field with 7.00. The discount offered in the module by Gerencianet (see field 7) is not included in the calculation of this minimum amount;

12. Sandbox: If you are interested, enable the Gerencianet API test environment;

13. Debug: In this field it is possible to enable the Gerencianet transaction and error logs in the WHMCS panel;

14. E-mail de cobrança - Gerencianet: If you are interested, enable the sending of collection emails from Gerencianet to the end customer;

15. Configuração de Multa: If you are interested, inform the amount, in percentage, charged as a fine after the due date. For example: if you want 2%, you must enter 2. Minimum of 0.01 and maximum of 10. Integer.

16. Configuração de Juros: interest charged per day after the due date. For example: if you want 0.033%, you would enter 0.033. Minimum of 0.001 and maximum of 0.33;

17. Observação: Allows you to include a message for the customer in the boleto.

CAUTION

During the configuration of our module, specifically in item 10 (see above), it is necessary that you have created a custom field (custom_field) in your WHMCS to receive the CPF and/or CNPJ from the end customer. Creation of this field is mandatory.

If not, go to the WHMCS administrative panel at Setup > Custom Client Fields and configure a field to receive these values. Ex: "CPF/CNPJ".

Note: the custom field, referring to the customer's CPF/CNPJ, must not have its position changed. We suggest this as we have seen reports from WHMCS users who have changed the field position and experienced problems with collecting customer data.

DO NOT FORGET: in our module, you must fill in item 10 with exactly the same name as you created the custom field.


CAUTION

It is important to note that boletos generated in sandbox are not valid and cannot be paid, they have the typeable line "zero" and a watermark at the bottom stating that it is a test ticket.

Payments for sandbox charges using credit card are dummy even if using a "real" card. All card payments in this environment will have the payment confirmed automatically, but this is just a status change to "Paid" . This feature allows you to test the paid status notification.

This means that all payments made in the sandbox are not real and, therefore, there is no financial charge.

It is important to know that the words Playground, Sandbox and Development Environment, in the Gerencianet's context, are synonymous in the sense that they refer to the test site we offer where you can freely test your API integration.


4. How to cancel a charge

Latest versions than 0.2.6 of the Gerencianet/WHMCS module, we have made the WHMCS automatic callback available to Gerencianet in cases of cancellation of the charges. Therefore, whenever a charge is canceled in WHMCS, it is automatically canceled in Gerencianet.

To cancel the charge on WHMCS, go to Orders > List All Orders, click on the desired invoice ID. Then click on Cancel Order (veja onde).


5. How to change the billing due date

Latest versions than 0.2.6 of the Gerencianet/WHMCS module, we have made the WHMCS automatic callback available to Gerencianet in cases of updating the bill's expiration date. Therefore, whenever the invoice has its due date modified, the Gerencianet boleto also has its due date updated.

To change the billing due date, go to Orders > List All Orders, click on the invoice ID (veja onde), then in the tab Options (veja onde) and in Due Date select the new due date (veja onde),then, click in Save Changes.


6. WHMCS discounts

In this integration module it is possible to generate charges considering the discounts of promotional coupons provided by WHMCS. If the integrator chooses one of the 4 WHMCS discount forms (percentage, fixed amount, price replacement and tariff exemption), such discount is converted into reais and passed on to the Gerencianet API at the time of generating the charge.

In addition to the discounts provided by WHMCS, it is possible to provide exclusive discounts for tickets generated through the Gerencianet module. This discount option is configured in the Desconto do Boleto and Tipo de desconto (Boleto Discount and Discount type) fields of the Gerencianet's module. Once configured, this discount will be displayed on the Gerencianet boleto and, as soon as it is paid, the order and billing amount on WHMCS will be updated to the value with the Gerencianet's discount.

Another form of discount, in addition to those mentioned above, are the credits that the user has in WHMCS. Thus, if a customer wants to apply a certain credit to the WHMCS order, such amount will be converted into a discount on the Gerencianet charge.


7. Common Integration Errors

Even before the module tries to generate a charge, some fields required in the integration go through a validation. The errors that this validation can return are:

  • Nome Inválido: The name informed by the end customer is very short, so the full name must be informed;

  • E-mail Inválido: The email provided by the end customer is invalid (does not follow the pattern xxxxx@xxxx.com) or does not exist;

  • Telefone Inválido: The telephone number informed by the end customer does not exist or the area code (DDD) is incorrect;

  • Documento Inválido: The final customer's CPF/CNPJ number is invalid;

  • Documento Nulo: The field referring to the customer's CPF and/or CNPJ does not exist in WHMCS or is not filled in;

  • Razão Social Inválida: The Social Reason is invalid. The client must type in the "Empresa" (company) field of the WHMCS the business name that appears in the Receita Federal;

  • Razão Social Nula: WHMCS "Empresa" (company) field is not populated;

  • Erro Inesperado: There was an error in the integration. You probably didn't fill in all the fields in the module correctly, or the PHP version of WHMCS is not compatible with the Gerencianet API. You will need to enable the module's Debug mode to know more details.

Even if none of these validation errors are returned, the GeGerencianet API may return errors regarding the generation of the charge. To interpret the API returns and, of course, correct possible data validation errors or similar ones, access the page "Interpretando Erros da API".


8. Gerencianet module developed by Gofas (a Gerencianet's Partnership for WHMCS)

In addition to the module for WHMCS developed internally by our team, Gerencianet has an official partner that developed a module for WHMCS separately. The solution is approved by the company and, if you prefer, you can use it:

Gerencianet module for WHMCS (credit card and boleto bancário) (developed by Maurício Gofas)


9. Support and Suggestions

Your suggestion of new ideas and implementations for the Gerencianet module for WHMCS is very important. So, if you have any ideas, please contact our team. We will analyze your suggestion and evaluate the possibility of implementation.

If you have any questions, please contact us via the website. Gerencianet.