Guia de Instalação — Asaas PIX para WHMCS v3.0

1. Requisitos

WHMCS 8.0 ou superior
PHP 7.4 ou superior (compatível com PHP 8.x)
Extensões PHP curl e json habilitadas
Conta Asaas ativa, com PIX habilitado e uma chave PIX cadastrada
Licença válida do módulo, fornecida pela Modules Pay
Um campo personalizado de cliente no WHMCS para o CPF/CNPJ
Cron do WHMCS configurado e funcionando

2. Estrutura de arquivos

O pacote contém as pastas includes/ e modules/, que devem ser copiadas para a raiz da instalação do WHMCS mantendo a mesma estrutura:

includes/
└── hooks/
    └── asaaspixmpay.php              ← hooks (criação de cobranças, e-mails, crons)
modules/
└── gateways/
    ├── asaaspixmpay.php              ← arquivo principal do gateway
    ├── asaaspixmpay/                 ← funções, imagens, relatórios
    │   ├── config.php
    │   ├── functions.php
    │   ├── logs_relatorio.php
    │   ├── payment.email.php
    │   ├── processa.pix.php
    │   ├── processa.qrcode.php
    │   ├── set_permissao.php
    │   ├── whmcs.json
    │   └── images/
    └── callback/
        └── asaaspixmpay.php          ← recebe o webhook do Asaas

A pasta docs/ e o arquivo leiaantes.md são apenas documentação e não precisam ser enviados ao servidor.

3. Envio dos arquivos para o servidor

Faça o download do pacote do módulo na área do cliente da Modules Pay.
Descompacte o arquivo no seu computador.
Via FTP, SFTP ou gerenciador de arquivos da hospedagem, envie as pastas includes e modules para a raiz do WHMCS (a pasta onde estão configuration.php e init.php).
Quando o cliente de FTP perguntar, escolha mesclar as pastas — nunca substitua a pasta modules ou includes inteira.

4. Permissões

Os arquivos devem ficar com permissão 0644 e os diretórios com 0755. O módulo inclui um assistente que ajusta isso automaticamente:

Faça login no admin do WHMCS.
No mesmo navegador, acesse:
https://seudominio.com.br/modules/gateways/asaaspixmpay/set_permissao.php
Clique no botão para aplicar as permissões e confira o resultado na lista exibida.

O arquivo de licença pixlicense.dat, quando presente, recebe permissão 0600 automaticamente.

5. Preparação no painel do Asaas

Antes de configurar o WHMCS, colete os dados abaixo no painel do Asaas:

Dado	Onde encontrar
Chave da API	Integrações → Chave de API. Gere uma nova chave e copie-a — ela só é exibida uma vez.
Chave PIX	Pix → Minhas chaves. Cadastre uma chave (CNPJ, e-mail, telefone ou aleatória) se ainda não houver.
Token de autenticação do webhook	Definido por você ao criar o webhook em Integrações → Webhooks (veja a seção 8). Use uma sequência longa e aleatória.

6. Ativação do gateway no WHMCS

No admin do WHMCS, acesse Configurações (ícone de chave) → Payments → Payment Gateways.
Na aba All Payment Gateways, clique em Asaas - PIX.
O gateway passa a aparecer na aba Manage Existing Gateways, com a tela de configuração do módulo.
O quadro Versão do Módulo deve exibir 3.0. Se houver versão mais nova, um aviso com link de download é mostrado.

7. Configuração dos campos

Preencha os campos na ordem numerada da tela. Os marcados como obrigatório são necessários para o módulo funcionar.

Dados de acesso

#	Campo	O que preencher
2	Chave de Licença obrigatório	Chave fornecida pela Modules Pay. O status da licença aparece logo abaixo do campo.
3	API obrigatório	Chave da API do Asaas.
4	Chave PIX no Asaas obrigatório	A chave PIX cadastrada na sua conta Asaas.
5	Token de Autenticação obrigatório	O mesmo token informado no webhook do Asaas. Se forem diferentes, os pagamentos não serão baixados.
6	Nome da Empresa obrigatório	Nome exibido na descrição das cobranças. Ex.: `MODULES PAY`.
7	Login Admin WHMCS obrigatório	Usuário de um administrador ativo do WHMCS, usado pela API interna para registrar pagamentos.

PIX

#	Campo	O que preencher
8	Taxa Fixa (R$)	Valor adicional cobrado por pagar via PIX. Use ponto como separador: `2.00`. Em branco = sem taxa.
9	Taxa (%)	Percentual adicional. Ex.: `1.50`. Em branco = sem taxa.
10	Exibir o QrCode	No próprio WHMCS (recomendado) ou Na Página do Asaas.
11	Descrição da cobrança	Texto exibido na cobrança do Asaas: empresa, número da fatura e/ou descrição do serviço.
12	Remover Faturas no Asaas após	Dias que uma cobrança pode ficar pendente antes de ser removida do Asaas. `0` = nunca remover.
13	Multa por Atraso (%)	Máximo de 2% (art. 52, §1º, do CDC).
14	Juros Proporcional (%)	Até 1% ao mês, aplicado proporcionalmente aos dias de atraso.
15–16	Desconto Antecipado	Quantidade de dias antes do vencimento e percentual de desconto.
17	Valor Mínimo Para Pagamento	Faturas abaixo desse valor não usam o gateway. O mínimo do Asaas é R$ 5,00.
18	Modificar data de vencimento	Move o vencimento para o próximo dia útil quando cair em fim de semana ou feriado nacional.

