Como configurar pagamentos com Banco Efí (PIX, Boleto e Cartão)

O Módulo Oficial da Efí para WHMCS (Versão 2.3) permite receber pagamentos via PIX, Boleto Bancário, Cartão de Crédito e Open Finance através de checkout transparente. Assim que o pagamento é confirmado, a Efí envia uma notificação automática via Webhook para dar baixa na fatura do cliente no WHMCS.

Requisitos do Sistema

Para garantir a compatibilidade e a estabilidade da integração, certifique-se de que o seu servidor atende aos seguintes requisitos:

• Versão do PHP: 8.1
• Versão do WHMCS: 8.9.x

Passo 1: Instalação dos Arquivos e Permissões

1. Baixe o pacote oficial do módulo Efí e descompacte o arquivo.
2. Copie o arquivo efi.php e a pasta efi/ para o diretório /modules/gateways/ do seu WHMCS.
3. Copie o arquivo efi.php e a pasta efi/ contidos na pasta callback para o diretório /modules/gateways/callback/.
4. Copie o arquivo efi.php localizado em hooks para a pasta /includes/hooks/.
5. Acesse o servidor via SSH ou Gerenciador de Arquivos e aplique as permissões adequadas:
   • chmod 777 modules/gateways/efi.php
   • chmod 777 modules/gateways/efi/ -R
   • chmod 777 modules/gateways/callback/efi.php
   • chmod 777 modules/gateways/callback/efi/ -R
   • chmod 777 includes/hooks/efi.php
6. Crie uma pasta segura na raiz do seu servidor (fora da pasta pública) e envie o seu certificado PIX no formato PFX (.p12).

Passo 2: Configuração no Painel do WHMCS

No painel administrativo do WHMCS, acesse o menu Opções > Portais Para Pagamentos > Payment Gateways e ative a opção Efí. Preencha os campos conforme as instruções abaixo:

• Client_id e Client_secret (Produção e Desenvolvimento): Copie as credenciais geradas na sua conta Efí no menu API > Minhas Aplicações.
• Identificador de conta: Insira o código localizado no menu API > Identificador de conta do painel Efí.
• Usuário administrador do WHMCS: Digite o nome de usuário exato que você utiliza para logar na administração do WHMCS.
• Chave PIX: Insira a sua chave PIX. Se for CNPJ ou CPF, digite apenas números. Se for telefone, utilize o padrão internacional (Ex: +5531988887777).
• Certificado Pix: Informe o caminho absoluto no servidor onde você salvou o arquivo do certificado (Ex: /home/usuario/certificados/producao.p12).
• Métodos de Pagamento Ativos: Marque as caixas de seleção desejadas para liberar as opções de PIX, Boleto, Cartão de Crédito e Open Finance.

Validações e Tratamento de Erros Comuns

O módulo realiza uma pré-validação dos dados informados pelo cliente final antes de emitir a cobrança. Fique atento aos erros frequentes:

• Nome ou Razão Social Inválida: O cliente deve digitar o nome completo ou o nome empresarial cadastrado na Receita Federal no campo Empresa.
• Documento Nulo ou Inválido: O número de CPF ou CNPJ está em branco ou possui dígitos incorretos.
• Erro Inesperado: Geralmente indica falta de preenchimento de algum campo obrigatório nas configurações do módulo ou versão de PHP incompatível no servidor. Ative a opção Debug na tela do módulo para registrar os detalhes da transação.