WooCommerce
Plugin oficial de QvaPay para WooCommerce. Acepta pagos en USD desde el balance de QvaPay de tus clientes, con confirmación automática por webhook firmado.
QvaPay para WooCommerce
QvaPay for WooCommerce es la pasarela de pago oficial que permite a las tiendas WooCommerce cobrar en USD directamente desde el balance de QvaPay de sus clientes. El cliente elige QvaPay en el checkout, la tienda crea una factura vía la API v2, y el cliente paga en QvaPay. Al confirmarse el pago, la tienda recibe un webhook firmado que marca el pedido como completado.
Repositorio en GitHub
Código fuente, releases y reporte de issues del plugin.
Crear una App
Genera el App ID y App Secret que necesita el plugin.
Requisitos
| Requisito | Versión mínima |
|---|---|
| WordPress | 6.0+ |
| PHP | 7.4+ |
| WooCommerce | 7.0+ |
| Moneda de la tienda | USD (obligatorio) |
| Protocolo | HTTPS (obligatorio) |
El plugin solo opera con tiendas configuradas en USD y servidas por HTTPS. Si la moneda no es USD o el sitio no usa HTTPS, el plugin mostrará una alerta en el panel de administración y no procesará pagos.
Instalación
Descarga el plugin
Descarga el ZIP desde la pestaña Releases del repositorio en GitHub.
Instálalo en WordPress
En tu panel de WordPress ve a Plugins → Añadir nuevo → Subir plugin, sube el ZIP y actívalo.
Crea tu App en QvaPay
Entra a Mis Aplicaciones y crea una nueva aplicación. Copia el App ID (UUID) y el App Secret (este último solo se muestra una vez).
Configura la Callback URL
En la configuración de tu App en QvaPay, establece la Callback URL apuntando al endpoint de webhook que expone el plugin:
https://TU-DOMINIO/wp-json/qvapay/v1/webhookConecta las credenciales
En WooCommerce → Ajustes → Pagos → QvaPay, pega el App ID y el App Secret, marca "Habilitar QvaPay como método de pago" y guarda.
Ajustes del plugin
La configuración se guarda en la opción woocommerce_qvapay_settings y expone los siguientes campos:
| Campo | Descripción |
|---|---|
enabled | Activa/desactiva QvaPay como método de pago en el checkout. |
title | Nombre del método de pago que ve el cliente. |
description | Texto que aparece bajo el título en el checkout. |
app_id | UUID de tu App de QvaPay. |
app_secret | Secreto de la App, usado para verificar la firma del webhook. |
webhook_url_override | (Opcional) URL/dominio alternativo del webhook para escenarios con proxy o túnel (Cloudflare, ngrok). |
webhook_url | (Solo lectura) URL de webhook efectiva que recibirá las notificaciones. |
debug | Activa el registro de peticiones y webhooks, visible en WooCommerce → Estado → Logs. |
Flujo de pago
El cliente selecciona QvaPay en el checkout.
El plugin crea una factura vía POST /v2/create_invoice con el monto y el remote_id del pedido.
El cliente es redirigido a https://www.qvapay.com/pay/{transaction_uuid} para completar el pago con su balance.
QvaPay entrega un webhook firmado al endpoint del plugin. Este valida la firma y el timestamp, marca el pedido como completado y guarda el UUID de la transacción en el meta del pedido (_qvapay_transaction_uuid).
Verificación del webhook
El plugin expone la ruta REST POST /wp-json/qvapay/v1/webhook y verifica cada notificación con dos cabeceras:
| Cabecera | Descripción |
|---|---|
x-qvapay-signature | HMAC-SHA256 (en hexadecimal) del cuerpo crudo de la petición, calculado con tu app_secret. |
x-qvapay-timestamp | Timestamp Unix de la petición. Se acepta una ventana de ±300 segundos para mitigar ataques de replay. |
La firma se compara con hash_equals() para evitar fugas por tiempo de comparación. Los pedidos son idempotentes: una notificación repetida para un pedido ya procesado no lo vuelve a procesar.
El App Secret nunca viaja en la notificación: se usa de ambos lados para calcular y comparar la firma HMAC. Mantenlo en secreto; si lo rotas en QvaPay, actualízalo también en los ajustes del plugin.
Características
- Integración directa con la API
v2de comerciantes de QvaPay. - Verificación de firma HMAC-SHA256 con protección contra replay (±5 minutos).
- Idempotencia de pedidos: evita el doble procesamiento.
- Compatible con el checkout clásico de WooCommerce y con los bloques de Cart/Checkout.
- Override opcional de la URL del webhook para entornos con proxy o túnel.
- Logging de depuración integrado en el panel de estado de WooCommerce.
- Alertas en el admin cuando la moneda no es USD o el sitio no usa HTTPS.
Soporte
¿Dudas o problemas? Abre un issue en el repositorio del plugin o únete al grupo de Telegram para desarrolladores.