Guia de Utilização

Da criação da fatura até a baixa do pagamento, tudo acontece automaticamente por meio de hooks ligados ao ciclo de vida da fatura no WHMCS.

• Fatura criada no WHMCSO módulo cadastra o cliente no Asaas (se necessário) e cria a cobrança de cartão de crédito.
• E-mail enviado ao clienteCom o botão “Pagar com Cartão”, que leva direto à página de pagamento.
• Cliente paga com um cartão salvoÀ vista ou parcelado, conforme a configuração da loja.
• Ou o cron cobra automaticamenteCom o pagamento recorrente ativo, o cartão padrão do cliente é cobrado a partir do vencimento.
• Asaas confirma o pagamentoO webhook avisa o WHMCS e a fatura é baixada automaticamente.
• Fatura cancelada ou paga por outro meioA cobrança no Asaas é removida ou marcada como recebida, mantendo os dois sistemas em sincronia.

Disparada quando uma fatura é criada com o gateway ASAAS - CARTÃO CRÉDITO.

Para cada fatura nova deste gateway, o módulo:

1. Confirma se a licença está ativa e se o gateway está habilitado.
2. Procura o cliente no Asaas pelo CPF/CNPJ e, se ele não existir, faz o cadastro.
3. Monta os dados da cobrança: valor, vencimento, multa, juros e desconto antecipado, se configurados.
4. Verifica se já existe cobrança para a fatura no Asaas, para evitar duplicidade.
5. Cria a cobrança, identificada no Asaas pela referência MPAY-{id da fatura}.

O módulo preenche o merge field {$cartaompay_button} nos e-mails de nova fatura.

O botão só aparece quando a cobrança da fatura está pendente ou vencida no Asaas.

Na área do cliente, ao abrir a fatura, o cliente vê o botão “Pagar via Cartão Crédito”.

• A página mostra o valor da fatura, o valor das taxas (fixa e/ou percentual, se configuradas) e o valor total.
• Se o total ficar abaixo do Valor Mínimo Para Pagamento, o botão é substituído por um aviso para escolher outra forma de pagamento.
• Na página de pagamento, o cliente escolhe um dos cartões salvos e, se o parcelamento estiver liberado, o número de parcelas (até o máximo configurado e respeitando o valor mínimo para parcelar).
• Se o cliente ainda não tiver um cartão salvo, ele é orientado a cadastrar um antes de pagar.
• Não é preciso enviar comprovante: a baixa é automática depois que o pagamento é aprovado.

Área onde o cliente gerencia os próprios cartões.

O módulo adiciona o item Meus Métodos de Pagamentos ao menu Faturamento da área do cliente (/modules/gateways/asaascartaompay/cartao.php). Nessa tela o cliente pode:

• Adicionar um cartão. O primeiro cartão cadastrado já se torna o padrão.
• Editar os dados de um cartão salvo.
• Definir como padrão o cartão usado nas cobranças automáticas.
• Remover um cartão.

Bandeiras aceitas: Visa, Mastercard, American Express, Elo, Diners Club, Discover, JCB, Aura e Hipercard. Cartões de outras bandeiras são recusados com um aviso.

Funciona quando a opção Ativar Pagamento Recorrente está ligada. Roda a cada execução do cron do WHMCS.

A cada execução, o módulo procura faturas deste gateway que estejam Unpaid e cujo vencimento esteja dentro da janela de Quantidade Máxima de Tentativas (1 a 5 dias). Para cada uma:

1. Usa o cartão do cliente marcado como padrão e com status Ativo.
2. Tenta cobrar a cobrança pendente ou vencida no Asaas com esse cartão.
3. Grava a tentativa na fatura, garantindo no máximo uma tentativa por dia.
4. Registra o resultado (sucesso ou motivo da recusa) no histórico de cobranças do cartão.

Quando a cobrança falha

• O cliente recebe um e-mail informando a falha e o motivo retornado pela operadora.
• Se o cliente não tem nenhum cartão salvo, recebe um e-mail pedindo para cadastrar um.
• Ao entrar na área do cliente com uma fatura vencida que teve tentativa recusada, o cliente vê um aviso pedindo para conferir o cartão ou trocar a forma de pagamento da fatura.

Feita pelo callback (webhook), sem nenhuma ação manual no WHMCS.

Quando o Asaas envia os eventos PAYMENT_RECEIVED ou PAYMENT_CONFIRMED para a URL de callback, o módulo:

