O que o módulo faz
- Dois botões na fatura: Pay by card / PayPal (4,5%) e Pay with crypto com seletor de moeda (1,5%). Qualquer um pode ser desativado.
- O cliente paga o saldo da fatura, então faturas pagas parcialmente também funcionam.
- O pagamento é lançado com
addInvoicePaymentsó depois que o módulo o relê pela API: pago, com o mesmo valor e moeda. O id do pagamento da UTOPAY vira o id da transação, então um pagamento nunca é lançado duas vezes. - Faturas em uma moeda que a UTOPAY não aceita (por exemplo, RUB) são pagas na moeda de Convert To For Processing; a fatura é creditada na própria moeda.
- Nada é chamado enquanto a fatura é exibida: o pagamento só é criado quando o cliente clica em um botão.
Instalação
- Baixe o ZIP acima e descompacte.
- Envie o conteúdo da pasta
utopay-whmcspara a raiz do WHMCS; a pastamodulesse junta à sua:modules/gateways/utopay.php,modules/gateways/utopay/,modules/gateways/callback/utopay.php. - No painel da UTOPAY abra Integration → API keys e crie uma chave de teste
utopay_sk_test_…. - Admin do WHMCS → System Settings → Payment Gateways → All Payment Gateways → UTOPAY.
- Cole a chave, escolha as opções de pagamento e salve.
- Para cripto: adicione sua carteira EVM no painel (Project settings → Funds & payouts, seção Crypto wallets) e liste as moedas nas configurações do módulo.
Configurações
| Campo | O que faz |
|---|---|
| Secret key | utopay_sk_test_… para o sandbox, utopay_sk_live_… para pagamentos reais. |
| Payment options | Cartão / PayPal e cripto, só cartão ou só cripto. |
| Crypto coins | Tickers separados por vírgula, por exemplo bep20/usdt,erc20/usdt,polygon/usdc. Lista completa: https://api.utopay.app/v1/crypto/coins. |
| Card method | Vazio: o cliente escolhe. Ou envie todos direto para um método (Stripe, PayPal, Revolut…). |
| Convert To For Processing | Opção padrão do WHMCS: a moeda em que o pagamento é feito quando a moeda da fatura não é suportada. |
Pagamento de teste
- Com a chave de teste, abra uma fatura em aberto na área do cliente e clique em Pay by card / PayPal.
- O sandbox da UTOPAY abre. Clique no botão verde ✅ para simular um pagamento.
- Você volta para a fatura. Em poucos segundos ela fica Paid; Billing → Gateway Log mostra «Success» com o id do pagamento.
- Troque a chave por
utopay_sk_live_….
Como as faturas são confirmadas
Cada pagamento leva sua própria URL de notificação: /modules/gateways/callback/utopay.php com o número da fatura e os valores, assinada com uma chave derivada da sua chave secreta. A UTOPAY assina cada evento (HMAC-SHA256) e tenta de novo por seis horas se o WHMCS não responder 2xx.
O módulo confere as duas assinaturas, relê o pagamento pela API e o lança só quando ele está pago exatamente com o valor e a moeda solicitados. Cada etapa é registrada no Gateway Log.
Solução de problemas
- «Invalid request token»: a página da fatura foi aberta antes de a chave ser trocada; recarregue a fatura.
- «amount is below the minimum»: o saldo está abaixo do mínimo do método ou da moeda; o cliente pode escolher outro.
- A fatura continua Unpaid: o WHMCS precisa estar acessível pela internet e
/modules/gateways/callback/não pode estar bloqueado por firewall ou autenticação HTTP. Veja Billing → Gateway Log. - Gateway Log: «Underpaid»: o cliente enviou menos cripto do que o necessário. O dinheiro está na sua carteira: adicione um pagamento parcial manualmente.
- «currency … is not supported»: defina Convert To For Processing como USD ou EUR.
Histórico de versões
- 1.0.1 — núcleo comum da UTOPAY atualizado, sem mudança de comportamento.
- 1.0.0 — primeira versão: cartões e PayPal, cripto, Convert To For Processing, botões em russo.
SHA-256: ab17e573fe3784fb5217c408d389a51af7196173d29f79d287938f9320a4327a
Atualizado · Equipe de integrações da UTOPAY