Guia de Instalação e Configuração

1

Requisitos

Confirme o ambiente antes de instalar.

🖥️

WHMCS

Versões 8.0 a 8.13

🐘

PHP

Versões 7.4 a 8.3, com IonCube Loader compatível

🏦

Conta Asaas

Conta ativa — Sandbox ou Produção

🔑

Licença

Chave de licença válida da Modules Pay

Como verificar PHP e IonCube No admin do WHMCS, acesse Utilitários → Sistemas → PHP Info. Essa página mostra a versão do PHP e a versão do IonCube Loader em uso no servidor — confirme a compatibilidade antes de subir os arquivos.

2

Download e envio dos arquivos

Envie os arquivos do módulo para os diretórios corretos da instalação do WHMCS.

1

Baixe a versão compatível do módulo

Baixe o pacote correspondente à versão do PHP e do IonCube Loader identificados no passo anterior.

2

Extraia e envie os arquivos

Organize e transfira os arquivos para os seguintes diretórios da sua instalação do WHMCS:

/modules/gateways/
/modules/gateways/asaasboletompay/
/includes/hooks/

Mantenha a mesma estrutura de pastas do pacote — arquivos fora do lugar impedem o funcionamento correto do módulo.

3

Permissões de arquivos

O módulo grava logs, PDFs de boletos e arquivos temporários — os diretórios precisam de permissão de escrita.

Após enviar os arquivos, use a ferramenta de permissões do próprio módulo em vez de ajustar manualmente via FTP/SSH:

{seu-dominio}/modules/gateways/asaasboletompay/set_permissions.php

Essa ferramenta ajusta automaticamente as permissões (0755) da pasta includes/hooks e da pasta do próprio módulo. O acesso exige sessão de administrador logado no WHMCS e usa um token de confirmação com validade de 15 minutos.

Atenção Esse link também fica disponível diretamente na tela de configuração do gateway, no rodapé, como atalho “Setar Permissões”.

4

Ativar o gateway de pagamento

Habilite o Asaas Boleto Pay como forma de pagamento no WHMCS.

1

Acesse Setup → Payments → Payment Gateways

No menu administrativo do WHMCS, vá até a área de portais de pagamento.

2

Ative o gateway “Asaas - BOLETO”

Ele aparece na aba de gateways disponíveis para ativação. Marque-o como ativo.

3

Abra a tela de configuração

Assim que ativado, o WHMCS exibe o formulário de configuração descrito na próxima seção.

5

Configurar os campos do gateway

Preencha cada campo da tela de configuração. Campos marcados como obrigatório impedem o funcionamento do módulo se ficarem em branco.

Geral

#	Campo	Descrição
1	Versão	Informativo — exibe a versão atual instalada e avisa quando há atualização disponível.
2	Chave de Licença obrigatório	Chave de licença fornecida pela Modules Pay no momento da compra.
3	API obrigatório	Chave de API (Access Token) gerada na sua conta Asaas.
3	Token de Autenticação obrigatório	Token gerado em Integrações → Webhooks no Asaas. Deve ser idêntico ao token cadastrado no webhook (veja a seção Webhook).
4	Nome da Empresa obrigatório	Nome exibido na descrição da cobrança nas faturas.
5	Login Admin WHMCS obrigatório	Usuário administrador do WHMCS usado pelo módulo para chamadas à API interna do sistema.

Boleto

#	Campo	Descrição
6	Taxa Fixa (R$)	Valor fixo somado ao boleto por uso desse meio de pagamento. Use ponto como separador decimal. Em branco = sem taxa.
7	Taxa Percentual (%)	Percentual somado sobre o valor da fatura. Em branco = sem taxa.
8	Descrição da cobrança no Asaas	Como o texto da cobrança será montado: Empresa + Nº Fatura, com/sem descrição do serviço, ou apenas descrição do serviço.
9	Remover Faturas no ASAAS após	Dias em aberto (PENDENTE) até a cobrança ser removida automaticamente pelo cron. `0` desativa a remoção.
10	Multa por Atraso (%)	Máximo de 2%, conforme art. 52, §1º do CDC (Lei 8.078/90).
11	Juros Proporcional	Aplica até 1% ao mês, calculado proporcionalmente aos dias de atraso (≈0,033%/dia).
12	Desconto Antecipado (dias)	Quantos dias antes do vencimento o desconto passa a valer. Em branco = sem desconto.
13	Desconto Antecipado (%)	Percentual do desconto por pagamento antecipado.
14	Valor Mínimo (R$)	Valor mínimo aceito para gerar boleto. O mínimo permitido pelo Asaas é R$ 5,00.
15	Modificar data de vencimento	Se “Sim”, empurra o vencimento para o próximo dia útil quando cair em fim de semana ou feriado nacional.