1. Valida o token de autenticação do webhook.
2. Localiza a fatura pela referência MPAY-{id da fatura}.
3. Confere se a transação ainda não foi registrada e se o valor pago confere, inclusive em pagamentos parcelados.
4. Registra o pagamento e marca a fatura como paga no WHMCS.

Cobranças sem referência externa (que não foram criadas por este módulo) são ignoradas, sem gerar log.

Painéis extras na fatura do WHMCS, sem precisar abrir o Asaas.

Status da cobrança no Asaas

Mostra o status atual da cobrança (Pendente, Vencido, Confirmado, Recebido, Recebido em dinheiro ou Cancelado) e a data de criação.

Capturar Pagamento

Em faturas Unpaid de clientes com cartão padrão ativo, o botão Capturar Pagamento cobra a fatura na hora no cartão do cliente. Antes de prosseguir, o módulo exibe um aviso sobre o risco de bloqueio do cartão ou da conta Asaas após várias tentativas sem sucesso. Se o cliente não tiver cartão ativo, a tela avisa. Abaixo do botão fica o histórico de tentativas de cobrança daquela fatura.

Processar pagamento do Asaas novo na v2.7

Se a fatura está pendente (Unpaid) no WHMCS, mas a cobrança já consta como Recebido ou Confirmado no Asaas (por exemplo, porque o webhook falhou), o painel exibe o botão Processar pagamento do Asaas. Ao clicar, o módulo:

1. Consulta o pagamento atualizado diretamente na API do Asaas.
2. Confere se o pagamento pertence à fatura (MPAY-{id da fatura}) e se está realmente pago. Em parcelamentos, usa a primeira parcela paga.
3. Executa o callback local com o mesmo conteúdo que o webhook do Asaas enviaria, autenticado com o Token de Autenticação do gateway.
4. Mostra o resultado no topo da tela da fatura e registra a operação nos logs do módulo e no log de atividades do WHMCS.

Mantém o Asaas em sincronia quando o admin marca a fatura como paga no painel.

Se um administrador marcar como Paid uma fatura deste gateway, o módulo confirma a cobrança correspondente no Asaas como recebida em dinheiro. Assim, ela não fica pendente ou vencida no Asaas enquanto já está quitada no WHMCS.

Cobre reaberturas, alterações de valor/itens e cancelamentos.

Fatura reaberta ou com valor alterado

Quando uma fatura volta para Unpaid ou tem o total alterado, o módulo verifica a cobrança no Asaas:

• Se ela existir e estiver pendente ou vencida, é atualizada com o novo valor e vencimento.
• Se não existir, uma nova cobrança é criada e o e-mail da fatura é reenviado ao cliente com o botão de pagamento.

Assim como na criação, a partir da v2.7 essas atualizações feitas pelo painel acontecem ao final da requisição, para não causar erro no WHMCS 9.

Fatura cancelada

Ao cancelar uma fatura deste gateway, o módulo localiza a cobrança no Asaas e a remove.

Executadas junto com o cron diário do WHMCS. Nenhuma configuração extra é necessária.

Acessíveis pelos atalhos no rodapé da tela de configuração do gateway.

Ver Logs no Banco

{seu-dominio}/modules/gateways/asaascartaompay/logs.php

Lista todos os eventos registrados pelo módulo (criação de cobrança, erros de API, callbacks, cobranças recorrentes, sincronizações etc.). Permite filtrar por tipo e por período, e apagar todos os registros de uma vez.

Setar Permissões

{seu-dominio}/modules/gateways/asaascartaompay/permissions.php

Reaplica as permissões corretas nas pastas do módulo. Útil depois de uma atualização via FTP que tenha alterado as permissões.

• O gateway está disponível apenas em português e aceita somente Real (BRL).
• O webhook no Asaas é indispensável: sem ele, nenhum pagamento é baixado automaticamente.
• Se uma fatura consta como paga no Asaas e continua pendente no WHMCS, use o botão Processar pagamento do Asaas em vez de lançar o pagamento manualmente. Assim a baixa usa os dados reais do pagamento.
• Use o botão Capturar Pagamento e o número de tentativas da cobrança recorrente com moderação, para não gerar bloqueios na operadora ou no Asaas.
• Oriente os clientes a manter um cartão válido marcado como padrão em Meus Métodos de Pagamentos.
• O botão de pagamento foi desenvolvido para o tema padrão do WHMCS. Em temas muito customizados, teste o fluxo de pagamento.