Guia de Instalação e Configuração

1

Requisitos

Confirme o ambiente antes de instalar.

🖥️

WHMCS

Versões 8.x e 9.x (compatibilidade com o WHMCS 9 a partir da v2.7)

🐘

PHP

Versão 7.4 ou superior, com cURL habilitado

🏦

Conta Asaas

Conta ativa — Sandbox ou Produção — com recebimento por cartão de crédito liberado

🔑

Licença

Chave de licença válida da Modules Pay

Como verificar a versão do PHP No admin do WHMCS, acesse Utilitários → Sistemas → PHP Info. Em versões do PHP anteriores à 7.4, o botão de pagamento não é exibido e o erro fica registrado no log de transações do gateway.

Fuso horário do servidor A partir da v2.7, o módulo não altera mais o fuso horário do PHP (isso causava erro no WHMCS 9). Defina date.timezone = America/Sao_Paulo no php.ini do servidor, para que as datas de vencimento e as tentativas de cobrança sigam o horário de Brasília.

2

Envio dos arquivos

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

1

Baixe o pacote do módulo

Baixe a versão mais recente na área do cliente da Modules Pay e extraia o arquivo no seu computador.

2

Envie os arquivos mantendo a estrutura de pastas

Transfira o conteúdo das pastas modules e includes do pacote para a raiz da sua instalação do WHMCS. Ao final, os arquivos devem estar em:

/includes/hooks/asaascartaompay.php
/modules/gateways/asaascartaompay.php
/modules/gateways/asaascartaompay/
/modules/gateways/callback/asaascartaompay.php

Arquivos fora do lugar impedem o funcionamento do módulo. O arquivo de hook, por exemplo, é o que cria as cobranças, faz as cobranças recorrentes e envia o botão de pagamento por e-mail.

3

Permissões de arquivos

As pastas do módulo precisam das permissões corretas para o servidor conseguir ler e executar os arquivos.

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/asaascartaompay/permissions.php

Essa ferramenta aplica as permissões 0755 para pastas e 0644 para arquivos. O acesso exige uma sessão de administrador ativa no WHMCS.

Atalho O link também fica no rodapé da tela de configuração do gateway, como “Setar Permissões”.

4

Ativar o gateway de pagamento

Habilite o Asaas Cartão Pay como forma de pagamento no WHMCS.

1

Acesse Setup → Payments → Payment Gateways

No menu administrativo do WHMCS, abra a tela de portais de pagamento.

2

Ative o gateway “ASAAS - CARTÃO CRÉDITO”

Ele aparece na lista de gateways disponíveis. Clique para ativá-lo.

3

Abra a tela de configuração

Depois de 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. Os números seguem os badges exibidos ao lado de cada campo no WHMCS. Se um campo marcado como obrigatório ficar em branco, o módulo não funciona.

Geral

#	Campo	Descrição
1	Versão	Informativo: exibe a versão instalada e avisa quando há atualização disponível, com atalhos para baixar a atualização e ver os logs.
2	Chave de Licença obrigatório	Chave de licença fornecida pela Modules Pay no momento da compra. O status da licença aparece logo abaixo do campo.
3	API obrigatório	Chave de API (Access Token) gerada na sua conta Asaas.
4	Token de Autenticação	Token do webhook gerado em Integrações → Webhooks no Asaas. Precisa ser idêntico ao token cadastrado no webhook (veja a seção 7). Também é usado pelo botão Processar pagamento do Asaas.
5	Nome da Empresa	Nome usado na descrição da cobrança no Asaas. Ex.: `MODULES PAY`.
6	Login Admin WHMCS obrigatório	Usuário administrador do WHMCS usado pelo módulo nas chamadas à API interna (registro de pagamentos, envio de e-mails).
7	Exibir Notificações da Modules Pay?	Mostra um pop-up na página inicial do admin com avisos de atualização do módulo.

Cartão de Crédito

#	Campo	Descrição
8	Quantidade Máxima de Parcelamento	De 1 a 12. Deixe `1` para aceitar apenas pagamento à vista.
9	Valor Mínimo para parcelamento	Vale apenas se o parcelamento máximo for maior que 1. Use ponto como separador decimal (ex.: `10.00`). Em branco = qualquer valor.
10	Ativar Pagamento Recorrente	Se ativado, o cron do WHMCS cobra automaticamente as faturas em aberto no cartão padrão do cliente. Veja a seção 9.
11	Taxa Fixa (R$)	Valor fixo somado à fatura quando o cliente paga com cartão (ex.: `2.00`). Em branco = sem taxa.
12	Taxa (%)	Percentual somado sobre o valor da fatura (ex.: `2.00`). Em branco = sem taxa.
13	Quantidade Máxima de Tentativas por Captura (dias)	De 1 a 5. Na cobrança recorrente, o módulo faz no máximo uma tentativa por dia, a partir do vencimento, até atingir esse número de dias.

Cobrança

