MP Modules Pay
Guia de instalação · versão 2.0

Mercado Pago Checkout Pro
para WHMCS

Do envio dos arquivos ao primeiro pagamento confirmado: CPF/CNPJ, credenciais no Mercado Pago Developers, webhooks e configuração do gateway, passo a passo.

⏱ ~20 minutos WHMCS 8 e 9 PHP 7.4+ PIX · Boleto · Cartão
1

Requisitos e checklist

Confira estes itens antes de começar. Eles evitam 90% dos problemas de instalação.

WHMCS
8.0 ou superior

Compatível com o WHMCS 9 e suas faturas imutáveis.

PHP
7.4 ou superior

Com a extensão cURL habilitada.

HTTPS
SSL válido

O Mercado Pago só envia webhooks para endereços HTTPS.

Licença
Modules Pay

Chave de licença ativa para o domínio do WHMCS.

Antes de instalar

2

Envio dos arquivos

Copie as pastas do pacote para a raiz do WHMCS, mantendo exatamente a mesma estrutura.

seu-whmcs/ ├── includes/hooks/ │ └── mpcheckoutprompay.php # cobrança automática, e-mails, cancelamento └── modules/ ├── gateways/ │ ├── mpcheckoutprompay.php # gateway │ ├── callback/mpcheckoutprompay.php # webhook │ └── mpcheckoutprompay/ # funções, logo, licença └── addons/ └── mpcheckoutpromonitor/ # auditoria e logs
  1. Envie as pastas por FTP/SFTP ou pelo gerenciador de arquivos da hospedagem, mesclando com as pastas existentes (não substitua a pasta modules inteira).
  2. Dê permissão de escrita à pasta modules/gateways/mpcheckoutprompay/. O módulo grava ali o arquivo license.txt com o cache da licença.
  3. Não é preciso criar tabelas manualmente: elas são criadas na primeira vez que você abre a configuração do gateway.
3

Campo personalizado CPF/CNPJ

O Mercado Pago exige o documento do pagador para gerar boleto e, em muitos casos, PIX.

O WHMCS não tem um campo nativo de CPF/CNPJ. Por isso, o módulo lê o documento de um campo personalizado de cliente. Se a sua instalação já tem esse campo, pule para o passo 4.

  1. No painel admin, abra Configurações › Configurações do Sistema › Campos Personalizados do Cliente (em inglês: System Settings › Custom Client Fields).
  2. Crie um novo campo com os valores da tabela abaixo e salve.
  3. Se você já tem clientes cadastrados, peça que preencham o CPF/CNPJ na área do cliente (ou preencha pelo perfil do cliente no admin).
  4. Na configuração do gateway (etapa 7), selecione este campo em Campo CPF/CNPJ.
OpçãoValor recomendado
Nome do campoCPF/CNPJ
TipoText Box (caixa de texto)
Campo obrigatórioMarcado — garante que todo novo cliente informe o documento
Mostrar no formulário de pedidoMarcado — o cliente preenche durante o checkout
Somente adminDesmarcado
Validação (opcional)/^(\d{3}\.?\d{3}\.?\d{3}-?\d{2}|\d{2}\.?\d{3}\.?\d{3}\/?\d{4}-?\d{2})$/
i

Pode digitar com ou sem pontuação. O módulo remove pontos, traços e barras automaticamente. Com 11 dígitos o documento é enviado como CPF; com 14 dígitos, como CNPJ. Documentos com outra quantidade de dígitos não são enviados.

!

Use um campo de cliente, não de produto. A lista do gateway mostra todos os campos personalizados do WHMCS; escolher um campo de produto faz o documento nunca ser encontrado.

4

Criar a aplicação no Mercado Pago Developers

A aplicação é o “cadastro” da sua integração. É dela que saem as credenciais e a configuração de webhooks.

  1. Entre em mercadopago.com.br/developers/panel/app com a conta Mercado Pago que vai receber os pagamentos.
  2. Clique em Criar aplicação e dê um nome reconhecível, por exemplo WHMCS — Minha Empresa.
  3. Quando perguntado sobre o tipo de solução, escolha Pagamentos online. Se perguntado sobre plataforma de e-commerce, responda Não.
  4. Em produto a integrar, selecione Checkout Pro.
  5. Aceite os termos e confirme. A aplicação aparece em Suas integrações.
