Reprocessar
Disponível em Sem cobrança e Erro. Apaga o registro de erro e tenta criar a cobrança de novo. Se falhar, mostra o código HTTP e a mensagem do Mercado Pago.
1
Como funciona
Da fatura emitida à fatura paga, sem intervenção manual.
🧾Fatura criadapelo pedido ou pelo cron do WHMCS
⚡Cobrança no MPPIX/boleto e link do Checkout Pro
✉️Cliente recebena fatura e no e-mail
💳Cliente pagaPIX, boleto ou cartão
🔔WebhookMercado Pago avisa o WHMCS
✅Fatura pagaserviço liberado/renovado
Cada cobrança fica registrada na tabela mod_mpcheckoutprompay e cada evento é gravado nos logs do addon. Se algo falhar no caminho, o painel de auditoria mostra onde.
2
O que o cliente vê na fatura
O quadro do Mercado Pago aparece na fatura (área do cliente) quando a forma de pagamento é o Mercado Pago Checkout Pro.
Partes do quadro
- Resumo de valores: valor da fatura, taxa configurada e total a pagar.
- Pagamento em destaque: conforme a Forma de Pagamento Default. PIX mostra o copia e cola, com botão de copiar e link para o QR Code; boleto mostra a linha digitável e o botão Abrir Boleto.
- Texto e bandeiras: listam só os meios liberados que não estão em destaque, respeitando os Meios excluídos.
- Botão Mercado Pago: abre o Checkout Pro, onde o cliente escolhe boleto, cartão (com parcelas) etc. Ao pagar, volta para a fatura.
i
Se a licença estiver inativa, a fatura estiver abaixo do Valor Mínimo ou o Mercado Pago recusar a criação, o quadro mostra um aviso amarelo no lugar dos botões.
3
Quando a cobrança é gerada
O módulo cria a cobrança uma única vez por fatura, no primeiro destes momentos que acontecer.
| Momento | O que acontece |
|---|---|
| Fatura gerada pelo cron | A cobrança é criada logo após a geração, antes do e-mail Invoice Created. |
| Envio de e-mail de fatura | Antes de enviar qualquer e-mail de fatura (criação, lembrete, atraso), o módulo garante que a cobrança existe para preencher os campos do e-mail. |
| Lembrete de pagamento | Se a fatura ainda não tem cobrança, ela é criada. |
| Cliente abre a fatura | Se ainda não houver PIX/boleto ou link do Checkout Pro, eles são criados na hora. |
Condições para gerar: fatura com forma de pagamento Mercado Pago Checkout Pro, situação Em aberto ou Cobrança, licença ativa e total igual ou acima do Valor Mínimo.
✓
Sem duplicidade: uma trava por fatura impede que dois processos simultâneos criem duas cobranças, e o Mercado Pago recebe uma chave de idempotência por fatura.
i
As cobranças expiram no Mercado Pago 10 dias após serem criadas.
4
Taxas, parcelas e valor mínimo
Como a configuração do gateway muda o valor cobrado.
Taxa fixa 1.99
R$ 100 → R$ 101,99
Somada ao total. Prevalece se a Taxa % também estiver preenchida.
Taxa 4.5%
R$ 100 → R$ 104,50
Percentual sobre o total da fatura.
Parcelas 6
até 6x no cartão
Juros conforme sua conta Mercado Pago.
Mínimo 5.00
R$ 4,90 → não cobra
O cliente é orientado a usar outra forma.
O que acontece com a taxa quando o pagamento entra
- WHMCS 8: o módulo adiciona à fatura o item “Mercado Pago: Taxas ou juros e multas por atraso” com a diferença e lança o pagamento integral.
- WHMCS 9: faturas em aberto não aceitam novos itens. O módulo lança como pagamento o saldo da fatura e registra a diferença como tarifa (fees) da transação, sem gerar crédito para o cliente. Um aviso
invoice_adjustfica no log. - Se o cliente pagar menos (desconto do Mercado Pago), o módulo tenta adicionar um item de desconto; se não for possível, a fatura fica parcialmente paga.
5
Dados de pagamento nos e-mails
Leve o botão, o PIX e a linha digitável direto para a caixa de entrada do cliente.
- Abra Configurações › Configurações do Sistema › Modelos de E-mail.
- Edite os modelos de fatura que desejar: Invoice Created, Invoice Payment Reminder e os de atraso (First/Second/Third Invoice Overdue Notice).
- Insira os campos abaixo onde quiser que apareçam. Eles também aparecem na lista de campos de mesclagem do editor.
| Campo | Conteúdo |
|---|---|
{$mpcheckoutprompay_payment_link} | Quadro com o botão Pagar com Mercado Pago. |
{$mpcheckoutprompay_qr_code} | Código PIX copia e cola (quando a cobrança é PIX). |
{$mpcheckoutprompay_digitable_line} | Linha digitável (quando a cobrança é boleto). |
Exemplo de trecho para o modelo
<p>Sua fatura #{$invoice_num} no valor de {$invoice_total} vence em {$invoice_date_due}.</p>
{$mpcheckoutprompay_payment_link}
{$mpcheckoutprompay_qr_code}
{$mpcheckoutprompay_digitable_line}
<p>Ou acesse: {$invoice_link}</p>
i
Campos sem conteúdo ficam vazios no e-mail; por isso é seguro incluir os três. Em faturas de outros gateways, nada é exibido.
6
Confirmação do pagamento
A baixa é automática, via webhook.
- O cliente paga. O Mercado Pago envia uma notificação ao WHMCS.
- O módulo confere a assinatura (se o Webhook Secret estiver configurado) e consulta o pagamento na API do Mercado Pago. Nunca confia só no conteúdo da notificação.
- Atualiza a situação da cobrança (pendente, aprovado, rejeitado…).
- Se aprovado e a fatura estiver em aberto, lança o pagamento com o ID do Mercado Pago como número da transação. A fatura fica Paga e o WHMCS segue o fluxo normal (ativação, renovação, e-mail de confirmação).
PIX
Segundos
Confirmação quase imediata.
Cartão
Minutos
Aprovado na hora ou após análise.
Boleto
1 a 3 dias úteis
Depende da compensação bancária.
✓
Sem baixa em dobro: se o Mercado Pago reenviar a mesma notificação, o módulo reconhece que a transação já foi lançada e não lança de novo.
7
Cancelamento e estorno
Ao cancelar uma fatura no WHMCS, o módulo tenta cancelar a cobrança no Mercado Pago.
| Tipo de cobrança | Cancela no Mercado Pago? | Observação |
|---|---|---|
| PIX/Boleto pendente | Sim | Cancelado automaticamente pela API. |
| PIX/Boleto já pago | Não | Faça o estorno manualmente no painel do Mercado Pago. |
| Link do Checkout Pro | Não | O Mercado Pago não permite cancelar; o link expira em 10 dias. |
| Cobrança com erro | — | Nada foi criado no Mercado Pago. |
!
Cancelar a fatura não devolve dinheiro. Reembolsos são feitos sempre pelo painel do Mercado Pago. Se um cliente pagar por um link antigo de uma fatura já cancelada, o pagamento não é lançado no WHMCS e deve ser estornado manualmente.
8
Addon: painel de Auditoria
Addons › Mercado Pago Checkout Pro — Auditoria. Cruza as faturas do WHMCS com as cobranças no Mercado Pago.
Indicadores (cartões do topo)
Cada fatura com forma de pagamento Mercado Pago entra em uma única situação. Clique no cartão para filtrar a lista.
| Situação | Significado | O que fazer |
|---|---|---|
| OK | Fatura paga no WHMCS, com cobrança registrada. | Nada. |
| Aguardando pagamento | Cobrança criada; o cliente ainda não pagou. | Nada. Se a cobrança for um link do Checkout Pro antigo, você pode usar Limpar e depois Reprocessar. |
| Sem cobrança no MP | A fatura não tem nenhuma cobrança registrada. | Use Reprocessar. Faturas antigas, de antes da instalação, costumam cair aqui. |
| Pago no MP ↔ Divergência | O Mercado Pago aprovou, mas a fatura segue em aberto no WHMCS. | Prioridade. Verifique o webhook (o painel mostra a URL). Confirme no Mercado Pago e lance o pagamento manualmente na fatura, se necessário. |
| Erro na criação | O Mercado Pago recusou a criação da cobrança. | Veja o motivo nos logs, corrija (CPF, credenciais…) e use Reprocessar. |
| Cancelado | Fatura cancelada no WHMCS. | Nada. |
Filtros
- Status: mesma lista de situações dos cartões.
- De / Até: período pela data de emissão da fatura. Os cartões também respeitam esse período.
- Limpar: remove todos os filtros.
Colunas da tabela
| Coluna | Conteúdo |
|---|---|
| Fatura | Número, com link para a fatura no admin. |
| Emissão / Vencimento | Datas da fatura. |
| Cliente | Nome (link para o perfil) e e-mail. |
| Valor | Total no WHMCS. Se o valor cobrado no Mercado Pago for diferente (taxas), aparece abaixo como “MP: R$ …”. |
| WHMCS | Situação da fatura: Pago, Em aberto, Cancelado, Reembolsado, Cobrança. |
| Tipo MP | PIX Boleto Checkout Pro — o tipo de cobrança criada. |
| ID Mercado Pago | Identificador da cobrança no Mercado Pago e ícone para abrir o link de pagamento (oculto em faturas canceladas). |
| Status MP | Situação no Mercado Pago: Criado, Pendente, Em processo, Aprovado, Rejeitado, Cancelado, Reembolsado, Estorno. |
| Auditoria | A situação conciliada (tabela acima). |
| Ações | Botões disponíveis para aquela fatura. |
Ações
Reprocessar todos pendentes
Aparece no topo quando há faturas em aberto sem cobrança ou com erro. Processa todas e informa quantas deram certo e quantas falharam. Pode levar alguns segundos.
Excluir erro
Disponível em Erro. Remove apenas o registro de erro, sem criar nada; a fatura passa a Sem cobrança.
Limpar
Disponível em Aguardando quando a cobrança é um link do Checkout Pro. Remove o registro local para permitir uma nova cobrança (por exemplo, PIX/boleto após mudar a configuração). O link antigo continua válido no Mercado Pago até expirar.
!
Quando existe alguma divergência, um alerta no rodapé do painel mostra a URL de webhook que deve estar cadastrada no Mercado Pago.
9
Addon: Logs
No painel de auditoria, clique em Ver Logs. Cada passo do módulo fica registrado aqui.
Tipos
Success
Operação concluída: cobrança criada, pagamento recebido.
Error
Falha que impediu a operação. Exige atenção.
Warning
Algo saiu do esperado, mas o módulo contornou.
Info
Registro informativo, como tentativas e reprocessamentos.
Como usar a tela
- Filtros: tipo, ação, número da fatura e período. Para investigar uma fatura, digite o número em Fatura.
- Ver dados: abre uma janela com os detalhes técnicos do evento (resposta do Mercado Pago, código HTTP, valores) em formato legível, com opção de ver o JSON bruto. Útil para enviar ao suporte.
- Deletar intervalo: apaga os logs entre duas datas (pode deixar um dos lados em branco).
- Deletar todos os logs: apaga tudo. Irreversível.
- Limpeza automática: logs com mais de 90 dias são removidos todo dia pelo cron do WHMCS.
Glossário de ações
| Ação | Quando aparece |
|---|---|
payment_created | PIX ou boleto criado (success) ou falha ao criar, com uso do Checkout Pro como alternativa (warning). |
preference_attempt | Tentativa de criar o link do Checkout Pro. |
preference_created | Link do Checkout Pro criado (success) ou recusado (error, com a resposta do Mercado Pago). |
create_charge | Erro inesperado ao criar a cobrança (fatura ou cliente não encontrado, exceção). |
license_error | Licença inativa bloqueou a cobrança automática. |
payment_received | Pagamento aprovado e lançado na fatura. |
invoice_adjust | Não foi possível ajustar a fatura com a taxa/desconto (WHMCS 9); o pagamento foi lançado mesmo assim. |
invoice_cancelled | Resultado do cancelamento da cobrança ao cancelar a fatura. |
reprocess | Reprocessamento manual pelo painel de auditoria. |
resolve_admin | O usuário admin configurado não existe ou está inativo; outro admin foi usado. |
log_cleanup / cron_cleanup | Limpeza manual ou automática dos logs. |
10
Rotina recomendada
Alguns minutos por semana mantêm tudo conciliado.
Diariamente
Pago no MP
Este cartão deve estar sempre em zero. Qualquer número aqui é cliente que pagou e não foi baixado.
Semanalmente
Erro e Sem cobrança
Corrija a causa e use Reprocessar todos pendentes.
Mensalmente
Logs de erro
Filtre por Error e procure padrões (CPF faltando, credencial expirada).
11
Perguntas frequentes
Clique para ver a resposta.
O cliente pagou, mas a fatura não foi baixada
Na auditoria a fatura aparece como Pago no MP. Confira a URL de webhook no Mercado Pago, o evento Pagamentos e o Webhook Secret. Depois de corrigir, lance o pagamento manualmente na fatura usando o ID do Mercado Pago como número da transação.
Mudei os meios excluídos, mas a fatura continua mostrando o PIX
A regra vale para as próximas cobranças. O PIX já gerado para aquela fatura continua disponível. Para gerar de novo com a regra nova, cancele a fatura e emita outra.
Por que a fatura ficou com um pagamento menor que o valor pago pelo cliente?
No WHMCS 9, quando há taxa configurada, o módulo lança apenas o saldo da fatura e registra a diferença como tarifa da transação. Isso evita crédito indevido na conta do cliente. Veja o aviso invoice_adjust nos logs.
A cobrança deu erro “identification” ou “payer”
O CPF/CNPJ do cliente está vazio ou com quantidade errada de dígitos. Corrija no perfil do cliente e use Reprocessar.
Posso emitir uma nova cobrança para a mesma fatura?
Se a cobrança atual for um link do Checkout Pro, use Limpar e depois Reprocessar. PIX e boleto já emitidos permanecem vinculados à fatura.
Como reembolsar um cliente?
Pelo painel do Mercado Pago, em Atividade, abrindo o pagamento e escolhendo Devolver. Depois registre o reembolso na fatura do WHMCS.
i
Precisa de ajuda? Envie o número da fatura e o conteúdo de Ver dados do log para contato@modulespay.com.br. Instalação e configuração: Guia de instalação.