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

💳 As três formas de pagamento

⚡

Pix

QR Code + código "copia e cola" no checkout.
Confirmação automática em segundos, sem o cliente sair da página.

🧾

Boleto

Linha digitável com botão de copiar.
Visualizar/baixar o boleto direto no checkout.
Juros, multa e desconto aplicados automaticamente pela Asaas.

💳

Cartão de Crédito

Aprovação confirmada na hora (ou depois, se cair em análise da Asaas).
Parcelamento real no Asaas; no WHMCS a fatura é quitada inteira de uma vez.
Cartão salvo para pagar com um clique e cobrança automática no vencimento.

🧭 Jornada do cliente

O cliente recebe a fatura por e-mail ou acessa o portal e clica no botão "Pagar".
Cai no checkout transparente do Asaas Cobrança MPAY — não sai do seu domínio.
Escolhe a forma de pagamento. O resumo mostra o valor original, crédito/pagamentos já aplicados, taxa adicional e multa/juros por atraso (quando houver).
Paga via Pix, boleto ou cartão (à vista ou parcelado). Pix e cartão confirmam na hora; boleto aguarda compensação.
A fatura é baixada automaticamente assim que o pagamento é confirmado, sem intervenção manual — e o valor sempre fecha o saldo da fatura (sem gerar crédito indevido).

⚙️ Como cada cobrança nova é gerada

Quando: ao publicar/criar a fatura (manual ou pelo cron), ao marcar como não paga, ao trocar o gateway da fatura para o Asaas Cobrança MPAY, ao abrir o checkout, ou pela verificação diária de faturas que ficaram sem cobrança. Fatura em rascunho nunca gera cobrança — só depois de publicada.
Forma de pagamento: a "Forma de Pagamento Preferida" do cliente, se estiver habilitada no gateway; senão, a "Forma de pagamento padrão". Uma escolha feita no checkout sempre prevalece.
Valor: o saldo em aberto da fatura (total menos crédito e pagamentos já aplicados) + taxa adicional da forma de pagamento. Com a opção de crédito ligada, o crédito do cliente é aplicado antes.
Fatura vencida: com a opção "Gerar cobrança de fatura vencida com a data do dia" ligada, vence hoje e já inclui multa e juros até hoje; desligada, não gera (o cliente vê um aviso para entrar em contato).
Valor mínimo: abaixo de R$ 5,00 o Asaas não aceita — a cobrança não é gerada (aviso na geração manual; registro no log na automática).
Descrição no Asaas: "Fatura #N - nome do(s) serviço(s)" (produto, addon ou domínio da fatura) ou "Fatura #N - Fatura Avulsa".
Cliente no Asaas: criado automaticamente se não existir, com o ID do cliente do WHMCS como "Identificador externo".

🔄 O que acontece quando a fatura muda no WHMCS

Ação no WHMCS	Efeito no Asaas
Fatura cancelada	Cobrança cancelada no Asaas (parcelamento: todas as parcelas).
Marcada como paga (por outro meio)	Cobrança cancelada no Asaas — a não ser que já esteja paga lá.
Itens/valor editados	Valor e descrição atualizados. Se a cobrança não existir mais, é criada de novo.
Vencimento editado	Atualizado ao abrir a fatura no admin (o WHMCS não avisa só essa alteração).
Marcada como não paga	Cobrança criada (se não houver) ou atualizada.

💳 Parcelamento no cartão

O cliente escolhe o número de parcelas no checkout (até o "Parcelamento máximo" configurado).
O módulo cria um parcelamento novo no Asaas com o cartão. Se o cartão for recusado, nada é criado e a cobrança anterior continua valendo.
Aprovado: a cobrança à vista anterior é removida (para o cliente não pagar duas vezes) e a fatura é quitada inteira no WHMCS, com as linhas "Taxa Aplicada", "Multas e Juros Aplicado" e "Juros do Parcelamento" quando aplicáveis.
Em análise: a fatura é quitada quando a Asaas confirmar (webhook).

Juros do parcelamento: "Quem assume os juros" = cliente → parcelas com 1,99% a.m. (a diferença vira a linha "Juros do Parcelamento"); = loja → valor só dividido. Cada parcela precisa ser de pelo menos R$ 5,00.

🔁 Cartão salvo e cobrança automática

O cliente tem uma tela própria "Meus Cartões" (atalho no menu da área dele) para salvar, listar, remover e escolher o cartão padrão. Cartões vencidos aparecem marcados como "Vencido" e não são usados.