i

O Mercado Pago muda os nomes das telas de tempos em tempos. Se algum texto estiver diferente, procure pelo equivalente: o importante é que a aplicação seja de pagamentos online com Checkout Pro.

5

Credenciais de teste e de produção

São quatro chaves. O módulo precisa de todas, do mesmo ambiente.

  1. Abra a aplicação criada. No menu lateral há Credenciais de teste e Credenciais de produção.
  2. Para usar em produção, abra Credenciais de produção. Na primeira vez, o Mercado Pago pede para ativar as credenciais informando o ramo de atividade e o site da empresa. Informe o endereço do seu WHMCS.
  3. Copie os quatro valores para um local seguro. Eles vão para a configuração do gateway na etapa 7.
CredencialFormatoUso
Public KeyAPP_USR-xxxx…Identifica a aplicação no navegador do cliente.
Access TokenAPP_USR-xxxx…Chave privada usada para criar cobranças. Nunca compartilhe.
Client IDnúmeroIdentificador da aplicação.
Client SecrettextoUsado para renovar o token automaticamente.
!

Não misture ambientes. Credenciais de teste geram cobranças fictícias que nunca caem na sua conta. Antes de liberar para clientes, confirme que as quatro chaves são de produção.

!

Se o Access Token vazar, gere um novo na mesma tela (Renovar) e atualize o gateway imediatamente.

6

Webhooks (confirmação automática)

É o webhook que avisa o WHMCS quando o cliente paga. Sem ele, as faturas não são baixadas sozinhas.

https://www.seusite.com.br/whmcs/modules/gateways/callback/mpcheckoutprompay.php
  1. Na aplicação do Mercado Pago, abra Webhooks › Configurar notificações.
  2. Em Modo produção, cole a URL acima. Se for testar antes, cole a mesma URL em Modo teste.
  3. Em Eventos, marque Pagamentos.
  4. Salve. O Mercado Pago gera uma assinatura secreta (chave secreta). Copie-a: ela vai no campo Webhook Secret do gateway.
  5. Opcional: use o botão Simular notificação para conferir se a URL responde com sucesso (HTTP 200).
✓

Por que preencher o Webhook Secret? Com ele, o módulo confere a assinatura de cada notificação e recusa avisos falsificados. Além disso, cada pagamento é sempre consultado de novo na API do Mercado Pago antes de baixar a fatura.

!

Se o WHMCS estiver atrás de proteção como Cloudflare “Under Attack”, senha de diretório ou bloqueio por país, libere o caminho /modules/gateways/callback/, ou os avisos do Mercado Pago serão barrados.

7

Ativar e configurar o gateway

Agora junte tudo no WHMCS.

  1. Abra Configurações › Configurações do Sistema › Gateways de Pagamento.
  2. Na aba Todos os gateways, clique em Mercado Pago Checkout Pro para ativar.
  3. Preencha os campos conforme a tabela e clique em Salvar alterações.
  4. Volte à página e confira o quadro da licença no topo: deve aparecer “Licença está ativa”.
i

O topo da página mostra a versão instalada, se há atualização disponível (com botão de download) e, abaixo, a URL de callback pronta para copiar. Use ponto como separador decimal nos campos de valor (1.99, não 1,99).

Campo por campo

01

Nome de exibição

Opcional

Nome que o cliente vê na lista de formas de pagamento do checkout e da fatura. Padrão do WHMCS: Mercado Pago Checkout Pro. Pode trocar por algo como PIX, Boleto ou Cartão (Mercado Pago).

02

Nome Usuário do WHMCS

Obrigatório

Nome de usuário (login) de um administrador ativo. O módulo usa esse usuário nas chamadas internas da API do WHMCS para consultar faturas e lançar os pagamentos confirmados.

Se ficar em branco ou inválido: o módulo usa o primeiro administrador ativo e grava um aviso resolve_admin no log. Recomendado: um admin dedicado, ex.: api-mercadopago.

03

Campo CPF/CNPJ

Obrigatório

Lista com os campos personalizados do WHMCS. Selecione o campo de cliente criado na etapa 3. O valor é enviado ao Mercado Pago como CPF (11 dígitos) ou CNPJ (14 dígitos).

