quickpay

n8n community node para QuickPay / QuickLink Pay API — crea links de cobro, ejecuta cobros C2P con OTP, dispersa pagos y recibe webhooks firmados (HMAC-SHA256) sin escribir glue.

Package Information

Released: 3 mo ago
Downloads: 165 weekly / 165 monthly
Latest Version: 0.1.0
Author: QuickLink

Available Nodes

QuickPay icon
QuickPay
Cobra, dispersa y crea links de pago con la QuickLink Pay API
QuickPay Trigger icon
QuickPay Trigger
Recibe y verifica (HMAC-SHA256) los webhooks salientes de QuickLink

Documentation

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).

Discussion