01 Qué hace y por qué no es solo un generador de código
Elegir pasarela es lo fácil. Lo que da problemas en producción es todo lo demás: un webhook que valida la firma pero no la antigüedad del evento y puede reutilizarse, un importe multiplicado por 100 en una moneda sin decimales, una ruta que concede acceso a quien envíe un POST con el texto adecuado. Ninguno de estos fallos lanza un error; muchos pasan una revisión de código.
PagoKit combina el trabajo del modelo con tres piezas deterministas que no dependen de la IA: validadores enganchados a los hooks de Claude Code que bloquean escrituras inseguras, un recomendador que ordena proveedores con reglas fijas y un firmador que genera eventos válidos para probar tus webhooks. Todo se ejecuta en local, sin cuenta, sin clave de API y sin telemetría.
| Nivel | Proveedores | Qué obtienes |
|---|---|---|
| Integración completa | Stripe, Mercado Pago, Lemon Squeezy y Wompi | Código completo e idiomático para tu stack. |
| Recomendación | Otros 38, entre ellos Redsys, Mollie, Adyen, Paddle o GoCardless | Comparativa, cálculo de comisiones y checklist; el código lo escribes tú. |
02 Instalación
git clone https://github.com/Hainrixz/agente-pagokit ~/agente-pagokit
cd ~/tu-proyecto
claude --plugin-dir ~/agente-pagokitCon la sesión abierta, lanza el asistente con /pagokit:start. El plugin se carga solo en las sesiones que arranques con --plugin-dir, así que no afecta a tus otros proyectos.
03 Cómo funciona el asistente
-
1
Analiza el proyecto
Lee package.json, rutas y esquema de base de datos para detectar framework, ORM, destino de despliegue y casos especiales como marketplaces o compras dentro de apps móviles.
-
2
Pregunta lo justo
Tres preguntas, cinco como máximo: país y compradores, pago único o suscripción y qué métodos locales necesitas.
-
3
Recomienda con motivos
Filtra primero por lo que te descarta (si puedes abrir cuenta en ese país, si tendrás claves a tiempo) y explica por qué rechaza cada alternativa.
-
4
Genera la integración
Un subagente escribe los archivos mientras los validadores revisan cada escritura y bloquean las que incumplen sus reglas.
Checkout
Precio buscado en el servidor, clave de idempotencia con UUID y unidades monetarias correctas para cada moneda.
Webhook
Cuerpo sin procesar, verificación de firma, ventana contra reenvíos, deduplicación por id de evento y respuesta rápida.
Portal y reembolsos
Autogestión de suscripciones y reembolsos con comprobación de permisos, o la vía de pago alternativa en métodos irreversibles.
Documentación
Registro de la integración, eventos enrutados, pendientes y una checklist para pasar a producción.
04 Lo que bloquea
- ✓Webhooks sin verificación de firma o que procesan el JSON antes de verificarla.
- ✓Claves de idempotencia predecibles con Math.random() o Date.now().
- ✓Claves de producción escritas en el código fuente.
- ✓Un .env creado antes de que .gitignore lo cubra.
- ✓Multiplicar por 100 en monedas sin decimales, como el yen.
- ✓Comparar firmas con === en lugar de una comparación de tiempo constante.
- ✓Datos de tarjeta que pasan por tu propio servidor, lo que dispara tus obligaciones PCI.
- ✓Reembolsos sobre métodos de pago que no los admiten, o rutas que sobrescriben webhooks existentes.
05 Probar y revisar la integración
| Comando | Qué hace |
|---|---|
| /pagokit:start | Asistente completo: analiza, pregunta, recomienda e implementa. |
| /pagokit:test | Envía a tu webhook local un evento válido, uno falsificado y uno repetido. Los dos últimos deben rechazarse. |
| /pagokit:doctor | Auditoría de solo lectura de una integración ya existente: credenciales, modo de claves, firma, eventos, esquema y protección contra reenvíos. |
Ejecuta /pagokit:doctor sobre este proyecto y después /pagokit:test. Resume en una tabla qué comprobaciones pasan y cuáles fallan, y para cada fallo explica el riesgo para el negocio en una frase. Repasa conmigo PAGOKIT_PRODUCTION_CHECKLIST.md punto por punto antes de cambiar ninguna clave a modo real.06 Si vendes en España
Para España, el recomendador identifica Bizum como método instantáneo dominante y conoce proveedores locales como Redsys, pero estos últimos están en nivel de recomendación: te dará comisiones, restricciones y checklist, no el código. Para un SaaS o infoproducto con clientes en varios países, Lemon Squeezy actúa como comerciante registrado y se encarga de los impuestos de venta; Stripe te da más control pero la facturación y el IVA siguen siendo tu responsabilidad.
Vendo [producto o servicio] a [particulares o empresas] en [países], con [pago único o suscripción] y un ticket medio de [importe]. Usa el recomendador de PagoKit para comparar las tres mejores opciones: comisiones estimadas, métodos de pago locales, quién gestiona los impuestos y qué nivel de integración ofrece PagoKit para cada una. No generes código todavía.Preguntas frecuentes
No. Todo se ejecuta en tu ordenador y no tiene telemetría. Las únicas llamadas de red son las que hace el código generado a tu propio proveedor de pagos.
El ejemplo de referencia es Next.js con App Router y Prisma, pero adapta la estructura a otros stacks manteniendo las mismas garantías de seguridad.
No. Reduce mucho los errores típicos, pero antes de cobrar dinero real conviene que alguien técnico revise la integración y que pruebes el flujo completo en modo de pruebas.
Los conoce y te los recomienda cuando encajan, pero a día de hoy no genera su código: te entrega la recomendación, el cálculo de comisiones y una checklist.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.