Se o cliente não tiver documento: o boleto e, em geral, o PIX não podem ser gerados; o módulo tenta o Checkout Pro como alternativa.

04

Chave de Licença

Obrigatório

Chave enviada pela Modules Pay na compra. Logo abaixo do campo aparece o status: ativa, inválida, expirada ou suspensa.

Sem licença ativa: a fatura mostra “No momento não é possível utilizar esta forma de pagamento” e nenhuma cobrança automática é criada.

05

Chave Pública (public_key)

Obrigatório

Public Key da aplicação, copiada em Credenciais de produção (etapa 5). Começa com APP_USR-.

06

Access Token

Obrigatório

Chave privada que autoriza o módulo a criar PIX, boletos e links de pagamento na sua conta. Começa com APP_USR- (produção) ou TEST- (teste).

Atenção: é a credencial mais sensível. O WHMCS guarda os campos do gateway criptografados no banco.

07

Client ID

Obrigatório

Identificador numérico da aplicação, na mesma tela das credenciais.

08

Client Secret

Obrigatório

Senha da aplicação. Junto com o Client ID, permite ao módulo obter um token válido automaticamente (OAuth) caso o Access Token informado não esteja no formato esperado. O token obtido fica em cache e é renovado sozinho.

09

Taxa Fixa

Opcional

Valor em reais somado ao total da fatura no momento da cobrança no Mercado Pago, para repassar o custo do meio de pagamento. Ex.: 1.99.

Exemplo: fatura de R$ 100,00 + taxa fixa 1.99 → cliente paga R$ 101,99. Se a Taxa Fixa e a Taxa % estiverem preenchidas, vale a Taxa Fixa.

10

Taxa %

Opcional

Percentual somado ao total da fatura. Ex.: 4.5 para 4,5%.

Exemplo: fatura de R$ 100,00 + 4.5% → cliente paga R$ 104,50. A taxa aparece discriminada no quadro de pagamento da fatura. Quando o pagamento é confirmado, a diferença é registrada na fatura (como item de ajuste ou, no WHMCS 9, como tarifa da transação).

11

Meios Pagamentos a ser excluídos

Opcional

Códigos dos meios que não devem ser oferecidos, separados por vírgula: 1 Boleto, 2 PIX, 3 Cartão Crédito, 4 Cartão Débito, 5 Pré-pago. Em branco = todos liberados.

Afeta a tela da fatura: o PIX/boleto em destaque, o texto e as bandeiras do botão. Veja os exemplos na etapa 8.

12

Número Máximo de Parcelas

Opcional

Limite de parcelas no cartão de crédito, de 1 a 12. Com 1, apenas à vista. Os juros do parcelamento seguem as condições da sua conta Mercado Pago.

13

Forma de Pagamento Default

Opcional

Pix ou Boleto. O módulo gera esse pagamento automaticamente e o exibe em destaque na fatura (código PIX copia e cola ou linha digitável) e nos e-mails. Os demais meios ficam no botão do Mercado Pago.

Se o meio escolhido estiver excluído no campo 11, nada é gerado em destaque e o cliente paga pelo botão.

14

Valor Mínimo

Opcional

Faturas com total abaixo deste valor não são cobradas pelo Mercado Pago (útil para evitar tarifas em valores muito baixos). Ex.: 5.00. Em branco = qualquer valor.

O cliente vê: uma mensagem pedindo outra forma de pagamento.

15

Webhook Secret

Recomendado

Assinatura secreta gerada pelo Mercado Pago ao salvar os webhooks (etapa 6). Com ela, o módulo confere a assinatura de cada notificação e recusa avisos falsificados.

Em branco: os webhooks continuam funcionando, mas sem a verificação de assinatura, e um aviso é registrado no log de atividades do WHMCS.

16

Converter para / moeda

WHMCS

Opção padrão do WHMCS. O Mercado Pago cobra em reais (BRL); se a sua moeda padrão for outra, configure a conversão para BRL.

8

Escolhendo os meios de pagamento

O campo “Meios Pagamentos a ser excluídos” define o que o seu cliente vê na fatura.

Código 1
Boleto
Código 2
PIX
Código 3
Cartão Crédito
Código 4
Cartão Débito
Código 5
Pré-pago

