Integrar un sistema de pagos desde cero consume semanas; PagoKit lo resuelve en minutos generando ~14 archivos listos para producción con 5 bloqueos de seguridad activos. El agente escanea tu proyecto, hace 3 preguntas sobre tu negocio, y escribe el checkout completo para Stripe, Mercado Pago, Wompi o Lemon Squeezy. Es más útil para founders que están lanzando su primer producto de pago con Next.js o Express.
Plugin gratuito (MIT) para Claude Code 2.x que automatiza la integración completa de un método de pago — botón, webhook firmado, reembolsos, portal de cliente y schema de base de datos — eligiendo el proveedor correcto según el país de tus clientes.
La diferencia con copiar la guía oficial de Stripe o Mercado Pago es doble:
.env en .gitignore, el commit falla. No es sugerencia — es PostToolUse hook que bloquea en duro.# 1. Clonar el repositorio una sola vez en el home
git clone https://github.com/Hainrixz/agente-pagokit ~/agente-pagokit
# 2. Desde la carpeta de tu proyecto, iniciar Claude Code con el plugin
claude --plugin-dir ~/agente-pagokit
# 3. Dentro de Claude Code, activar el agente
/pagokit:start
Requisitos previos: Node.js ≥ 18, Claude Code 2.x instalado.
El plugin vive en ~/agente-pagokit y es reutilizable para cualquier proyecto. No modifica configuración global — solo activa para esa sesión.
| Comando | Función |
|---|---|
/pagokit:test |
Corre validadores en dry-run sobre archivos generados. Útil después de editar manualmente para confirmar que no rompiste ningún bloqueo. |
/pagokit:doctor |
Diagnóstico de entorno: verifica Node ≥ 18, plugin vinculado correctamente, variables de entorno en su lugar. |
| Respuesta | Proveedor elegido | Razón |
|---|---|---|
| USA · UK · Europa · Australia | Stripe | Dashboard maduro, subscripciones complejas, ecosistema de integraciones más grande |
| México · Argentina · Brasil · Chile · Colombia · Perú · Uruguay | Mercado Pago | Mejor ratio cobertura/comisión para LatAm, agrupa métodos locales en un SDK |
| Solo Colombia | Wompi | Más liviano y barato que Mercado Pago para ese caso específico |
| Cualquier país · ventas digitales globales | Lemon Squeezy | Actúa como Merchant of Record, maneja IVA/VAT/sales tax mundialmente |
Checkout Sessions y schema simple con tabla Payment.Si se activa, PagoKit habilita los métodos de efectivo del proveedor elegido:
El pago en efectivo no es instantáneo — puede demorar 24-72 horas. PagoKit ajusta el copy del botón y el manejo del estado pending en consecuencia.
Para un proyecto Next.js App Router + Prisma (el caso más común). En Express u otro ORM los nombres cambian pero la lógica es la misma.
components/CheckoutButton.tsx — Botón visible al cliente. Al hacer clic llama al endpoint de checkout y redirige al gateway del proveedor.app/api/checkout/route.ts — Crea la sesión de pago. Recibe el carrito o producto, llama al proveedor y retorna URL de redirección.app/api/webhook/[provider]/route.ts — Escucha eventos del proveedor cuando alguien paga. Verifica firma criptográfica, actualiza base de datos, dispara emails o acceso.app/api/portal/route.ts — Abre el portal de cliente: facturas, actualizar tarjeta, cancelar suscripción sin contactarte.app/api/refund/route.ts — Ejecuta reembolso desde admin. Conecta con proveedor, revierte el cobro y actualiza estado en DB.lib/payments/[provider].ts — Cliente del proveedor configurado con keys desde .env, reintentos en fallo de red y tipos del SDK.lib/payments/errors.ts — Tipos y helpers para manejo consistente de errores: CardDeclined, WebhookSignatureInvalid, RateLimited. Tu UI sabe qué mostrar según el tipo.lib/payments/utils.ts — Helpers comunes: generar IDs idempotentes (uno de los 5 bloqueos), formatear montos con moneda correcta, parsear webhooks.lib/db.ts — Cliente de DB configurado y exportado como singleton para evitar múltiples conexiones por request.prisma/schema.prisma — Tablas de pagos faltantes: Payment, Subscription, Customer, WebhookEvent. Si ya tienes schema, PagoKit hace merge sin tocar el tuyo..env.example — Template de variables de entorno con instrucciones exactas de dónde obtener cada valor en el dashboard del proveedor..gitignore (patch) — Si .env no está en .gitignore, lo agrega automáticamente. Es uno de los 5 bloqueos.PAGOKIT_INTEGRATION.md — Manual de tu integración: qué decidió el agente, qué archivos creó, dónde pegar keys, cómo probar el flujo end-to-end.PAGOKIT_PRODUCTION_CHECKLIST.md — Checklist final antes de cobrar real: cambiar keys de test a live, activar webhook en dashboard del proveedor, configurar dominio para emails de recibo, hacer un cobro de $1 USD de prueba y reembolsarlo.Estos no son advertencias — bloquean el commit en duro.
Escanea cada archivo modificado buscando patrones de keys reales (sk_live_*, prod_*, etc.). Si encuentra una, bloquea el commit e indica el archivo y línea a mover a .env.
.env siempre en .gitignoreAntes de cualquier commit verifica que .env esté listado en .gitignore. Si no, lo agrega automáticamente o falla con instrucciones claras. Una key en el historial de git se asume comprometida.
Inspecciona cada endpoint webhook generado y exige llamar al método de verificación de firma del proveedor (Stripe.webhooks.constructEvent, MercadoPago.signatureVerify, etc.) antes de procesar el body. Sin esto, cualquiera con la URL del webhook puede simular un pago y desbloquear acceso premium.
Cada operación de cobro y reembolso usa una idempotency key generada como UUID v4 desde el cliente, persistida en la tabla Payment. Si Stripe envía el mismo evento dos veces (sucede), tu DB no genera dos filas de pago.
Configura middleware de raw body solo en rutas webhook (bodyParser.raw({ type: 'application/json' }) o equivalente en Next.js). El body se preserva tal como llegó y la firma valida correctamente. Sin esto, Express parsea el JSON y la verificación de firma falla — bug clásico que cuesta horas de debugging.
Además de los 5 bloqueos, hay 7 reglas que advierten sin bloquear: sin replay protection en webhook, sin límite de tamaño de body, logging de datos sensibles (PII), usando keys live en desarrollo. Dejan un comentario en el código pero no detienen el commit.
Si necesitas saltarte una regla por un caso legítimo, agrega el comentario:
// pagokit-ignore: <nombre-regla> -- <tu-razón>
PagoKit permite pero registra en .pagokit/audit.log con tu razón.
Fase 1 (disponible hoy)
Fase 2 (roadmap próximo)
Fase 3 (roadmap futuro)
Si tu stack está en Fase 2 o 3, PagoKit lo detecta y te lo dice honestamente — no improvisa salidas a medias.
Decide el modelo de negocio antes de correr el comando. ¿Cobro único, suscripción, mixto? ¿Cuánto? ¿En qué monedas? ¿De dónde vienen tus clientes reales hoy?
Ten las API keys del proveedor en modo test. PagoKit genera el código pero tú pegas las keys en .env. Nunca uses keys live en desarrollo.
Corre /pagokit:start y responde honestamente. Si vendes en LatAm pero "algún día" quieres expansión a USA, responde LatAm. Siempre puedes cambiar de proveedor con un nuevo /pagokit:start. Elige lo que necesitas hoy.
Lee PAGOKIT_INTEGRATION.md antes de probar. Es el primer archivo que abres. Dice qué proveedor eligió, qué archivos creó, dónde pegar las keys, qué variables faltan, cómo probar el flujo completo localmente. Leerlo entero ahorra horas.
Sigue PAGOKIT_PRODUCTION_CHECKLIST.md antes de cobrar real. Cambia keys de test a live, configura el webhook en el dashboard del proveedor con la URL real, activa el dominio de emails, haz un cobro real de $1 USD y reembólsalo verificando el flujo completo.
| Situación | Por qué no aplica |
|---|---|
| Ya tienes Stripe o Mercado Pago integrado y funcionando | PagoKit es para empezar desde cero, no migra integraciones existentes |
| Tu stack está en Fase 2 o 3 del roadmap | No puede generar código end-to-end para tu framework aún |
| Necesitas un método de pago específico no incluido (cripto, ACH directo, transferencias bancarias custom) | PagoKit no improvisa — mejor integrar directo el SDK que necesitas |
| Empresa con equipo de pagos dedicado y pipeline de seguridad propio | Los bloqueos deterministas pueden chocar con tu CI. Consultar con el CTO antes de instalar en repos corporativos |