Guia de Instalação — Asaas Cobrança MPAY

1

✅ Requisitos

🖥️WHMCS 8.x ou superior

🐘PHP 8.1 ou superior

🔌Extensões curl e openssl habilitadas

🏦Conta ativa no Asaas (produção e/ou sandbox)

Nenhuma dependência via Composer é necessária — o módulo é autocontido.

2

📦 Copiar os arquivos

Copie o conteúdo do pacote para a raiz da instalação do WHMCS, mantendo a estrutura de pastas:

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

Ao atualizar uma instalação existente, basta sobrescrever os arquivos. As tabelas e colunas novas do banco são criadas sozinhas no primeiro acesso seguinte — não é preciso rodar nenhum script.

3

🔑 Ativar o gateway

Acesse Configurações (Setup) > Pagamentos > Gateways de Pagamento.
Na aba All Payment Gateways, localize Asaas Cobrança MPAY — Boleto, Pix e Cartão e clique para ativar.
Ao abrir a tela de configuração pela primeira vez, o módulo cria automaticamente as tabelas do banco de dados.
Preencha sua API Key (produção e/ou sandbox), habilite as formas de pagamento desejadas e salve. O status da conexão aparece logo abaixo do campo.

4

🔑 Chave da Licença (Modules Pay)

O Asaas Cobrança MPAY é um módulo comercial — sem uma licença ativa, novas cobranças não são criadas (as já existentes continuam funcionando normalmente para consulta e baixa).

Adquira/consulte sua Chave da Licença com a Modules Pay.
Cole no campo "Chave da Licença", na seção "Conexão com a Modules Pay" da configuração do gateway.
O status (ativa/inativa e o motivo) aparece ao lado do campo logo após salvar.

5

🔗 Configurar o Webhook no Asaas