Exemplos com “Forma de Pagamento Default” = Pix

ExcluídosEm destaqueAbaixo, no botão Mercado Pago
vazioPIX“Para Boleto, Cartão Crédito e Cartão Débito pague direto no”
4PIX“Para Boleto e Cartão Crédito pague direto no”
1PIX“Para Cartão Crédito e Cartão Débito pague direto no”
1,3,4PIXBotão oculto: só restaria o PIX, que já está em destaque.
2—Sem PIX em destaque; o botão mostra apenas os meios liberados.
i

A mudança vale para as próximas cobranças geradas. Pagamentos já criados para uma fatura continuam disponíveis para o cliente.

9

Ativar o addon de auditoria

Painel para acompanhar cobranças, reprocessar falhas e consultar os logs.

  1. Abra Configurações › Configurações do Sistema › Módulos Addon.
  2. Ative Mercado Pago Checkout Pro — Auditoria.
  3. Clique em Configurar e, em Controle de acesso, marque os grupos de administradores que podem usar o painel. Salve.
  4. O painel fica em Addons › Mercado Pago Checkout Pro — Auditoria.

O que o addon oferece

Auditoria
Reconciliação

Cruza cada fatura do WHMCS com a cobrança no Mercado Pago e aponta divergências.

Ações
Reprocessar

Recria cobranças que falharam, uma a uma ou todas de uma vez.

Logs
Histórico

Cada evento do módulo com os dados técnicos, filtros e exclusão por período.

Manutenção
Automática

Logs com mais de 90 dias são apagados pelo cron diário do WHMCS.

i

O addon não tem campos de configuração: basta ativá-lo e liberar o acesso. O uso de cada tela, indicador e botão está explicado no Guia de utilização.

10

Teste final

Um pagamento real de valor baixo confirma que tudo está ligado.

✓

Tudo certo? O módulo está pronto. Veja o Guia de utilização para e-mails, auditoria e rotina do dia a dia.

11

Atualizando de uma versão anterior

Na versão 2.0 o addon mudou de nome. Siga esta ordem.

  1. Faça backup dos arquivos e do banco.
  2. Em Módulos Addon, desative o addon antigo do Mercado Pago.
  3. No servidor, apague a pasta modules/addons/mpcheckoutprompay/.
  4. Envie os arquivos novos (etapa 2), substituindo os do gateway e do hook.
  5. Ative o addon novo e marque de novo o controle de acesso (etapa 9).
  6. Abra a configuração do gateway, confira os campos e preencha o novo Webhook Secret.
!

Não deixe as duas pastas de addon no servidor. A pasta antiga tem funções com o mesmo nome do gateway e pode causar erro fatal no painel.

i

As tabelas mod_mpcheckoutprompay e mod_mpcheckoutprompay_logs são preservadas: nenhum histórico é perdido.

12

Problemas comuns na instalação

Clique para ver a solução.

A configuração do gateway mostra “Licença inválida”

Confira a chave e se ela foi emitida para o mesmo domínio do WHMCS. Verifique também se o servidor consegue acessar painel.modulespay.com.br (firewall de saída) e se a pasta modules/gateways/mpcheckoutprompay/ tem permissão de escrita.

A fatura mostra “Não foi possível gerar o link de pagamento”

Normalmente é credencial errada ou de outro ambiente. Abra o addon de auditoria, aba Logs, e procure erros preference_created ou payment_created: o detalhe mostra a resposta do Mercado Pago.

O boleto ou PIX não é gerado, só o botão do Mercado Pago

Verifique se o cliente tem CPF/CNPJ preenchido no campo correto e se o meio não está na lista de excluídos. Quando o pagamento direto falha, o módulo usa o Checkout Pro como alternativa e registra um aviso no log.

O cliente pagou mas a fatura continua em aberto

O webhook não chegou ou foi recusado. Confira a URL da etapa 6, o evento Pagamentos, o Webhook Secret e se nada bloqueia /modules/gateways/callback/. No addon, essas faturas aparecem como Pago no MP.

Erro fatal “Cannot redeclare mpcheckoutprompay_config()”

A pasta antiga modules/addons/mpcheckoutprompay/ ainda está no servidor. Apague-a (etapa 11).