#	Campo	Descrição
14	Descrição da cobrança no Asaas	Como o texto da cobrança é montado: Empresa + Nº da Fatura, com ou sem a descrição do serviço, Nº da Fatura + descrição, ou apenas a descrição do serviço.
15	Remover Faturas no ASAAS após	Quantidade de dias que uma cobrança pode ficar vencida até ser removida do Asaas pelo cron diário. `0` desativa a remoção.
16	Multa por Atraso (%)	Máximo de 2%, conforme o art. 52, §1º do CDC (Lei 8.078/90).
17	Juros Proporcional	Aplica até 1% ao mês, calculado proporcionalmente aos dias de atraso (≈0,033% ao dia).
18	Desconto Antecipado (dias)	Quantos dias antes do vencimento o desconto passa a valer. Em branco = sem desconto.
19	Desconto Antecipado (%)	Percentual do desconto para pagamento antecipado.
20	Valor Mínimo Para Pagamento	Valor mínimo (ex.: `15.00`) para aceitar pagamento por este gateway. O mínimo do Asaas é R$ 5,00. Abaixo dele, o cliente vê um aviso para escolher outra forma de pagamento.
21	Modificar data de vencimento	Se ativado, passa o vencimento para o próximo dia útil quando ele cai em fim de semana ou feriado nacional.

Imagens

#	Campo	Descrição
22	Imagem do botão [Na Invoice]	URL da imagem do botão de pagamento na página da fatura (recomendado 160×43 px). Em branco usa a imagem padrão do módulo.
23	Imagem do botão [No E-mail]	URL da imagem usada no botão dos e-mails (mesmo tamanho recomendado).
24	URL Confirmação de Pagamento	URL personalizada para o botão do e-mail de confirmação. Em branco redireciona para a URL padrão do Asaas.

Opções customizadas

#	Campo	Descrição
25	Permitir Notificações Asaas	Define se o próprio Asaas pode enviar notificações (cobrança, vencimento etc.) diretamente ao cliente. Marque “Não” para que só o WHMCS se comunique com o cliente.
26	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 tela de portais de pagamento.

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 26).

Sem CPF/CNPJ, sem cobrança Se o campo estiver vazio para um cliente, o módulo não consegue criar a cobrança no Asaas para as faturas dele e registra o motivo no log.

7

Configurar o Webhook no Asaas

É o webhook que dá baixa automática nas faturas quando o pagamento é aprovado.

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

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

A URL também aparece na tela de configuração do gateway no 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 4). Os dois precisam ser idênticos: é essa comparação que garante que só o Asaas consiga notificar o 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 a partir da v2.7 indicam se o token chegou vazio ou diferente; (3) se a hospedagem repassa os cabeçalhos da requisição, pois alguns provedores bloqueiam cabeçalhos personalizados por padrão.

Webhook não chegou? novo na v2.7 Se uma fatura ficar pendente no WHMCS mas já estiver paga no Asaas, a tela da fatura no admin exibe o botão Processar pagamento do Asaas, que registra o pagamento sem depender do webhook. Para isso funcionar, o Token de Autenticação deve estar preenchido e o servidor do WHMCS precisa conseguir acessar a própria URL de callback.

8

Botão de pagamento no e-mail

Opcional, mas recomendado: permite que o cliente pague direto pelo e-mail da fatura.

1

Acesse Setup → Email Templates e abra o template Invoice Created (e/ou Credit Card Invoice Created).

2

Insira o merge field {$cartaompay_button} no ponto onde o botão deve aparecer e salve o template.

Quando a fatura usa este gateway, o merge field vira um botão com a imagem configurada no item 23, que leva o cliente direto à página de pagamento por cartão.

9

Pagamento recorrente e cron

As cobranças automáticas e as rotinas de manutenção rodam junto com o cron padrão do WHMCS.

Confirme que o cron do WHMCS está configurado e rodando (Utilitários → Sistemas → Status Automação).
Ative a opção Ativar Pagamento Recorrente (item 10) e defina a Quantidade Máxima de Tentativas (item 13).
Para ser cobrado automaticamente, o cliente precisa ter um cartão salvo, ativo e marcado como padrão, em Faturamento → Meus Métodos de Pagamentos.

Nenhum cron extra é necessário O módulo usa os hooks de cron do próprio WHMCS. Não é preciso cadastrar nenhuma tarefa adicional no servidor.

10

Atualizando o módulo

O processo de atualização é o mesmo da instalação inicial.

Faça backupCopie os arquivos atuais do módulo e faça um backup do banco de dados.
Reenvie os arquivosSobrescreva os quatro locais: includes/hooks/, modules/gateways/, modules/gateways/asaascartaompay/ e modules/gateways/callback/.
Salve a configuração do gatewayAbra Portais de Pagamento → ASAAS - CARTÃO CRÉDITO e clique em Salvar, mesmo sem alterar nada.
Confirme a versãoO card “Versão” no topo da configuração deve mostrar a versão 2.7.

Atualizando para a v2.7 A versão mínima do PHP passou a ser 7.4, e o módulo deixou de definir o fuso horário por conta própria. Antes de atualizar, confira a versão do PHP e o date.timezone do servidor (veja a seção 1).

11

Checklist final

PHP 7.4 ou superior e date.timezone = America/Sao_Paulo
Arquivos enviados para includes/hooks/, modules/gateways/, modules/gateways/asaascartaompay/ e modules/gateways/callback/
Permissões ajustadas via permissions.php
Gateway “ASAAS - CARTÃO CRÉDITO” ativado em Payment Gateways
Chave de licença válida e status “Ativa”
API Key, Token de Autenticação e Login Admin WHMCS 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
{$cartaompay_button} inserido no template de e-mail de nova fatura
Cron do WHMCS rodando (necessário para o pagamento recorrente)

12

Suporte

🌐

Site

modulespay.com.br

✉️

E-mail

contato@modulespay.com.br

📘

Documentação

Guia de Utilização

🎬

Tutorial

Atalho Tutorial no rodapé da configuração do gateway