n8n-nodes-quickpay

Community node de n8n para la QuickLink Pay API (marca pública: QuickPay). Permite que un comercio que arma su flujo en n8n acepte y disperse pagos vía QuickLink sin escribir glue: crear links de cobro, ejecutar cobros C2P con OTP, dispersar pagos masivos y recibir webhooks firmados — todo como nodos arrastrables.

Este paquete es un wrapper de la Pay API (POST /switch/v1/...). No reimplementa lógica de dinero: arma el request, inyecta la autenticación y devuelve la respuesta cruda del switch.

Nodos incluidos

| Nodo | Tipo | Para qué | |------|------|----------| | QuickPay | acción | Crear links de cobro, cobrar con OTP, consultar y dispersar | | QuickPay Trigger | trigger (webhook) | Recibir webhooks salientes de QuickLink, verificando la firma HMAC-SHA256 |

Instalación

En tu instancia de n8n (self-hosted), instala el paquete como community node:

Opción A — desde la UI: Settings → Community Nodes → Install → n8n-nodes-quickpay.

Opción B — manual (build local, sin publicar a npm):

cd switch/integrations/n8n-nodes-quickpay
npm install
npm run build          # tsc → dist/

# enlázalo en tu carpeta de nodes custom de n8n
mkdir -p ~/.n8n/custom
ln -s "$(pwd)" ~/.n8n/custom/n8n-nodes-quickpay
# reinicia n8n

Requisitos: Node.js ≥ 18 (el trigger usa node:crypto).

Configuración de credenciales (QuickPay API)

Crea una credencial QuickPay API con:

| Campo | Ejemplo | Notas | |-------|---------|-------| | Comercio | mi_comercio | slug del comercio | | Secret Key | sk_test_… / sk_live_… | el prefijo fija el ambiente (test = no mueve dinero) | | Base URL | https://pay.quickoffer.io | sin barra final |

La credencial arma la cabecera de auth:

x-switch-key: <comercio>:<sk_key>

El botón Test hace un GET /switch/v1/bancos autenticado (read-only) para validar que la combinación comercio + key funciona.

Operaciones del nodo QuickPay

| Resource | Operation | Endpoint | |----------|-----------|----------| | Link de Cobro | Crear | POST /switch/v1/links | | Link de Cobro | Consultar | GET /switch/v1/links/{id} | | Cobro | Solicitar OTP | POST /switch/v1/cobrar/token | | Cobro | Ejecutar | POST /switch/v1/cobrar | | Cobro | Consultar | POST /switch/v1/consultar | | Dispersión | Crear | POST /switch/v1/dispersiones |

Money-safety: la regla idempotency_key (token ≠ cobro)

El cobro C2P son dos pasos: Solicitar OTP y Ejecutar. Reglas que el flujo debe respetar:

• El OTP NO es la idempotency_key. Son cosas distintas: el OTP autoriza, la idempotency_key deduplica.
• Estable por intento: usa la misma idempotency_key en Solicitar OTP y en el Ejecutar de ese mismo intento (y si reintentas exactamente ese intento). Reintentar con la misma llave nunca duplica el cobro: devuelve el resultado original.
• Nueva llave = intento nuevo: genera una idempotency_key distinta solo cuando el pagador re-solicita OTP y arranca un cobro desde cero.
• El nodo no inventa reintentos ciegos: el reintento lo decide tu flujo.

Tip: en n8n puedes derivar la llave con un nodo Code/Set (p.ej. un UUID estable por intento) y pasarla a ambos pasos por expresión.

Trigger: QuickPay Trigger

Configura un Webhook Secret (el secret show-once que QuickLink devolvió al crear el webhook). El nodo:

1. Lee el cuerpo crudo de la request.
2. Recalcula HMAC-SHA256(secret, cuerpo_crudo).
3. Lo compara en tiempo constante con x-quicklink-signature: sha256=<hex>.
4. Rechaza con 401 las firmas inválidas o ausentes (no emite nada).
5. Emite el evento si la firma es válida y el type está entre los Eventos seleccionados (transaccion.aprobada / transaccion.rechazada / transaccion.liquidada / link.pagado).

Registra la URL de producción del webhook de n8n como endpoint en tu webhook de QuickLink.

Ejemplo de flujo: Crear link → esperar link.pagado

Datos dummy (no reales):

1. Manual Trigger (o el disparador que prefieras).
2. QuickPay → Resource Link de Cobro, Operation Crear:
   • Monto: 150.00
   • Moneda: VES
   • Concepto: Pedido #1042
   • Expira (horas): 24
   • Salida: { id, url, estado: "pendiente", expires_at, ... }. Comparte url con el pagador.
3. QuickPay Trigger (rama paralela, activa en el workflow):
   • Webhook Secret: el secreto del webhook.
   • Eventos: link.pagado.
   • Cuando el pagador completa el cobro, QuickLink POSTea el evento firmado; el nodo verifica la firma y emite { type: "link.pagado", data: { id, txn_id, ... } }.
4. Conecta la salida del trigger a tu lógica de negocio (marcar pedido pagado, enviar recibo, etc.).

Ejemplo de cobro C2P con OTP (dummy)

1. QuickPay → Cobro / Solicitar OTP:
   • Idempotency Key: 11111111-1111-4111-8111-111111111111 (estable por intento)
   • Monto: 320.00, Concepto: Matrícula
   • Cobrador: { tipo: cuenta, valor: 0138..., banco: 0138, identificacion: J00378944781, nombre: Comercio Demo }
   • Pagador: { tipo: telefono, valor: 04141234567, banco: 0105, identificacion: V12345678, nombre: Pagador Demo }
2. El pagador recibe el OTP de su banco y te lo dicta.
3. QuickPay → Cobro / Ejecutar:
   • Misma Idempotency Key del paso 1.
   • Mismos Monto/Cobrador/Pagador + OTP: 12345678.
   • Salida: Resultado con estado (ACEPTADA/PENDIENTE/LIQUIDADA/RECHAZADA).
4. Opcional: QuickPay → Cobro / Consultar con el id hasta LIQUIDADA.

Scripts

npm run typecheck   # tsc --noEmit
npm run build       # tsc → dist/

Licencia

UNLICENSED (uso interno).