Visão geral
Do momento em que a fatura é aberta até ela aparecer como paga.
Toda cobrança é uma Pix com vencimento: ela tem data de vencimento, aceita pagamento até alguns dias depois (campo Tempo de Expiração) e pode embutir multa, juros e desconto. O módulo cria apenas uma cobrança por fatura e a reaproveita sempre que possível.
O que o cliente vê
A tela de pagamento aparece dentro da própria fatura do WHMCS.
- Resumo dos valores. Valor da fatura e, quando houver, taxas, multa/juros e desconto. O Valor a Pagar só aparece quando há algum desses ajustes.
- QR Code. Gerado pela Efí para a cobrança da fatura.
- Pix Copia e Cola. O botão Copiar coloca o código na área de transferência para colar no app do banco.
- Confirmação automática. Enquanto a fatura está aberta, a página consulta o pagamento a cada 3 segundos por até 3 minutos. Quando o Pix é confirmado, a fatura recarrega como paga.
- Sem comprovante. O cliente não precisa enviar nada: a baixa é feita pelo webhook, mesmo que ele feche a página.
Quando a tela de Pix não apareceSe a licença estiver inativa, a fatura estiver abaixo do Valor Mínimo, o CPF/CNPJ for inválido ou a Efí recusar a cobrança, o cliente vê um aviso no lugar do QR Code. Veja a lista de mensagens.
Como o valor é calculado
Os encargos vêm das configurações do gateway e são aplicados na cobrança Pix.
| Item | Regra |
|---|---|
| Taxas | Taxa Fixa + Taxa % sobre o valor da fatura. Sempre somadas ao Pix. |
| Desconto antecipado | Percentual sobre (fatura + taxas), válido até N dias antes do vencimento. Depois dessa data, o valor volta ao normal. |
| Multa | Percentual configurado (máx. 2%) aplicado quando a fatura já está vencida. |
| Juros | Se ativado, 1% ao mês proporcional aos dias de atraso (≈ 0,033% ao dia), calculado pela Efí no momento do pagamento. |
| Vencimento | A data de vencimento da fatura, ajustada para o próximo dia útil. Em fatura vencida, a cobrança é reemitida com vencimento no próximo dia útil a partir de hoje. |
| Validade | Após o vencimento, o Pix ainda pode ser pago pelo número de dias definido em Tempo de Expiração. |
Exemplo
Fatura de R$ 100,00 com Taxa Fixa 1.00, Taxa 2.00%, Multa 2.00% e desconto de 5.00% até 3 dias antes do vencimento.
Pago com antecedência
Pago até o vencimento
Fatura vencida
Na baixa, a diferença entre o valor pago e o valor da fatura vira itens na própria fatura, para que o total feche com o que entrou na conta (veja a etapa 5).
Crédito do clienteCom Aplicar Crédito ativado, o saldo de crédito do cliente é aplicado à fatura quando ela é criada, e o Pix cobre apenas o valor restante.
Ciclo de vida da cobrança
A cada abertura da fatura, o módulo consulta a cobrança na Efí e decide o que fazer.
| Situação na Efí | O que o módulo faz |
|---|---|
| Não existe | Cria a cobrança e grava os dados na tabela mod_efimpay. |
| ATIVA | Mostra o mesmo QR Code. Se o valor mudou ou a fatura venceu, atualiza a cobrança (valor e vencimento) antes de exibir. |
| CONCLUIDA | Informa que a fatura já está paga. |
| REMOVIDA_PELO_USUARIO_RECEBEDOR | A cobrança foi removida no painel da Efí. O módulo gera uma nova. |
Por isso, editar itens, aplicar descontos manuais ou mudar o vencimento da fatura no WHMCS é seguro: na próxima abertura, o Pix é ajustado ao novo valor.
As cobranças do módulo têm um txid no formato <ID da fatura>EFIMPAY<aleatório>. Assim é possível localizar no painel da Efí a fatura de cada Pix.
Baixa automática
O que acontece no WHMCS quando a Efí confirma o pagamento.
- A Efí envia o webhook com o
txid, o valor pago e o identificador da transação (endToEndId). - O módulo identifica a fatura pelo
txide confirma que ela está Em aberto. Notificações de faturas já pagas são ignoradas. - Se a transação já estiver registrada, nada é feito. Isso evita pagamento em duplicidade quando a Efí reenvia a notificação.
- Os ajustes são lançados como itens da fatura, com descrições fáceis de reconhecer:
EFI PIX MPAY: Taxa do Serviço– taxas fixa e percentualEFI PIX MPAY: Desconto Pagamento Antecipado– valor negativoEFI PIX MPAY: Multas e Juros por Atraso
- O pagamento é registrado na fatura com o
endToEndIdcomo ID da transação. Taxas e multa ficam no campo de tarifas da transação. - O WHMCS marca a fatura como Paga e segue a automação normal: e-mail de confirmação, desbloqueio de serviços etc.
Pagamentos feitos por foraUm Pix enviado direto para a sua chave, sem usar o QR Code da fatura, não tem txid do módulo e não é baixado automaticamente. Registre esse pagamento manualmente na fatura.
Rotina do administrador
Onde acompanhar o módulo no dia a dia.
Em Utilitários → Logs → Log de Atividades, filtre por [EFI PIX MPAY]: criação de cobranças, pagamentos, ajustes e erros.
O status aparece abaixo do campo Chave de Licença. Sem licença ativa, o gateway deixa de exibir o Pix.
O campo Versão avisa quando há nova versão, com links para download e para o histórico de mudanças.
A tabela mod_efimpay guarda, por fatura: txid, QR Code, valor, vencimento, status e data de pagamento.
Boas práticas
- Renove o certificado antes de expirar. Gere um novo na Efí, converta para
.pem, envie paracerts/e selecione-o nas configurações. - Trocou de chave Pix ou de domínio? Atualize o campo Chave Pix, salve e abra uma fatura para recadastrar o webhook.
- Não cancele cobranças pela Efí sem necessidade. Se cancelar, o módulo cria outra na próxima abertura, com um novo QR Code.
- Mantenha o CPF/CNPJ dos clientes preenchido. É a causa mais comum de Pix não gerado.
Mensagens exibidas ao cliente
Avisos que podem aparecer no lugar do QR Code, e o que fazer.
| Mensagem | Causa e solução |
|---|---|
| Este gateway no momento não está funcional | Licença inativa, ou a fatura usa outra forma de pagamento. Verifique a licença no gateway. |
| O valor da fatura … é inferior ao valor mínimo | Fatura abaixo do Valor Mínimo. O cliente deve usar outra forma de pagamento, ou reduza o mínimo. |
| O CPF/CNPJ … não é um documento válido | Documento vazio ou inválido no cadastro do cliente. Corrija o perfil do cliente. |
| O Token Gerado é Inválido | Client ID/Secret ou certificado incorretos. Revise as credenciais de produção. |
| Não foi localizado o arquivo do Certificado | O .pem selecionado não está em certs/. |
| Invoice #… Já está com o Status PAGO | O Pix já foi pago na Efí. Se a fatura ainda aparece em aberto, verifique o webhook e o log. |
| Erro: 400 / 403 / 404 / 503 … | Recusa da API Efí, com o detalhe na mensagem. Ex.: escopo não habilitado na aplicação ou dados do cliente inválidos. |
Perguntas frequentes
O cliente pagou, mas a fatura continua em aberto. E agora?
Procure [EFI PIX MPAY] no Log de Atividades. Sem nenhum registro, a notificação não chegou: confirme que o WHMCS responde por HTTPS e que firewall, WAF ou Cloudflare não bloqueiam /modules/gateways/efipixmpay/webhook/. Se for urgente, registre o pagamento manualmente com o endToEndId exibido na Efí.
O cliente pode pagar depois do vencimento?
Sim. O Pix continua válido pelo número de dias definido em Tempo de Expiração, com multa e juros, se configurados. Ao abrir uma fatura vencida, o módulo reemite a cobrança com novo vencimento.
Alterei o valor da fatura. O QR Code antigo ainda funciona?
Na próxima abertura da fatura, o módulo atualiza a cobrança na Efí para o novo valor. Peça ao cliente para reabrir a fatura e usar o QR Code exibido.
Posso usar credenciais de homologação para testar?
Não nesta versão: o módulo usa somente o ambiente de produção. Para testar, gere uma fatura de valor baixo e pague com uma conta própria.
Preciso enviar o comprovante para algum lugar?
Não. A confirmação vem diretamente da Efí, e a fatura é baixada sozinha.
Onde peço suporte?
Abra um ticket na Central do Cliente Modules Pay. O WhatsApp (22) 98865-1514 é só para um primeiro contato: problemas técnicos não são resolvidos por lá.
Ainda não instalou?
Siga o passo a passo de instalação e configuração.