Imagens

#	Campo	Descrição
16	Imagem do botão [Na Invoice]	URL da imagem do botão de pagamento na página da fatura (recomendado 160×43px). Em branco usa a imagem padrão do módulo.
17	Imagem do botão [No E-mail]	URL da imagem usada nos templates de e-mail (mesmo tamanho recomendado).
18	URL Confirmação de Pagamento	URL customizada para o botão do e-mail. Em branco redireciona para a URL padrão do Asaas.

Opções customizadas

#	Campo	Descrição
19	Permitir Notificações Asaas	Padrão “Não” — controla se o próprio Asaas pode notificar o cliente diretamente (cobrança, vencimento etc).
20	Campo CPF/CNPJ obrigatório	Campo personalizado do WHMCS onde o CPF/CNPJ do cliente está cadastrado. Veja a próxima seção.

Salvar configuração Depois de preencher os campos, clique em Salvar Alterações no rodapé da própria tela de portais de pagamento do WHMCS.

6

Campo personalizado de CPF/CNPJ

O Asaas exige CPF/CNPJ para cadastrar o cliente e emitir a cobrança.

Se o seu WHMCS ainda não possui um campo personalizado de cliente para CPF/CNPJ:

1

Acesse Setup → Custom Client Fields e crie o campo (ex.: “CPF/CNPJ”), do tipo texto.

2

Volte à configuração do gateway e selecione esse campo na opção Campo CPF/CNPJ (item 20).

Sem CPF/CNPJ, sem boleto Se o campo estiver vazio para um cliente, o módulo aborta a geração/atualização da cobrança para aquela fatura e registra um aviso no log.

7

Configurar o Webhook no Asaas

O webhook é o que permite a baixa automática das faturas quando o cliente paga o boleto.

No painel do Asaas, em Integrações → Webhooks, cadastre a seguinte URL de callback:

{systemurl}modules/gateways/callback/asaasboletompay.php

Essa mesma URL também é exibida automaticamente no rodapé da tela de configuração do gateway dentro do WHMCS, já com o domínio do seu sistema preenchido.

Eventos necessários

PAYMENT_RECEIVED
PAYMENT_CONFIRMED

Token do Webhook

Gere o token de autenticação do webhook no Asaas e cole exatamente o mesmo valor no campo Token de Autenticação da configuração do gateway (item 3). Os dois precisam ser idênticos — é essa comparação que garante que apenas o Asaas consiga notificar seu WHMCS.

Erro comum: 403 Token inválido Se o webhook retornar esse erro, confira: (1) se o token salvo no gateway é exatamente igual ao do Asaas; (2) os logs do módulo, que indicam se o token chegou corretamente sem expor o valor; (3) se a hospedagem está repassando os cabeçalhos da requisição — alguns provedores bloqueiam cabeçalhos personalizados por padrão.

8

Boleto em PDF anexado ao e-mail

Opcional, mas recomendado para melhorar a experiência do cliente.

1

Em Configurações Gerais → Faturas, verifique se a opção Habilitar Faturas em PDF está marcada.

2

Para o passo a passo completo de anexar o boleto em PDF nos lembretes de e-mail, consulte o artigo da base de conhecimento: painel.modulespay.com.br — KB #4.

9

Atualizando o módulo

Ao lançar uma nova versão, o processo de atualização é o mesmo da instalação inicial.

Baixe a versão compatívelSempre respeitando a versão do PHP/IonCube do servidor.
Reenvie os arquivosPara as mesmas três pastas: modules/gateways/, modules/gateways/asaasboletompay/ e includes/hooks/.
Salve a configuração do gatewayAcesse Portais de Pagamento → Asaas, e clique em Salvar mesmo sem alterar nada — isso aplica rotinas de atualização internas do módulo.
Confirme a versãoO card “Versão” no topo da configuração deve mostrar “Sua versão está atualizada”.

10

Checklist final

Arquivos enviados para modules/gateways/, modules/gateways/asaasboletompay/ e includes/hooks/
Permissões ajustadas via set_permissions.php
Gateway “Asaas - BOLETO” ativado em Payment Gateways
Chave de licença válida e status “Ativa”
API Key e Token de Autenticação do Asaas preenchidos
Campo personalizado de CPF/CNPJ criado e selecionado
Webhook cadastrado no Asaas com a URL de callback e o mesmo token
Eventos PAYMENT_RECEIVED e PAYMENT_CONFIRMED habilitados no webhook
Faturas em PDF habilitadas (se for usar boleto anexado ao e-mail)

11

Suporte

🌐

Site

modulespay.com.br

✉️

E-mail

contato@modulespay.com.br

📘

Documentação

Guia de Utilização

🎬

Tutorial

Vídeo tutorial