# 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](https://pay.perly.io/docs/sdks.md) já vem dentro.

> **Nota:** O Perly Pay fatura em USD ou EUR. Para clientes em outra moeda, escolha USD ou EUR em **Convert To For Processing** do gateway; o pagamento é registrado do mesmo jeito na moeda da própria fatura. Sem isso, esses clientes verão uma indicação para escolher outra forma de pagamento.

## Instalação

1. **Pegue o zip** — O módulo está a caminho do WHMCS Marketplace. Enquanto não chega, [escreva para nós](https://pay.perly.io/pt/contact) 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.php` e `modules/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](https://pay.perly.io/docs/test-mode.md), `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:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

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](https://pay.perly.io/docs/screening.md) | 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](https://pay.perly.io/docs/refunds.md) 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.