1. Como o módulo funciona
- Uma fatura é criada no WHMCS com a forma de pagamento Asaas - PIX.
- O módulo cria (ou reaproveita) o cliente no Asaas, usando o CPF/CNPJ do cadastro, e gera a cobrança PIX com a referência
MPAY-{número da fatura}. - O cliente paga pelo QRCode ou pelo código copia e cola.
- O Asaas envia o webhook
PAYMENT_RECEIVED/PAYMENT_CONFIRMEDpara o callback do módulo. - O módulo registra o pagamento na fatura, que passa para Paga, e o WHMCS executa as ações normais (ativação, renovação, e-mail de confirmação).
2. Experiência do cliente
Na fatura (área do cliente)
- A fatura mostra o botão de pagamento PIX (imagem padrão ou a definida no campo Imagem do botão [Na Invoice]).
- Com Exibir o QrCode = No próprio WHMCS, o QRCode e o código copia e cola são mostrados sem sair do WHMCS.
- Com Na Página do Asaas, o cliente é redirecionado para a página de pagamento do Asaas.
- Após o pagamento, a fatura é atualizada automaticamente quando o webhook é recebido.
Requisitos do cadastro do cliente
- CPF ou CNPJ válido no campo personalizado configurado no gateway.
- Fatura com valor igual ou acima do Valor Mínimo Para Pagamento.
3. E-mails e variáveis de template
O módulo adiciona variáveis aos templates de e-mail do WHMCS (Configurações → Email Templates):
| Variável | Conteúdo |
|---|---|
{$pixmpay_button} | Botão com link para pagamento via PIX |
{$pixmpay_qrcode} | Imagem do QRCode PIX |
{$pixmpay_copiaecola} | Código PIX copia e cola |
{$mpay_link_comprovante} | Link do comprovante de pagamento |
As variáveis são preenchidas nos templates de fatura: Invoice Created, Invoice Modified, Invoice Payment Reminder, avisos de atraso (1º, 2º e 3º) e Invoice Payment Confirmation.
Exemplo de trecho para o template Invoice Created:
{$pixmpay_qrcode}Ou copie o código:
{$pixmpay_copiaecola}{$pixmpay_button}
4. Acompanhando faturas no admin
Ao abrir uma fatura do gateway Asaas PIX em Billing → Invoices, o módulo mostra um quadro com o status da cobrança no Asaas:
| Status no Asaas | Significado |
|---|---|
| Pendente (PENDING) | Cobrança criada, aguardando pagamento. |
| Recebida (RECEIVED) | PIX pago e creditado. |
| Confirmada (CONFIRMED) | Pagamento confirmado pelo Asaas. |
| Vencida (OVERDUE) | Passou do vencimento sem pagamento. |
O quadro também informa a data de criação da cobrança no Asaas.
5. Sincronização manual de pagamentos NOVO 3.0
Se o cliente pagou o PIX mas a fatura continua Não Paga no WHMCS — normalmente porque o webhook não chegou ou foi recusado —, o quadro de status exibe um botão para registrar o pagamento:
Data de criação: 12/10/2026
Processar pagamento do Asaas
A fatura está pendente no WHMCS, mas já foi paga no Asaas. Clique para registrar o pagamento sem depender do webhook.
Passo a passo
- Abra a fatura no admin.
- Clique em Processar pagamento do Asaas. O botão fica desabilitado enquanto processa.
- A página recarrega com o resultado no topo do quadro:
- Verde — "Pagamento sincronizado com sucesso. Fatura #N marcada como paga."
- Vermelho — o motivo da falha (veja a tabela abaixo).
Quando o botão aparece
- A fatura usa o gateway Asaas PIX;
- está com status Unpaid no WHMCS;
- há uma cobrança no Asaas com status RECEIVED ou CONFIRMED.
Segurança
Antes de registrar o pagamento, o módulo consulta o pagamento diretamente na API do Asaas e confirma que a referência é MPAY-{número da fatura} e que o status é pago. Em seguida executa o callback local com o mesmo conteúdo do webhook, usando o token de autenticação configurado. A ação exige sessão de administrador e token CSRF, e fica registrada no Activity Log do WHMCS.
Mensagens de erro
| Mensagem | O que fazer |
|---|---|
| Fatura não está pendente | A fatura já foi paga ou cancelada; nenhuma ação necessária. |
| O pagamento não pertence à fatura | A cobrança no Asaas tem outra referência. Verifique a cobrança no painel do Asaas. |
| O pagamento no Asaas não está pago | O status mudou desde o carregamento da página. Recarregue a fatura. |
| Falha ao acessar o callback local | O servidor não consegue acessar a própria URL do WHMCS (DNS, firewall ou SSL). Verifique a System URL. |
| Callback local recusou a requisição (token inválido) | O campo Token de Autenticação do gateway está vazio ou incorreto. |
| Callback executado, mas a fatura continua pendente | Consulte o relatório de logs para o motivo detalhado. |
6. O que acontece em cada ação da fatura
| Ação no WHMCS | Efeito no Asaas |
|---|---|
| Fatura criada | Cobrança PIX gerada automaticamente. |
| Valor ou itens da fatura alterados | Cobrança atualizada com o novo valor. |
| Fatura voltou para Não Paga | Cobrança recriada/atualizada no Asaas. |
| Fatura cancelada | Cobrança pendente removida do Asaas. |
| Fatura marcada como paga manualmente (ex.: pagamento em dinheiro) | Cobrança pendente é confirmada como recebida em dinheiro no Asaas, evitando cobrança em duplicidade. |
| Dados/CPF do cliente alterados no admin | Cadastro do cliente atualizado no Asaas. |
7. Rotinas automáticas diárias
Executadas pelo cron diário do WHMCS:
- Criação de cobranças pendentes — gera no Asaas cobranças de faturas dos últimos 3 dias que ainda não têm cobrança.
- Remoção de cobranças vencidas — quando Remover Faturas no Asaas após é maior que 0, remove cobranças pendentes há mais dias que o configurado.
- Notificações do Asaas — quando Permitir Notificações Asaas = Não, desativa as notificações automáticas do Asaas para os clientes.
- Limpeza de registros — remove registros locais de cobranças cujas faturas já foram pagas.
- Limpeza de logs — apaga logs do módulo com mais de 14 dias.
8. Relatório de logs
Com uma sessão de administrador ativa, acesse:
https://seudominio.com.br/modules/gateways/asaaspixmpay/logs_relatorio.php
É possível filtrar por tipo, período e quantidade de registros (50 a 500).
| Tipo | Uso |
|---|---|
| INFO | Operações normais: cobranças criadas, eventos recebidos, sincronizações. |
| WARNING | Eventos ignorados: payload vazio, JSON inválido, campos ausentes, forma de pagamento não tratada. |
| ERROR | Falhas ao registrar pagamento ou comunicar com o Asaas. |
| SECURITY | Licença inválida e requisições de webhook recusadas por token. |
9. Boas práticas
- Mantenha Permitir Notificações Asaas em Não para que o cliente receba apenas os e-mails do WHMCS.
- Respeite os limites legais: multa até 2% e juros até 1% ao mês.
- Torne o CPF/CNPJ obrigatório no cadastro de clientes.
- Confira periodicamente no Asaas se a fila do webhook não está pausada (o Asaas pausa a fila após falhas seguidas).
- Revise os logs WARNING e SECURITY após mudanças de servidor, domínio ou token.
10. Perguntas frequentes
O cliente pagou e a fatura não baixou. O que faço?
Abra a fatura no admin e clique em Processar pagamento do Asaas. Depois, verifique no log se há registros de token recusado e corrija o webhook.
Posso usar a chave de API de sandbox?
Use sempre a chave de produção em ambiente real. Cobranças de teste não geram pagamentos reais.
O cliente pode pagar uma fatura vencida?
Sim. Multa e juros configurados são aplicados pelo Asaas no momento do pagamento. Se a cobrança foi removida pela rotina de limpeza, ela é gerada novamente quando a fatura é atualizada.
Por que algumas faturas não mostram o botão PIX?
O valor está abaixo do mínimo configurado ou o cliente não tem CPF/CNPJ válido.