Imagens

#	Campo	O que preencher
19	Imagem do botão [Na Invoice]	URL de uma imagem 160×43 px. Em branco = imagem padrão.
20	Imagem do botão [No E-mail]	URL de uma imagem 160×43 px para os e-mails. Em branco = imagem padrão.
21	URL Confirmação de Pagamento	Destino do botão do e-mail. Em branco = página padrão do Asaas.

Opções customizadas

#	Campo	O que preencher
22	Permitir Notificações Asaas	Não (padrão) evita que o cliente receba e-mails/SMS duplicados do Asaas além dos do WHMCS.
23	Campo CPF/CNPJ obrigatório	Selecione o campo personalizado de cliente que guarda o CPF/CNPJ.

Clique em Save Changes ao final.

Sem CPF/CNPJ válido o Asaas recusa a criação do cliente. Se o campo ainda não existe, crie-o em Configurações → Custom Client Fields antes de configurar o item 23.

8. Configuração do Webhook

O webhook é o que avisa o WHMCS quando um PIX é pago. No painel do Asaas, acesse Integrações → Webhooks e crie um webhook de cobranças com:

Campo no Asaas	Valor
URL	`https://seudominio.com.br/modules/gateways/callback/asaaspixmpay.php` Substitua pela URL do seu WHMCS (a mesma configurada em System URL).
Token de autenticação	O mesmo valor do campo 5 do módulo.
Versão da API	v3
Fila de sincronização	Ativada
Eventos	No mínimo `PAYMENT_RECEIVED` e `PAYMENT_CONFIRMED`. Outros eventos são ignorados pelo módulo.

Na versão 3.0, toda requisição recusada por token inválido ou ausente é registrada no log do módulo como SECURITY, facilitando identificar erros de digitação no token.

9. Cron do WHMCS

O módulo usa o DailyCronJob do WHMCS para criar cobranças pendentes, remover cobranças vencidas, sincronizar notificações e limpar logs antigos. Confira em Utilities → Automation Status se o cron está rodando diariamente. Exemplo de linha no crontab:

*/5 * * * * php -q /caminho/do/whmcs/crons/cron.php

10. Teste da instalação

Crie (ou use) um cliente de teste com CPF/CNPJ válido preenchido.
Gere uma fatura para esse cliente com a forma de pagamento Asaas - PIX e valor acima do mínimo.
Abra a fatura no admin: o quadro de status da cobrança deve mostrar "Cobrança já existe no Asaas".
Abra a fatura na área do cliente e clique no botão PIX — o QRCode e o código copia e cola devem aparecer.
Pague um valor baixo e verifique se a fatura muda para Paga em poucos segundos.

Se a fatura não for baixada automaticamente, use o botão Processar pagamento do Asaas (novo na 3.0) e consulte a solução de problemas para corrigir o webhook.

11. Atualizando da versão 2.x

Faça backup dos arquivos atuais do módulo e do banco de dados.
Envie os arquivos da 3.0 sobrescrevendo:
- includes/hooks/asaaspixmpay.php
- modules/gateways/asaaspixmpay.php
- modules/gateways/asaaspixmpay/ (pasta inteira)
- modules/gateways/callback/asaaspixmpay.php
As configurações do gateway são preservadas; não é preciso reconfigurar.
Abra Payment Gateways e confira se a versão exibida é 3.0.

12. Solução de problemas

Sintoma	Causa provável e solução
Gateway não aparece em Payment Gateways	Arquivo `modules/gateways/asaaspixmpay.php` ausente ou na pasta errada. Confira a estrutura.
Licença inválida ou suspensa	Verifique a chave no campo 2 e se o domínio do WHMCS é o mesmo cadastrado na licença.
Cobrança não é criada no Asaas	Cliente sem CPF/CNPJ válido, chave de API incorreta ou valor abaixo do mínimo. Consulte o relatório de logs.
Fatura paga no Asaas, mas pendente no WHMCS	Webhook com URL ou token errados, ou fila de sincronização pausada no Asaas. Corrija o webhook e use o botão Processar pagamento do Asaas na fatura.
Log "token de autenticação inválido"	O token do webhook no Asaas é diferente do campo 5 do módulo.
Log "campos ausentes no payload"	O webhook está em uma versão de API diferente da v3 ou o evento não é de pagamento PIX.

Os logs do módulo ficam em https://seudominio.com.br/modules/gateways/asaaspixmpay/logs_relatorio.php (é necessário estar logado no admin) e são mantidos por 14 dias.