No painel do Asaas, vá em Configurações > Webhooks.
Clique em Adicionar Webhook e cole a URL exibida na tela de configuração do gateway (algo como https://seudominio.com.br/modules/gateways/callback/asaascobrancas.php).
No campo de token/autenticação (header asaas-access-token), cole o Token exibido na mesma tela.
Marque os eventos:
- Pagamento: PAYMENT_RECEIVED, PAYMENT_CONFIRMED, PAYMENT_OVERDUE, PAYMENT_DELETED, PAYMENT_REFUNDED, PAYMENT_UPDATED.
- Cartão de crédito: PAYMENT_AWAITING_RISK_ANALYSIS, PAYMENT_APPROVED_BY_RISK_ANALYSIS, PAYMENT_REPROVED_BY_RISK_ANALYSIS, PAYMENT_CREDIT_CARD_CAPTURE_REFUSED.

⚠️ Se você usa o Modo Sandbox, cadastre o webhook no painel sandbox.asaas.com — são contas e tokens independentes da produção. O webhook é obrigatório: é ele que dá baixa nas faturas de boleto/Pix, confirma pagamentos de cartão que ficaram em análise e quita faturas pagas em parcelas.

6

🪪 Campos de CPF/CNPJ

O módulo lê o CPF/CNPJ do cliente a partir de Campos Personalizados de Cliente (Setup > Custom Client Fields) — crie-os antes de configurar o gateway.

Modo único: um campo só (ex.: CPF/CNPJ), aceita os dois formatos.
Modo separado: dois campos (ex.: CPF e CNPJ) — se ambos preenchidos, o CNPJ tem prioridade.

Na configuração do gateway, esses campos aparecem como uma lista suspensa com os campos já cadastrados — basta selecionar. O campo "Forma de Pagamento Preferida" do cliente é criado pelo próprio módulo — não precisa criar.

7

⚙️ Regras de geração de cobrança

Estas opções definem como cada cobrança nova é gerada no Asaas (automática ou manual):

Opção	O que faz
⭐ Forma de pagamento padrão	Forma usada quando o cliente não tem uma "Forma de Pagamento Preferida" ou quando a preferida dele está desabilitada no gateway. Também é gravada como preferida em todo cliente novo.
💰 Aplicar crédito do cliente ao gerar cobrança	Marcado: o crédito que o cliente tem no WHMCS é aplicado na fatura antes, e a cobrança sai só pelo restante (ou não sai, se o crédito quitar tudo).
📅 Gerar cobrança de fatura vencida com a data do dia	O Asaas não aceita vencimento no passado. Marcado: fatura já vencida gera cobrança com vencimento hoje e com a multa e os juros acumulados até hoje somados ao valor. Desmarcado: fatura vencida não gera cobrança nova.
🧾 Juros ao mês / Multa por atraso	Enviados ao Asaas em toda cobrança e usados no cálculo da opção acima.

O Asaas não aceita cobrança abaixo de R$ 5,00. Se o valor final (depois de crédito, taxa e acréscimos) ficar abaixo disso, a cobrança não é gerada — o admin vê um aviso na geração manual e a geração automática só registra no log.

8

🧾 PDF real do boleto nos e-mails recomendado

Para o e-mail anexar o boleto real da Asaas (em vez do PDF de fatura padrão do WHMCS):

A biblioteca TCPDI já vem incluída em modules/gateways/asaascobrancas/tcpdi/ — nenhum download ou instalação necessária.
Localize o invoicepdf.tpl do seu tema ativo (ex.: templates/twenty-one/invoicepdf.tpl).
Renomeie o original para invoicepdf-original.tpl — nunca apague, ele é o fallback.
Copie modules/gateways/asaascobrancas/templates/invoicepdf.tpl para a pasta do tema, como invoicepdf.tpl.
Confirme em Configurações Gerais > Mail que "Anexar PDF da Fatura" está habilitado.

Se trocar de tema no futuro — ou atualizar o módulo e o invoicepdf.tpl dele tiver mudado — repita os passos 2–4. Atualizar só a cópia dentro da pasta do módulo não tem efeito.

9

💳 Cartão de crédito: parcelamento e cartão salvo

Parcelamento: defina o "Parcelamento máximo" (1 a 12) e "Quem assume os juros do parcelamento" (cliente = parcelas com juros de 1,99% a.m.; loja = valor só dividido). O parcelamento é criado de verdade no Asaas; no WHMCS a fatura é quitada inteira de uma vez.

Cartão salvo (tela "Meus Cartões" do cliente, pagamento com um clique e cobrança automática no vencimento). No campo "Forma de armazenamento do cartão salvo", escolha:

TOKENIZAÇÃO (padrão, recomendado) — a Asaas guarda um token do cartão; número e CVV nunca ficam no seu banco. Exige habilitação da Asaas para uso em Produção (funciona livre em Sandbox) — solicite ao seu gerente de contas Asaas.
SEM TOKENIZAÇÃO — número e CVV ficam criptografados no seu próprio banco, sem precisar de aprovação da Asaas. A tela de configuração explica por que isso não é recomendado (não segue o padrão PCI-DSS da indústria de cartões) — use só se você entende esse risco.

⚠️ Sem a habilitação da tokenização na sua conta Asaas, nenhum cartão é salvo no modo TOKENIZAÇÃO — e, sem cartão salvo, a cobrança automática nunca acontece. O cliente vê o aviso "não foi possível salvar o cartão" e o log do módulo registra um erro com essa orientação. Peça a habilitação ou troque para SEM TOKENIZAÇÃO.

10

🎨 Personalização (opcional)

Na configuração do gateway você também pode ajustar, sem mexer em código:

🔘Texto, cor e imagem do botão "Pagar" da fatura e do e-mail

🎨Cor de fundo da página de checkout

💰Desconto e taxa adicional por forma de pagamento (R$ e, só no cartão, também %)

📨Botão de pagamento e anexo de PDF nos e-mails

11

🧪 Teste antes de ir para produção

Ative o Modo Sandbox e gere uma fatura de teste.
Acesse o link "Pagar" da fatura e teste as três formas de pagamento — no cartão, teste também o pagamento parcelado.
Confirme que o webhook de sandbox está dando baixa automaticamente.
Se usar cartão salvo: salve um cartão em "Meus Cartões" e deixe uma fatura de cartão vencendo para conferir a cobrança automática no cron do dia.
Só então desative o Modo Sandbox e coloque a API Key de produção (e cadastre o webhook de produção).