No checkout: com cartão salvo, paga sem redigitar os dados (TOKENIZAÇÃO) ou digitando só o CVV (SEM TOKENIZAÇÃO).
Quais faturas: só as que têm cobrança de Cartão de Crédito — faturas de boleto/Pix nunca são cobradas no cartão automaticamente.
Quando: a partir do dia do vencimento (nunca antes), uma vez por dia, no cron diário do WHMCS.
Tentativas: até 3, no máximo uma por dia (normalmente no vencimento, 1 e 2 dias depois; se o cron não rodar num dia, a tentativa acontece nos dias seguintes, até 7 dias após o vencimento). A 1ª usa o cartão padrão; as seguintes alternam entre os outros cartões válidos.
Em análise na Asaas: não conta como falha — o módulo aguarda a decisão (webhook).
A cada recusa: o cliente recebe um e-mail (nas 1ª e 2ª: "tentaremos de novo amanhã, ou pague agora"; na 3ª: "pague manualmente"), o admin recebe um e-mail com o motivo da recusa, e o caso aparece em destaque no painel da fatura e no widget "Cartões recusados" do painel inicial do admin. A fatura continua em aberto e pode ser paga normalmente.
Sem cartão (ou só cartão vencido): nada é cobrado; fica registrado no resumo diário do log. O cliente paga pelo checkout, como qualquer outra fatura.
Vencimento prorrogado: as 3 tentativas recomeçam a partir do novo vencimento.

Quer personalizar os e-mails ao cliente? Crie modelos de e-mail do tipo Fatura em Configurações > Modelos de E-mail com os nomes exatos Asaas Cobrança MPAY - Tentativa de Cobranca Recusada (1ª e 2ª recusas) e Asaas Cobrança MPAY - Falha na Cobranca Automatica (3ª recusa) — eles passam a ser usados no lugar do texto padrão.

🖥️ Painel na tela da fatura (admin)

Ao abrir uma fatura do Asaas Cobrança MPAY no admin, o painel "Asaas Cobrança MPAY — Cobrança" mostra status no Asaas, forma de pagamento, ID da cobrança, valor e, se for o caso, o parcelamento. As ações abaixo só aparecem enquanto a cobrança está em aberto:

🔄 Sincronizar status agora ♻️ Recriar cobrança 🚫 Cancelar cobrança no Asaas

Link exibido: em aberto → boleto (ou fatura Asaas, no cartão); paga → comprovante de pagamento; cancelada/estornada → nenhum.
Sem cobrança: se a fatura estiver em aberto, aparece "Criar cobrança agora"; em rascunho, paga ou cancelada, o painel não aparece.
💳 Cobrar no cartão salvo: em faturas cuja cobrança é de Cartão de Crédito (à vista) e cujo cliente tem cartão salvo válido, o admin escolhe o cartão e cobra na hora. Não gasta as tentativas da cobrança automática, e recarregar a página não cobra de novo. Use este botão no lugar do "Tentar Capturar" nativo do WHMCS, que não funciona com este módulo.

✉️ E-mails de fatura

Se "Anexar PDF do boleto" e "Adicionar botão de pagamento" estiverem ativos na configuração, cada e-mail de fatura do Asaas Cobrança MPAY chega com o boleto real em PDF e um botão "Pagar Agora" (texto/cor/imagem configuráveis) que já leva à forma de pagamento atual da cobrança.

Merge field	O que faz
`{$asaas_payment_buttons}`	Botão de pagamento único.
`{$asaas_boleto_linha_digitavel}`	Linha digitável do boleto (quando a forma atual é boleto).

Esses campos aparecem em "Campos de Mesclagem Disponíveis" ao editar um template em Setup > Email Templates.

🎨 O que dá para personalizar sem mexer em código

🔘

Botões

Texto, cor e imagem própria — separadamente para o botão da fatura e o botão do e-mail.

🖼️

Checkout

Cor de fundo da página — o texto do cabeçalho/rodapé se ajusta sozinho para continuar legível.

💰

Taxas e descontos

Juros, multa, desconto e taxa adicional por forma de pagamento — no cartão, a taxa adicional pode ser em R$ e em % ao mesmo tempo.

🩺 Se algo der errado

Pagamento não deu baixa sozinho: confira o webhook cadastrado no painel Asaas (incluindo os eventos de cartão) e veja os logs filtrando por contexto webhook.
Cobrança não foi gerada: veja os logs da fatura — os motivos mais comuns são fatura vencida sem autorização, valor abaixo de R$ 5,00, fatura quitada por crédito, CPF/CNPJ inválido ou licença inativa.
Cobrança automática não aconteceu: o resumo diário no log (contexto cron) diz o motivo de cada fatura: não é de cartão, cliente sem cartão, só cartão vencido, em análise, tentativas esgotadas…
Cartão não fica salvo: no modo TOKENIZAÇÃO, a habilitação para Produção precisa ser solicitada e aprovada pela Asaas (funciona direto em Sandbox) — troque para SEM TOKENIZAÇÃO enquanto isso, se preferir.
Checkout ou anexos com erro estranho: confira a página de permissões — pastas como pdf/ e templates/compiled/ precisam ser graváveis.
Qualquer outro comportamento inesperado: mude o Nível de log para "debug" na configuração do gateway e acompanhe pelos logs.