HandyPay

Guia de integração

Obtenção do WHMCS

Conecte o WHMCS ao HandyPay para faturas únicas e assinaturas recorrentes, mantendo o teste e faturamento ao vivo completamente separados.

Configurar lista de verificação

  1. Crie uma chave do API no portal mercante. Iniciar com um hp_test_ Chave.
  2. Armazene a chave na configuração do gateway do WHMCS. Nunca coloque no JavaScript do lado do cliente ou em um modelo público.
  3. Utilização https://api.handypay.me/api/v1 como base do API URL.
  4. Registre um endpoint webhook que pode receber pagamentos e eventos de ciclo de vida da assinatura.
  5. Execute uma fatura de teste completa antes de substituir a chave por uma hp_live_ Chave.

Ensaio seguro

As chaves de teste usam uma conta de teste dedicada. Produtos, clientes, pagamentos, assinaturas e endpoints webhook criados com uma chave de teste não podem aparecer em atividade ao vivo.

Verificar a atividade do teste
curl https://api.handypay.me/api/v1/test-payments \
  -H "Authorization: Bearer hp_test_your_api_key_here"
bash

A mesma atividade é visível no modo de teste no portal mercador do HandyPay.

Comportamento de saída

Crie uma sessão de pagamento hospedada para cada fatura do WHMCS. O HandyPay mostra métodos de pagamento elegíveis para o comerciante, moeda, cliente e dispositivo. A compra de cartão permanece disponível quando um método adicional não é elegível.

Criar uma verificação de fatura
curl -X POST https://api.handypay.me/api/v1/payment-sessions \
  -H "Authorization: Bearer hp_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{
      "amount": 4999,
      "currency": "usd",
      "name": "WHMCS invoice #1042",
      "quantity": 1
    }],
    "customer_email": "buyer@example.com",
    "success_url": "https://billing.example.com/payment-complete",
    "cancel_url": "https://billing.example.com/viewinvoice.php?id=1042",
    "metadata": { "whmcs_invoice_id": "1042" }
            }'
bash

O Google Pay já está habilitado. Não há nenhum campo do Google Pay para adicionar ao módulo. O Stripe Checkout o apresenta automaticamente quando o cliente e o pagamento estão qualificados.

  • Teste em um navegador compatível, em um dispositivo qualificado com um cartão ativo no Google Wallet.
  • Não use uma janela privada ou anônima e permita que o navegador verifique as formas de pagamento salvas.
  • O Google Pay é registrado como uma carteira de cartão, portanto a sessão de Checkout e o fluxo de webhooks existentes continuam conciliando a fatura do WHMCS.
Testar formas de pagamento neste navegador →

Assinaturas e lugares sentados

Crie um produto de assinatura uma vez e, em seguida, crie uma sessão de assinatura para o cliente. Definir quantity para cobrança por assento. As assinaturas activas podem ser actualizadas sem as substituir.

Alterar um número de assentos ativo
curl -X PATCH https://api.handypay.me/api/v1/subscriptions/sub_123/quantity \
  -H "Authorization: Bearer hp_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 8,
    "proration_behavior": "create_prorations"
  }'
bash
  • create_prorations Coloca o ajustamento na próxima factura.
  • always_invoice factura o ajustamento imediatamente.
  • none muda a contagem do banco sem um ajuste prorado.

Webhooks

Registre o URL de chamada do WHMCS com o mesmo modo de chave usado pela saída. Um endpoint de teste recebe apenas eventos de teste, e um endpoint vivo recebe apenas eventos vivos.

Registar um webhook de teste
curl -X POST https://api.handypay.me/api/v1/webhook-endpoints \
  -H "Authorization: Bearer hp_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://billing.example.com/modules/gateways/callback/handypay.php",
    "events": [
      "payment_intent.succeeded",
      "payment_intent.payment_failed",
      "customer.subscription.updated",
      "customer.subscription.deleted"
    ]
  }'
bash

Resolução de Problemas

O Google Pay não aparece: confirme se o Google Wallet tem um cartão ativo, use um navegador e dispositivo compatíveis fora da navegação privada e permita que o navegador verifique formas de pagamento salvas. A Stripe ainda pode ocultar uma carteira para uma região ou transação não compatível; o cartão continua sendo a alternativa compatível.

Falta um pagamento de teste: confirmar o pedido utilizado hp_test_ chave, então verifique o portal Modo de Teste de espaço de trabalho ou GET /v1/test-payments.

O WHMCS não está atualizando: confirmar o callback O URL é público HTTPS, verificar a assinatura do webhook contra o corpo de solicitação bruto, e retornar uma resposta 2xx bem sucedida apenas após a atualização da fatura ter sucesso.