HandyPay

Integración guía

Pago por WHMCS

Conecte WHMCS a HandyPay para facturas únicas y suscripciones recurrentes mientras mantiene la facturación de prueba y en vivo completamente separada.

Lista de verificación de configuración

  1. Crear una API clave en el portal del comerciante. Comience con una hp_test_ clave.
  2. Almacene la clave en la configuración de la puerta de enlace WHMCS. Nunca lo coloque en JavaScript del lado del cliente ni en una plantilla pública.
  3. Utilice https://api.handypay.me/api/v1 como URL base de API.
  4. Registre un punto final de webhook que pueda recibir eventos del ciclo de vida de pagos y suscripciones.
  5. Ejecute una factura de prueba completa antes de reemplazar la clave con una hp_live_ clave.

Prueba de forma segura

Las claves de prueba utilizan una cuenta de prueba dedicada. Los productos, clientes, pagos, suscripciones y puntos finales de webhook creados con una clave de prueba no pueden aparecer en la actividad en vivo.

Verificar actividad de prueba
curl https://api.handypay.me/api/v1/test-payments \
  -H "Authorization: Bearer hp_test_your_api_key_here"
bash

La misma actividad es visible en el Modo de prueba en el portal comercial HandyPay.

Comportamiento de pago

Crear una sesión de pago alojada para cada WHMCS factura. HandyPay muestra los métodos de pago elegibles para el comerciante, la moneda, el cliente y el dispositivo. El pago con tarjeta permanece disponible cuando un método adicional no es elegible.

Crear una factura checkout
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

Google Pay ya está habilitado. No hay ningún campo de Google Pay que añadir al módulo. Stripe Checkout lo muestra automáticamente cuando el cliente y el pago cumplen los requisitos.

  • Haga la prueba en un navegador compatible y un dispositivo apto con una tarjeta activa en Google Wallet.
  • No use una ventana privada o de incógnito y permita que el navegador compruebe los métodos de pago guardados.
  • Google Pay se registra como una cartera de tarjeta, por lo que la sesión de Checkout y el flujo de webhooks existentes siguen conciliando la factura de WHMCS.
Probar métodos de pago en este navegador →

Suscripciones y puestos

Cree un producto de suscripción una vez y luego cree una sesión de suscripción para el cliente. Establecer quantity para facturación por puesto. Las suscripciones activas se pueden actualizar sin reemplazarlas.

Cambiar el recuento de asientos activos
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 el ajuste en la siguiente factura.
  • always_invoice factura el ajuste inmediatamente.
  • none cambia el recuento de asientos sin un ajuste prorrateado.

Webhooks

Registre la URL de devolución de llamada de WHMCS con el mismo modo de clave utilizado al realizar el pago. Un punto final de prueba solo recibe eventos de prueba y un punto final en vivo solo recibe eventos en vivo.

Registrar un webhook de prueba
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

Solución de problemas

Google Pay no aparece: confirme que Google Wallet tenga una tarjeta activa, use un navegador y dispositivo compatibles fuera de la navegación privada y permita que el navegador compruebe los métodos de pago guardados. Stripe aún puede ocultar una cartera para una región o transacción no admitida; la tarjeta sigue siendo la alternativa compatible.

Falta un pago de prueba: confirme que la solicitud utilizó una hp_test_ clave, luego verifique el espacio de trabajo del modo de prueba del portal o GET /v1/test-payments.

WHMCS no está actualización: confirme que la URL de devolución de llamada sea HTTPS pública, verifique la firma del webhook con el cuerpo de la solicitud sin procesar y devuelva una respuesta 2xx exitosa solo después de que la actualización de la factura sea exitosa.