Qué hace el módulo
- Dos botones en la factura: Pay by card / PayPal (4,5%) y Pay with crypto con selector de moneda (1,5%). Cualquiera de los dos se puede desactivar.
- El cliente paga el saldo de la factura, así que también funcionan las facturas pagadas parcialmente.
- El pago se aplica con
addInvoicePaymentsolo después de que el módulo lo vuelve a leer por la API: pagado, con el mismo importe y moneda. El id del pago de UTOPAY se usa como id de transacción, así que un pago nunca se aplica dos veces. - Las facturas en una moneda que UTOPAY no acepta (por ejemplo, RUB) se pagan en la moneda de Convert To For Processing; la factura se abona en su propia moneda.
- No se llama a nada mientras se muestra una factura: el pago se crea solo cuando el cliente pulsa un botón.
Instalación
- Descarga el ZIP de arriba y descomprímelo.
- Sube el contenido de la carpeta
utopay-whmcsa la raíz de WHMCS; la carpetamodulesse fusiona con la tuya:modules/gateways/utopay.php,modules/gateways/utopay/,modules/gateways/callback/utopay.php. - En el panel de UTOPAY abre Integration → API keys y crea una clave de prueba
utopay_sk_test_…. - Admin de WHMCS → System Settings → Payment Gateways → All Payment Gateways → UTOPAY.
- Pega la clave, elige las opciones de pago y guarda.
- Para cripto: añade tu wallet EVM en el panel (Project settings → Funds & payouts, sección Crypto wallets) y enumera las monedas en los ajustes del módulo.
Ajustes
| Campo | Qué hace |
|---|---|
| Secret key | utopay_sk_test_… para el sandbox, utopay_sk_live_… para pagos reales. |
| Payment options | Tarjeta / PayPal y cripto, solo tarjeta o solo cripto. |
| Crypto coins | Tickers separados por comas, por ejemplo bep20/usdt,erc20/usdt,polygon/usdc. Lista completa: https://api.utopay.app/v1/crypto/coins. |
| Card method | Vacío: elige el cliente. O envía a todos directamente a un método (Stripe, PayPal, Revolut…). |
| Convert To For Processing | Opción estándar de WHMCS: la moneda en la que se hace el pago cuando la moneda de la factura no es compatible. |
Pago de prueba
- Con la clave de prueba, abre una factura impagada en el área de cliente y pulsa Pay by card / PayPal.
- Se abre el sandbox de UTOPAY. Pulsa el botón verde ✅ para simular un pago.
- Vuelves a la factura. En unos segundos pasa a Paid; Billing → Gateway Log muestra «Success» con el id del pago.
- Cambia la clave por
utopay_sk_live_….
Cómo se confirman las facturas
Cada pago lleva su propia URL de notificación: /modules/gateways/callback/utopay.php con el número de factura y los importes, firmada con una clave derivada de tu clave secreta. UTOPAY firma cada evento (HMAC-SHA256) y reintenta durante seis horas si WHMCS no responde 2xx.
El módulo comprueba ambas firmas, vuelve a leer el pago por la API y lo aplica solo cuando está pagado exactamente con el importe y la moneda solicitados. Cada paso se registra en el Gateway Log.
Solución de problemas
- «Invalid request token»: la página de la factura se abrió antes de cambiar la clave; recarga la factura.
- «amount is below the minimum»: el saldo está por debajo del mínimo del método o moneda; el cliente puede elegir otro.
- La factura sigue en Unpaid: WHMCS debe ser accesible desde internet y
/modules/gateways/callback/no debe estar bloqueado por un firewall o autenticación HTTP. Revisa Billing → Gateway Log. - Gateway Log: «Underpaid»: el cliente envió menos cripto de la necesaria. El dinero está en tu wallet: añade un pago parcial a mano.
- «currency … is not supported»: pon Convert To For Processing en USD o EUR.
Historial de versiones
- 1.0.1 — núcleo común de UTOPAY actualizado, sin cambios de comportamiento.
- 1.0.0 — primera versión: tarjetas y PayPal, cripto, Convert To For Processing, botones en ruso.
SHA-256: ab17e573fe3784fb5217c408d389a51af7196173d29f79d287938f9320a4327a
Actualizado · Equipo de integraciones de UTOPAY