Si estás construyendo con la nube y te falta el método de pago, hice este plugin gratis para la comunidad. Lo instalás · le decís de dónde son tus clientes · y te escribe el checkout completo con Stripe, Mercado Pago, Wompi o Lemon Squeezy — botón, webhook firmado, refunds, portal del cliente y schema de DB. Acá va el paso a paso para que lo uses bien en tu próximo proyecto, en español simple, sin asumir que sos dev profesional.
Los 4 proveedores · de un vistazo
EE.UU. · Europa · global
Stripe
Para vender en Estados Unidos, Reino Unido, Europa o Australia. Incluye OXXO, Boleto, Pix, Bizum, SEPA y ACH cuando hace falta.
LatAm
Mercado Pago
Para vender en México, Argentina, Brasil, Chile, Colombia, Perú o Uruguay con OXXO, Pix, Boleto, Rapipago, PSE y PagoEfectivo.
Colombia
Wompi
Para proyectos enfocados 100% en Colombia con PSE, Nequi, Bancolombia, Efecty y Baloto. Más liviano que Mercado Pago para ese caso.
Global · sin pelearse
Lemon Squeezy
Para vender productos digitales en todo el mundo con tarjeta, PayPal y Klarna. Maneja VAT e impuestos por vos como Merchant of Record.
Manual completo · actualizado a mayo 2026
4 proveedores soportados · 14 archivos generados · 5 candados deterministas · explicado en español simple
Esta guía es el manual completo de PagoKit · qué es · cómo se instala · qué responder a las 3 preguntas que te hace · qué proveedor te conviene según de dónde son tus clientes · qué hace cada uno de los 14 archivos que escribe en tu proyecto · y qué protege cada uno de los 5 candados de seguridad. Todo en español simple · sin asumir que programás profesionalmente.
01 qué es
PagoKit es un plugin para Claude Code (la versión terminal de Claude, no la web). Lo instalás una sola vez, lo activás dentro de la carpeta de tu proyecto, y el agente se mete a escanear tu código de pie a cabeza — qué framework usás, qué base de datos tenés, qué carpetas existen, dónde van las rutas — antes de tocar absolutamente nada.
Una vez que entiende tu proyecto, te hace 3 preguntas cortas para entender tu negocio (no técnicas). Con esas respuestas elige el mejor proveedor de pagos según tu país y modelo, y escribe alrededor de 14 archivos en tu proyecto — el botón de pagar, el endpoint que escucha cuándo alguien pagó, los refunds, el portal del cliente, el schema de la base de datos y la documentación.
La diferencia con copiar y pegar la guía oficial de Stripe (o de cualquier otro) es que PagoKit te deja todo listo para producción con 5 candados de seguridad activos: si intenta publicar una API key, escribir un webhook sin verificar firma, o dejar tu `.env` fuera del `.gitignore`, el commit se bloquea. No hay forma de cagarla por descuido.
En una frase, en serio
PagoKit es como si tuvieras un dev senior de pagos sentado al lado tuyo · entiende tu proyecto, te hace las 3 preguntas justas, y te deja el método de pago listo para producción · con los candados puestos para que no la cagues por descuido.
02 instalación
Antes de empezar · prerequisitos
Bajás el plugin a tu home una sola vez. No se mete dentro de tu proyecto · vive aparte y se reutiliza para cualquier proyecto donde lo necesites.
Paso 01
git clone https://github.com/Hainrixz/agente-pagokit ~/agente-pagokitEntrá a la carpeta del proyecto donde vas a meter el checkout y arrancás Claude Code apuntando al plugin. Solo se activa para esa sesión · no modifica tu config global.
Paso 02
claude --plugin-dir ~/agente-pagokitDentro de Claude Code, escribís este comando y el agente se pone a escanear tu proyecto. Después te hace las 3 preguntas y arranca a escribir archivos.
Paso 03
/pagokit:startComandos auxiliares · cuando los necesites
/pagokit:testCorre los validadores en seco sobre los archivos generados — útil después de editar manualmente para confirmar que no rompiste ningún candado.
/pagokit:doctorDiagnóstico del entorno · revisa que tu Node sea ≥ 18, que el plugin esté bien linkeado y que las variables de entorno estén donde tienen que estar.
03 las 3 preguntas
Cuando corrés /pagokit:start, después de escanear tu proyecto, PagoKit te hace exactamente estas 3 preguntas. Son cortas, sin tecnicismo, y con tus respuestas elige proveedor y arma los archivos.
Opciones posibles
Qué decide tu respuesta
Define el proveedor base. Países anglo o europeos → Stripe. LatAm con Mercado Pago disponible → Mercado Pago. Solo Colombia → Wompi (más liviano). Global sin pelearse con cada autoridad fiscal → Lemon Squeezy como Merchant of Record.
Opciones posibles
Qué decide tu respuesta
Determina qué endpoints y qué tablas de DB se generan. Pago único usa Checkout Sessions y un schema simple. Suscripción agrega portal del cliente, manejo de renovaciones, upgrades, cancelaciones y un schema con estado de subscription. La opción mixta arma los dos flujos juntos.
Opciones posibles
Qué decide tu respuesta
Activa o no los métodos cash-based del proveedor elegido. Si pedís efectivo, PagoKit prende OXXO en México, Boleto en Brasil, Rapipago en Argentina, Efecty en Colombia. Esto cambia el copy del botón de checkout y el manejo del estado pendiente (un pago en efectivo no se cobra al instante · puede tardar 24-72hs).
04 proveedores
PagoKit elige uno de estos 4 según tus respuestas. Acá tenés la lógica detrás de cada uno · qué países cubre, qué métodos locales soporta, cuándo conviene elegirlo y qué alternativa tenés si no encaja perfecto.
Países donde brilla
Si tus clientes están en EE.UU., Canadá, Reino Unido, la Unión Europea, México, Brasil, India o Australia.
Métodos locales que soporta
Cuándo elegirlo
Es el default cuando vendés a países con alto poder adquisitivo y necesitás un dashboard maduro, suscripciones complejas y un ecosistema enorme de integraciones.
Alternativa si no encaja
Si vendés sobre todo en LatAm sin presencia en Brasil, Mercado Pago suele cobrar menos comisión y aceptar más métodos locales.
Países donde brilla
Si tus clientes están concentrados en LatAm y necesitás métodos locales agrupados sin tener que integrar 5 proveedores distintos.
Métodos locales que soporta
Cuándo elegirlo
La mejor relación cobertura/comisión para LatAm. Incluye tarjeta + efectivo + transferencia + QR en un solo SDK.
Alternativa si no encaja
Si vendés solo en Colombia, Wompi suele ser más simple y barato. Si querés OXXO sin pelear con Mercado Pago México, Stripe también lo soporta.
Países donde brilla
Si tu negocio está enfocado al 100% en Colombia y querés un proveedor local con dashboard en español y soporte directo.
Métodos locales que soporta
Cuándo elegirlo
Cuando tus clientes pagan sobre todo con Nequi o PSE, Wompi es más fluido que Mercado Pago. Comisiones competitivas para volumen colombiano.
Alternativa si no encaja
Si planeás expandirte a México o Brasil pronto, Mercado Pago te ahorra una migración futura.
Países donde brilla
Si vendés productos digitales (cursos, software, ebooks) a clientes de cualquier país y no querés lidiar con VAT, IVA o sales tax.
Métodos locales que soporta
Cuándo elegirlo
Lemon Squeezy actúa como Merchant of Record · te cobra una comisión más alta pero se hace cargo de todos los impuestos del mundo. Vos cobrás neto, ellos pelean con cada autoridad fiscal.
Alternativa si no encaja
Si vendés productos físicos o necesitás suscripciones B2B complejas, Stripe te da más control.
05 los 14 archivos
Estos son los archivos que escribe PagoKit en un proyecto Next.js App Router con Prisma como ORM (el caso más común). Para Express o stacks con otro ORM, los nombres cambian pero la lógica es la misma. Cada archivo está agrupado por dónde vive y qué hace.
1 archivo
Componentes UI que se renderizan en el browser.
components/CheckoutButton.tsxEl botón que tus clientes ven en la página. Cuando lo aprietan, llama al endpoint de checkout y los redirige a la pasarela del proveedor.
7 archivos
Rutas en el server que reciben requests del cliente o del proveedor.
app/api/checkout/route.tsEl endpoint que crea la sesión de pago. Recibe el carrito o el producto, llama al proveedor (Stripe, Mercado Pago, etc.) y devuelve la URL a la que redirigir al cliente.
app/api/webhook/stripe/route.tsEl endpoint que escucha al proveedor cuando alguien paga. Verifica que el mensaje sea legítimo (firma criptográfica), actualiza el estado en tu base de datos y dispara emails o accesos.
app/api/portal/route.tsEl endpoint que abre el portal del cliente · donde tus usuarios pueden ver sus facturas, actualizar su tarjeta o cancelar la suscripción sin escribirte.
app/api/refund/route.tsEl endpoint para devolver un pago. Lo llamás desde tu admin cuando un cliente pide reembolso · se conecta al proveedor, ejecuta el refund y actualiza el estado en tu DB.
lib/payments/stripe.tsEl cliente del proveedor configurado correctamente · con las API keys leídas del `.env`, retries en caso de fallo de red y los tipos del SDK. Tus rutas lo importan en vez de instanciar el SDK en cada lugar.
lib/payments/errors.tsTipos y helpers para manejar errores del proveedor de forma consistente · `CardDeclined`, `WebhookSignatureInvalid`, `RateLimited`. Tu UI sabe qué mostrarle al cliente según el tipo de error.
lib/payments/utils.tsHelpers comunes · generar IDs idempotentes (uno de los 5 candados), formatear amounts con la moneda correcta, parsear webhooks. Centralizado para que no se duplique lógica.
2 archivos
Cliente de DB y schema de tablas necesarias para pagos.
lib/db.tsEl cliente de la base de datos (Prisma, Drizzle o lo que tengas) configurado y exportado como singleton, para no abrir múltiples conexiones por request.
prisma/schema.prismaEl esquema de tu base de datos con las tablas que faltan para pagos · `Payment`, `Subscription`, `Customer`, `WebhookEvent`. Si ya tenés un schema, PagoKit hace merge sin tocar lo tuyo.
4 archivos
Archivos `.md` y configuración con instrucciones para vos.
.env.exampleEl template de variables de entorno que necesita tu proyecto · API keys del proveedor, secret del webhook, URL del portal, etc. Te dice exactamente dónde sacar cada valor del dashboard del proveedor.
.gitignore (parche)Si tu `.gitignore` no incluye `.env`, PagoKit lo agrega automáticamente. Es uno de los 5 candados deterministas · sin eso, el commit se bloquea.
PAGOKIT_INTEGRATION.mdEl manual personalizado de tu integración · qué decidió PagoKit por vos, qué archivos creó, dónde están las API keys del proveedor que elegiste, y cómo testear el flujo end-to-end.
PAGOKIT_PRODUCTION_CHECKLIST.mdLa checklist final antes de pasar a producción · cambiar las test keys por live keys, activar el webhook en el dashboard del proveedor, configurar dominio para los emails de recibo, probar un refund de prueba.
Si tu stack no es Next.js + Prisma
Los nombres y rutas cambian según tu framework y ORM · por ejemplo, en Express los endpoints quedan en `routes/`, con Drizzle el schema vive en `drizzle/schema.ts`, con SQLAlchemy en `models.py`. Pero la cantidad de archivos y la lógica detrás es la misma · PagoKit adapta los outputs a tu proyecto, no al revés.
06 los 5 candados
PagoKit no solo escribe el código · también pone 5 candados deterministas que se ejecutan en cada acción de Claude Code. Si intentás violar uno (publicar una API key, escribir un webhook sin firma, etc.), el commit se bloquea. No es una sugerencia · es un hook PostToolUse que falla hard.
Qué protege
Evita que termines publicando una clave secreta de Stripe (o cualquier proveedor) directo en el código fuente.
Cómo funciona
Escanea cada archivo modificado buscando patrones de API keys reales (sk_live_*, prod_*, etc.). Si encuentra una, bloquea el commit y te indica el archivo y la línea para que la muevas al `.env`.
Qué protege
Evita que termines pusheando el archivo con tus secretos a GitHub. Es el error más común y el más caro · una vez que está en el historial, asumí que tus keys ya están comprometidas.
Cómo funciona
Antes de cualquier commit, verifica que `.env` esté listado en `.gitignore`. Si no está, lo agrega automáticamente o falla con instrucciones claras.
Qué protege
Evita que cualquiera con tu URL de webhook simule un pago y desbloquee accesos premium en tu app sin haber pagado nada.
Cómo funciona
Inspecciona cada endpoint webhook generado y exige que llame al método de verificación de firma del proveedor (Stripe.webhooks.constructEvent, MercadoPago.signatureVerify, etc.) antes de procesar el body.
Qué protege
Evita doble cobro si una request se reintenta. Si Stripe te manda el mismo evento dos veces (cosa que pasa), tu DB no genera dos rows de pago.
Cómo funciona
Cada operación de cobro y refund usa un idempotency key generado como UUID v4 desde el cliente, persistido en la tabla `Payment`. El segundo intento con la misma key devuelve el resultado del primero sin re-ejecutar.
Qué protege
Evita que tu webhook rechace pagos legítimos porque Express ya parseó el JSON y la firma deja de verificar. Es un bug clásico que cuesta horas debuguear.
Cómo funciona
Configura el middleware de raw body solo en las rutas de webhook (`bodyParser.raw({ type: 'application/json' })` o el equivalente Next.js). El body se preserva tal cual llegó y la firma valida bien.
Además de los 5 deterministas · 7 reglas guía
Además de los 5 candados deterministas (que bloquean el commit), PagoKit trae 7 reglas guía no-bloqueantes que te avisan si estás haciendo cosas raras · sin replay protection en el webhook, sin límite de body size, logueando datos sensibles (PII), usando live keys en desarrollo. No te frenan, pero te dejan un comentario en el código.
Escape hatch · cuando tenés que saltarte una regla
Si necesitás saltarte una regla por una razón legítima · por ejemplo, un caso de uso muy específico que el candado no contempla · podés agregar el comentario `// pagokit-ignore: <nombre-regla> -- <tu-razón>` en la línea problemática. PagoKit lo deja pasar pero queda registrado en `.pagokit/audit.log` con tu razón, para que un futuro vos (o cualquier otra persona del equipo) sepa por qué se desactivó.
07 stacks soportados
PagoKit cubre Fase 1 hoy · Next.js App Router y Express con sus ORMs más comunes. Si tu stack está más allá, el plugin todavía no te puede ayudar end-to-end · pero el roadmap es público y vas a poder revisar el progreso desde el repo.
Soportado
Roadmap
Roadmap
Si tu stack está en Fase 2 o 3
Si tu stack está en Fase 2 o Fase 3, PagoKit todavía no te puede ayudar end-to-end · escanea el proyecto y te avisa con honestidad que tu framework no está soportado todavía. Si tu ORM ya está soportado (Prisma, Drizzle, SQLAlchemy) pero tu framework no, podés esperar a la versión que lo cubra o usar la integración manual del proveedor mientras tanto.
08 cómo integrarlo bien
Instalar PagoKit es fácil · usarlo bien tiene 5 pasos que la gente saltea y después se quema. Acá va el playbook en orden, sin código, en lenguaje de la vida real.
Antes de instalar nada, tené claro qué vas a cobrar · ¿es un producto único, una suscripción, una mezcla? ¿Cuánto cuesta? ¿En qué monedas? ¿De dónde son la mayoría de tus clientes? PagoKit te va a preguntar estas cosas y mientras más honestamente respondas, mejor te elige el proveedor.
Antes de correr `/pagokit:start`, andá al dashboard del proveedor que pensás usar (Stripe, Mercado Pago, etc.) y sacá tus test keys. Esto es importante · PagoKit genera el código pero las keys las pegás vos en el `.env`. Nunca uses live keys en desarrollo.
No infles datos · si vas a vender en LatAm pero pensás 'algún día expansión a EE.UU.', respondé LatAm. Después siempre podés cambiar de proveedor con un nuevo `/pagokit:start` · pero hoy elegí lo que necesitás hoy. PagoKit toma menos de un minuto en escribir todos los archivos.
El primer archivo que abre es el manual personalizado · te dice qué proveedor eligió, qué archivos creó, dónde pegar las API keys, qué variables de entorno faltan, y cómo testear el flujo completo en local. Leelo entero · son 5 minutos y te ahorra horas.
Cuando ya probaste en test mode y todo anda, abrís la segunda doc · es la checklist para pasar a producción. Cambiar test keys por live keys, configurar el webhook en el dashboard del proveedor con la URL real, activar el dominio de los emails, hacer un cobro real de $1 USD y un refund para verificar el flujo completo. Sin saltarte pasos.
Antes de poner el botón en vivo · revisá los candados
Los 5 candados deterministas se mantienen activos · si en algún momento te tentaste de pegarle un pagokit-ignore a uno de ellos para sacar el commit más rápido, volvé a la sección de seguridad y revisá si valió la pena. El audit log queda escrito y tu vos del futuro te va a agradecer haber hecho lo correcto.
09 cuándo NO usarlo
PagoKit no es para todo el mundo · estos son los casos donde no tiene sentido instalarlo y mejor seguís con lo que ya tenés (o vas directo a la doc del proveedor).
Ya tenés Stripe, Mercado Pago u otro proveedor integrado y andando · PagoKit no migra integraciones existentes · es para empezar de cero. Si tu integración actual funciona, no te metas a romperla.
Tu stack está en Fase 2 o Fase 3 del roadmap (NestJS, FastAPI, Django, Laravel, Rails, Hono, SvelteKit, Astro, Go) · esperá la versión que cubra tu framework o usá la doc oficial del proveedor.
Necesitás un método de pago específico que no está en los 4 proveedores soportados (por ejemplo, criptomonedas, ACH directo sin Stripe, transferencias bancarias custom) · PagoKit no improvisa · mejor integrá directo el SDK del proveedor que necesitás.
Estás en una empresa con un equipo de pagos dedicado y un sistema de seguridad propio · los candados deterministas pueden chocar con tu pipeline interno. Pedile a tu CTO antes de meter cualquier plugin a un repo corporativo.
Si ninguno de estos casos es el tuyo
Andá tranquilo · PagoKit fue hecho para vos. Volvé a la sección de instalación y arrancás con el primer comando. Si te trabás en algún punto, abrí un issue en el repo · respondo todos.
Guía de la comunidad
Esta guía es el manual completo de PagoKit, un plugin gratis de Claude Code hecho para la comunidad. Es parte de la bóveda de tododeia, una colección libre de recursos para quienes construyen con Claude todos los días.
Cierre personal
“Hice PagoKit porque me cansé de ver gente que tenía su producto listo · su landing pulida · su comunidad armada · y se quedaba trabada un mes entero peleándose con Stripe o Mercado Pago. El método de pago no debería ser el cuello de botella entre tu proyecto y tus primeros clientes. Si esta guía te sirvió, instalalo y mandame qué proyecto estás construyendo · me gusta ver dónde termina ayudando.”
Repo de PagoKit · GitHub
El código fuente del plugin, el README completo, las issues abiertas y los releases. MIT · libre para forkear y proponer cambios.
Claude Code · documentación oficial de plugins
La doc de Anthropic sobre cómo funcionan los plugins de Claude Code 2.x. Útil si querés entender qué hace `--plugin-dir` por debajo o construir tu propio plugin.
Stripe · API reference
La referencia oficial de Stripe. Útil cuando PagoKit te genera el endpoint pero querés profundizar en algún parámetro específico (custom fields del checkout, metadata, etc.).
Mercado Pago · docs
La documentación oficial de Mercado Pago en español. Si tu proveedor elegido fue MP, acá están las guías por país.
Guías hermanas que cruzan con esta
Cómo crear tus propios skills de Claude
PagoKit es un plugin con varios skills adentro. Si te interesó el patrón, esta guía te muestra cómo crear tus propios skills paso a paso · para automatizar otras tareas más allá de pagos.
5 herramientas gratis para Claude Code 2026
El hub de las 5 herramientas top-tier del ecosistema (Superpowers, ECC, UI UX Pro Max, claude-mem, n8n-MCP). PagoKit es complementario · estas son las herramientas base que vale la pena tener instaladas siempre.
Los 3 modelos de Claude · Haiku, Sonnet, Opus
Antes de instalar PagoKit, vale la pena saber qué modelo de Claude estás usando. Si corrés Opus para todo, esta guía te explica cuándo bajar a Sonnet o Haiku para ahorrar tokens.
Cómo instalar Claude Code · paso a paso
Si no tenés Claude Code instalado todavía, arrancá por acá. PagoKit requiere Claude Code 2.x y Node ≥ 18 · esta guía cubre todo el setup desde cero.
Memoria persistente en Claude Code
PagoKit funciona mejor cuando Claude se acuerda de tu proyecto entre sesiones. Esta guía cubre claude-mem · cómo darle memoria a largo plazo para que no repita preguntas que ya respondiste antes.
Por dónde empezar si llegaste sin saber nada
Por dónde empezar si nunca tocaste un método de pago · (1) si recién estás aprendiendo Claude Code, primero leé instalar-claude-code y aprende-skill para entender qué es un plugin, (2) decidí de dónde son tus clientes y qué vas a cobrar antes de instalar nada · la peor optimización es montar Stripe cuando tus clientes están todos en México, (3) clavá las API keys del proveedor en test mode antes de correr `/pagokit:start` · sin las keys el agente igual escribe el código pero no podés probar nada, (4) leé los dos archivos `.md` que te genera (INTEGRATION y PRODUCTION_CHECKLIST) · son los más importantes de los 14 y casi todos los saltan, (5) cuando todo funciona en test, hacés UN cobro real de $1 USD y un refund antes de poner el botón en vivo · si eso funciona, ya estás.
Para quién no aplica esta página
Para quién no aplica este plugin · si ya tenés Stripe o Mercado Pago integrado y andando, no lo cambies por PagoKit · está hecho para arrancar de cero, no para migrar. Si tu stack es Django, Laravel, Rails, FastAPI o cualquier otro fuera de Fase 1, todavía no podés usarlo end-to-end · esperá los próximos releases o pegale directo al SDK del proveedor mientras tanto. Si trabajás en una empresa con políticas estrictas de seguridad y aprobación de dependencias, pasale el repo a tu CTO antes de instalarlo en un repo corporativo · los candados deterministas modifican el commit flow y eso puede chocar con tu CI.