IFthenpay Gateway para Perfex CRM: Pagamentos Portugueses Nativos, do “Emitir” ao “Pago”

Autor: Rodrigo Soares — DriveWeb
Categoria: Perfex CRM · Módulos · Pagamentos
Publicado: Fevereiro de 2026
Tempo de leitura: ~12 minutos

O problema que ninguém quer ter de explicar ao cliente

O Perfex CRM é uma plataforma forte para gestão de clientes, propostas e faturação. O ponto fraco, para quem opera em Portugal, aparece no momento mais sensível do ciclo de receita: o pagamento.

Na prática, muitas equipas acabam presas a um fluxo desconfortável: fatura enviada, cliente pede referência por mensagem, alguém responde manualmente, depois confirma no extrato, e só então atualiza o estado no CRM. Resultado: atrasos, reconciliação manual, falhas humanas e aquele clássico “já paguei” sem prova imediata.

Foi para cortar esse atrito que nasceu o IFthenpay Gateway: um módulo que integra Multibanco, MB WAY e Payshop (e, opcionalmente, métodos adicionais via Gateway Key) diretamente no Perfex, usando a API oficial da Ifthenpay.

O que é o IFthenpay Gateway (e o que ele resolve na vida real)

O IFthenpay Gateway é um módulo para o Perfex CRM que permite:

• Gerar referências Multibanco por fatura (dinâmicas via API ou offline por algoritmo, conforme configuração).

• Pedir pagamento por MB WAY com confirmação (e experiência de utilizador pensada para não “emperrar”).

• Gerar referência Payshop para pagamento em agentes/CTT.

• Disponibilizar métodos extra (cartões, Google Pay, Apple Pay, PIX, débitos diretos) via Gateway Key PINPAY, quando contratado.

• Receber callbacks (webhooks) automáticos: assim que o cliente paga, a fatura é marcada como paga no Perfex.

• Manter registos de auditoria: transações + logs de callbacks para diagnóstico e rastreabilidade.

O objetivo é simples: transformar o pagamento numa etapa automática, e não num mini-projeto de suporte.

Métodos de pagamento suportados (visão prática)

Nesta versão, o módulo cobre:

• Multibanco (API dinâmica e opção offline)

• MB WAY

• Payshop

• Gateway PINPAY (cartões e variantes, consoante contrato)

Um detalhe importante: Multibanco / MB WAY / Payshop funcionam com as suas próprias chaves. A Gateway Key é para o pacote adicional (cartões, wallets e afins).

Como funciona o fluxo (do clique ao recibo)

O fluxo foi desenhado para ser “óbvio” para o cliente e “auditável” para o admin:

1) Emissão normal da fatura

O utilizador cria a fatura como sempre. O gateway surge como opção de pagamento na página pública da fatura.

2) Página de seleção de método

Ao clicar em “Pagar agora”, o cliente vê um selector limpo com os métodos ativos apenas se estiverem configurados (evita botões mortos). Pode operar em modo white-label.

3) Pagamento conforme o método

• Multibanco: mostra Entidade/Referência/Valor + ações de copiar + validade.

• MB WAY: valida telemóvel, dispara pedido e apresenta estado (com controlo de tempo e verificação).

• Payshop: gera referência e instruções objetivas.

• Gateway PINPAY: encaminha para o checkout hosted, quando aplicável.

4) Confirmação automática no Perfex

Quando a Ifthenpay confirma o pagamento, o módulo:

• valida segurança do callback,

• confirma valores,

• marca a fatura como paga,

• regista log e escreve nota interna na fatura.

Sem “liga-me quando pagares”.

Segurança a sério (sem teatro)

Aqui é onde muitos módulos falham: funcionam… até ao dia em que alguém tenta abusar do endpoint.

O módulo implementa medidas práticas e verificáveis:

• Chave anti-phishing validada com comparação timing-safe (hash_equals).

• Whitelist de IPs (configurável) para reduzir superfície de ataque.

• Rate limiting por IP para travar abuso.

• HTTPS obrigatório no endpoint.

• Validação de valor em cêntimos (inteiros) para evitar erros de arredondamento.

• Idempotência: callbacks duplicados não geram pagamentos duplicados.

• Sanitização de inputs antes de qualquer uso.

• Resposta 404 em tentativas inválidas para não “anunciar” o endpoint.

A filosofia é simples: um webhook é uma porta de entrada — trata-se como tal.

Arquitetura: encaixa no Perfex sem dependências

O módulo segue a base do Perfex (PHP/CodeIgniter) e evita “peso morto”:

• Sem Composer

• Sem SDK externo

• Compatível com alojamentos comuns (incluindo partilhados), desde que o Perfex já corra bem

Estrutura típica: bootstrap do módulo, controllers para callback/pagamentos/admin, views para o fluxo do cliente, migrations para as tabelas.

Base de dados e auditoria (para quando algo não bate certo)

O ponto mais subestimado em integrações de pagamento é o diagnóstico.

O módulo mantém:

• Transações: método, referência, valor, estado (pendente/pago/expirado), timestamps.

• Logs de callback: IP, resultado, payload, motivo de rejeição (ex.: chave inválida, mismatch de valor, IP bloqueado).

Quando o cliente diz “paguei” e a fatura não muda, o admin não fica a adivinhar: vai ao log e vê o motivo exato.

Integração com contratos (o “pipeline completo”)

Para quem usa contratos no Perfex, o encaixe é natural:

1. contrato enviado →

2. aceite registado →

3. fatura criada automaticamente →

4. cliente paga no selector →

5. callback confirma e fecha o ciclo.

Isto transforma “proposta → pagamento” numa linha contínua, sem saltos manuais.

Instalação em 5 minutos (sem drama)

Fluxo típico:

1. Setup → Modules → Upload

2. Install → Activate

3. Upgrade Database (migrations)

4. Setup → Settings → Payment Gateways → IFthenpay → inserir chaves

5. Configurar callback URL no backoffice da IFthenpay (por método)

A chave anti-phishing é gerada automaticamente e fica visível nas definições do módulo.

Perguntas frequentes (as que realmente aparecem)

Funciona sem Gateway Key?
Sim. Multibanco/MB WAY/Payshop não dependem de Gateway Key.

E se o callback vier duas vezes?
Não duplica. O módulo é idempotente: se já está pago, responde OK e segue.

Como testar sem pagamentos reais?
Modo “test/sandbox” quando disponível (e comportamento controlado por configuração).

Compatível com hosting partilhado?
Sim, desde que o Perfex esteja estável e o servidor cumpra os mínimos de PHP/MySQL exigidos pelo próprio Perfex.

Resultados em produção (o que interessa)

Em ambiente real, o impacto é direto:

• menos mensagens “manda referência”

• menos reconciliação manual

• menos erros humanos

• mais velocidade a transformar faturas em dinheiro

E, sobretudo: o Perfex passa a comportar-se como software de faturação “português”, não apenas “genérico”.

Conclusão

O IFthenpay Gateway para Perfex CRM resolve um problema concreto: pagamentos portugueses nativos, automatizados e auditáveis, com uma implementação focada em segurança e diagnóstico.

Para quem usa o Perfex CRM para cobrar clientes em Portugal, isto tira o pagamento do modo “manual e frágil” e coloca-o no modo “industrial e rastreável”.

Sobre o autor

Rodrigo Soares é fundador da DriveWeb, focada em desenvolvimento web, módulos para Perfex CRM, integrações com gateways e soluções WordPress para o mercado ibérico.

Site: driveweb.pt
E-mail: contacto@driveweb.com.br
WhatsApp: +351 913 671 493