Guias
WHMCS
Gateway de pagamento para o WHMCS: os clientes pagam as faturas em bitcoin ou USDC/USDT direto na sua carteira, e um webhook assinado registra o pagamento.
O módulo do Perly Pay adiciona cripto às faturas do WHMCS. O cliente clica em Pagar com cripto; o saldo da fatura vira uma fatura do Perly Pay, paga sobre a página do WHMCS ou numa página separada; um webhook assinado registra o pagamento no WHMCS. WHMCS 8, PHP 8.1+ com curl. Não é preciso instalar nada com o Composer: o SDK de PHP já vem dentro.
Instalação
- 1
Pegue o zip
O módulo está a caminho do WHMCS Marketplace. Enquanto não chega, escreva para nós para pedir o
perly-pay-whmcs.zip. - 2
Envie
Descompacte sobre a sua pasta do WHMCS. São adicionados
modules/gateways/perlypay.php,modules/gateways/callback/perlypay.phpemodules/gateways/perlypay/. - 3
Ative
Configuration → Apps & Integrations → Payment Gateways (ou Setup → Payment Gateways), ative Perly Pay.
Configuração
| Campo | O que colocar |
|---|---|
| Chave secreta | Dashboard → Developers → API keys. sk_test_… para o modo de teste, sk_live_… para dinheiro real. |
| Segredo de assinatura do webhook | whsec_…, do webhook que você vai adicionar para este WHMCS (abaixo). |
| Checkout | Sobreposto abre o checkout sobre a fatura (pay.js). Redirecionamento leva o cliente para a página dele. No celular, a página sempre abre. |
| Moedas | USD e EUR, ou só uma. |
- 1
Cole a chave
Salve e clique em Testar conexão no campo da chave: você vê se a chave funciona, o modo dela e se o Perly Pay tem o webhook deste WHMCS.
- 2
Adicione o webhook
Em Dashboard → Developers → Webhooks, adicione o endereço da configuração,
https://your-whmcs/modules/gateways/callback/perlypay.php, com os eventos de faturas e reembolsos. Cole o segredo dele e salve. - 3
Permita a sobreposição
Em Dashboard → Settings, adicione o endereço do seu WHMCS em Sites that may embed the checkout. Sem isso, a sobreposição oferece abrir o checkout numa aba nova.
Teste
Com uma chave sk_test_…, abra uma fatura não paga na área do cliente e clique em Pagar com cripto. Pague com moedas de teste ou pela API; o id da fatura está no checkout:
Em alguns segundos, a fatura do WHMCS passa a Paid. Billing → Gateway Log mostra a rede, o valor e um link para a transação.
Como as faturas acompanham os pagamentos
| No Perly Pay | No WHMCS |
|---|---|
Paga, remetente verificado (invoice.fulfilled) | Um pagamento no valor faturado ao cliente, na moeda da fatura, com o id de pagamento do Perly Pay (pay_…). O WHMCS marca a fatura como Paid e faz o resto como sempre. |
| Vista, paga em parte, paga e ainda em revisão | Uma linha no Gateway Log. Sem pagamento. |
| Retida para revisão | Uma linha no Gateway Log com o motivo. Decida no Perly Pay. |
| Expirada ou cancelada | Uma linha no Gateway Log. Clicar no botão de novo cria uma fatura nova. |
| Reembolso aberto, pronto, enviado, confirmado | Uma linha no Gateway Log: o que enviar e para onde. |
Clicar no botão de novo reaproveita a fatura aberta enquanto o saldo for o mesmo. Cada pagamento é registrado uma única vez, chegue o webhook quantas vezes chegar, e só para faturas deste WHMCS.
Reembolsos
Reembolse a transação no WHMCS como sempre: o módulo abre um reembolso no Perly Pay na moeda em que foi pago (na mesma proporção, se for parcial). O Perly Pay pede ao cliente um endereço por e-mail e o verifica; o Gateway Log diz o que enviar e para onde. Você envia da sua carteira e cola o id da transação no Perly Pay: o Perly Pay nunca guarda o dinheiro.
Ir para produção
- Ative a produção no Perly Pay e conecte as chaves públicas da sua carteira.
- Cole uma chave
sk_live_…. As chaves e os webhooks de produção são separados dos de teste: adicione de novo o endereço de retorno em produção e cole o segredo dele. - Adicione o endereço https do seu WHMCS em Sites that may embed the checkout em produção.
- Pague uma fatura real pequena e reembolse.