Integración de pagos con Claude Code: Stripe + Sepay de la A a la Z (2026)

¿Por qué usar Claude Code para integrar pagos?

La integración de pagos es ese tipo de trabajo repetitivo pero fácil de equivocar: crear una ruta de checkout, manejar la redirección, escribir un webhook, verificar firmas, guardar pedidos y cubrir cada caso de prueba. Hacerlo a mano desde la documentación se come una tarde entera, y perder un solo detalle (digamos, un webhook que no es idempotente) puede cobrarle dos veces a un cliente.

La fuerza de Claude Code aquí es que actúa como un constructor, no solo como quien sugiere código. En una sola sesión lee la estructura de tu repositorio, averigua si estás en el App Router o en Express, luego genera la ruta de API correcta, produce un handler de webhook que coincide con el payload de la pasarela y ejecuta los comandos de prueba directo desde tu terminal. Pasar de "unas horas escarbando en la documentación" a "unos minutos revisando un diff" es una diferencia real, sobre todo cuando tienes que conectar Stripe y Sepay a la vez. Si todavía no has dejado que Claude Code escriba una API, lee primero nuestra guía sobre construir una API de backend con Claude Code para aprender a orientarlo bien.

Pero lo digo claro desde el principio: los pagos involucran dinero de verdad, así que una persona todavía tiene que revisar cada línea. Claude Code puede verificar la unidad de moneda equivocada, saltarse un caso límite o sugerir una API obsoleta. Trátalo como un dev júnior rápido: quien firma al final sigues siendo tú. El principio que recorre todo este artículo: la IA construye, tú verificas.

Elegir una pasarela: Stripe vs Sepay vs Polar

Elige tu pasarela antes de escribir un prompt, porque cada una tiene su propio flujo y payload. Tres opciones populares para quienes desarrollan atendiendo a clientes vietnamitas y globales:

La recomendación corta: para clientes vietnamitas, usa Sepay (VietQR/NAPAS, el cliente escanea un código para transferir y el dinero cae en tu cuenta bancaria); para clientes internacionales que pagan con tarjeta, usa Stripe; para vender SaaS a nivel global cuando prefieres no lidiar con impuestos, usa Polar, ya que actúa como Merchant of Record y gestiona el IVA por ti. Muchas apps corren Stripe y Sepay en paralelo: los clientes del exterior pasan por Stripe, los clientes locales pasan por VietQR. Este artículo profundiza en esas dos pasarelas; el flujo de Polar es parecido al de Stripe (tiene su propio adaptador para Next.js).

Qué preparar antes de empezar

Una lista de verificación antes de que abras Claude Code (échale un vistazo rápido y completa lo que falte):

• Una app Next.js o Node/Express que ya corra localmente.
• Una cuenta de Stripe en modo de prueba, o una cuenta de Sepay en sandbox (las claves tienen forma de SP-TEST-*).
• Claves secretas guardadas en .env y nunca commiteadas — agrega .env a .gitignore primero.
• Claude Code instalado y un CLAUDE.md en el repositorio que describa tu stack y tus convenciones (lo usamos más abajo).
• Un endpoint público para que la pasarela llame al webhook — en local usa el Stripe CLI o un túnel; en producción usa HTTPS de verdad.

Manejar claves secretas es la parte más frágil de la seguridad de pagos, así que lee también sobre gestionar los permisos de Claude Code de forma segura para no dejar sin querer que el agente lea o imprima un secreto en los logs.

Cómo orientar a Claude Code en el trabajo de pagos

La calidad de la salida depende casi por completo de cómo orientas. Para pagos, las dos cosas que más importan son el contexto en CLAUDE.md y un prompt específico.

Agrega unas líneas de contexto así a CLAUDE.md para que Claude Code no tenga que adivinar:

# Payment context
- Stack: Next.js 15 App Router, TypeScript, Prisma + PostgreSQL
- Gateways: Stripe (international) + Sepay/VietQR (VN customers)
- Env: all secrets live in .env, NEVER commit, NEVER print to logs
- Convention: use Stripe Checkout Sessions only, NO legacy Charges/Card Element
- Safety: NEVER run production commands, NEVER refund; test mode/sandbox only

Luego, el prompt. Compara un vago "intégrame Stripe" con uno específico:

Read app/ and prisma/schema.prisma. Create a POST route app/api/checkout/route.ts
that creates a Stripe Checkout Session (mode payment) from the priceId in the body
and returns session.url. Use the existing env vars. Do not touch other files.
Then document a Stripe CLI test in the README; do not run any live commands.

Un prompt específico mantiene los cambios de Claude Code acotados, usa tu esquema de base de datos real y le impide "inventar" archivos de más. También puedes apuntarlo a la documentación de la pasarela vía fetch/MCP (documentación de Stripe, developer.sepay.vn) para que siga la API más reciente en lugar de la memoria desactualizada.

El flujo de Stripe con Claude Code (clientes internacionales)

El flujo moderno de Stripe cabe en cuatro pasos. Prefiere las Checkout Sessions (alojadas por Stripe) y evita los antiguos Charges/Card Element, ya que están desactualizados y aumentan tu carga de PCI.

1. Ruta para crear una Checkout Session. Orienta a Claude Code para generar una ruta que reciba un priceId, cree la sesión y devuelva session.url para que el cliente redirija.
2. Redirección de éxito/cancelación. Pasa success_url y cancel_url; no marques un pedido como "pagado" en la página de éxito — espera el webhook.
3. Webhook checkout.session.completed. Verifica la firma con constructEvent antes de manejar cualquier lógica de negocio.
4. Prueba con el Stripe CLI directo en tu máquina local, sin necesidad de deploy.

// app/api/checkout/route.ts
import { NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
 const { priceId } = await req.json();
 const session = await stripe.checkout.sessions.create({
 mode: "payment",
 line_items: [{ price: priceId, quantity: 1 }],
 success_url: `${process.env.APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
 cancel_url: `${process.env.APP_URL}/cancel`,
 });
 return NextResponse.json({ url: session.url });
}

// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
 const body = await req.text(); // raw body is required to verify
 const sig = req.headers.get("stripe-signature")!;
 let event: Stripe.Event;
 try {
 event = stripe.webhooks.constructEvent(
 body, sig, process.env.STRIPE_WEBHOOK_SECRET!
 );
 } catch {
 return new Response("Invalid signature", { status: 400 });
 }
 if (event.type === "checkout.session.completed") {
 // idempotent: check whether event.id was already processed before writing the order
 }
 return new Response("ok", { status: 200 });
}

Prueba en local con dos comandos, a costo cero:

stripe listen --forward-to localhost:3000/api/webhooks/stripe
stripe trigger checkout.session.completed

Para el flujo completo de puesta en producción y la lista oficial, mira la documentación de Stripe (docs.stripe.com, consultado en 08/2026) — confirma la versión de la API en producción antes de publicar, ya que Stripe la actualiza con frecuencia.

El flujo de Sepay/VietQR con Claude Code (clientes de Vietnam)

Sepay encaja bien con clientes vietnamitas: generas un código VietQR o una cuenta virtual, el cliente escanea y transfiere, y Sepay dispara un webhook confirmando que el dinero llegó. El flujo en cuatro pasos:

1. Crea el pedido y genera el VietQR (o cuenta virtual) para ese pedido, con una nota de transferencia que puedas conciliar después.
2. El cliente escanea el QR y transfiere a través de su app bancaria.
3. El webhook de Sepay reporta la transacción con transferType: "in", junto con transferAmount, content y referenceCode.
4. Verifica, elimina duplicados y devuelve {"success": true} en menos de 5 segundos para que Sepay no reintente.

// app/api/webhooks/sepay/route.ts
import { db } from "@/lib/db";

export async function POST(req: Request) {
 const auth = req.headers.get("authorization");
 if (auth !== `Apikey ${process.env.SEPAY_API_KEY}`) {
 return new Response("Unauthorized", { status: 401 });
 }
 const data = await req.json();
 // data: { id, transferType, transferAmount, content, referenceCode }
 if (data.transferType !== "in") {
 return Response.json({ success: true }); // ignore outgoing transactions
 }
 const existed = await db.transaction.findUnique({
 where: { sepayId: data.id },
 });
 if (existed) return Response.json({ success: true }); // dedupe by id
 await db.transaction.create({
 data: {
 sepayId: data.id,
 amount: data.transferAmount,
 content: data.content,
 ref: data.referenceCode,
 },
 });
 // TODO: reconcile content with the order, then update its status to "paid"
 return Response.json({ success: true });
}

Guardar transacciones y conciliarlas con los pedidos debería vivir de forma ordenada en la capa de datos — mira cómo almacenar pedidos y transacciones con una base de datos para diseñar tablas de pedidos/transacciones prolijas. Sepay tiene su propio sandbox y un límite de 2 req/s, así que basta con dejar que Claude Code lea la documentación oficial (developer.sepay.vn, consultado en 08/2026) para ceñirse al endpoint y al payload correctos.

Webhooks e idempotencia — la parte más fácil de errar

Aquí es donde los tutoriales manuales se saltan pasos, y también donde el daño es peor. Las pasarelas de pago no garantizan que un webhook se entregue exactamente una vez: redes inestables, timeouts y reintentos hacen que el mismo evento llegue varias veces. Si tu handler no es idempotente, escribes pedidos duplicados, acreditas un saldo dos veces o envías un artículo dos veces.

La regla: elimina duplicados por el identificador del evento. Para Sepay, es el id de la transacción; para Stripe, es el event.id. Guarda el id procesado (un índice único en la base) y sáltalo si ya lo viste antes. Para casos más complejos, usa una clave compuesta (por ejemplo, orderId más el tipo de evento).

Restricciones de tiempo y de reintento que conviene recordar:

• Sepay: el handler debe devolver 2xx en menos de 5 segundos; de lo contrario, Sepay reintenta automáticamente hasta 7 veces a lo largo de aproximadamente 5 horas en un calendario de Fibonacci. Eso significa que la misma transacción puede llegar 7 veces — eliminar duplicados es obligatorio.
• Stripe: reintenta con su propio calendario cuando no recibe un 2xx; aun así necesitas eliminar duplicados por el event.id.

Un consejo práctico: guarda el evento primero, procesa la lógica de negocio después. Escribe el registro del evento (de forma idempotente), luego ejecuta la lógica pesada en un paso aparte, para que, si la lógica falla, un reintento siga siendo seguro. Este es un buen momento para pedirle a Claude Code que escriba una prueba para el caso del "webhook que llega dos veces" — suele olvidarlo a menos que se lo recuerdes.

Pruebas y seguridad antes de salir a producción

Antes de encender el dinero de verdad, repasa esta lista (es también lo que los tutoriales manuales suelen dejar fuera):

Pruebas:

• Stripe: usa el Stripe CLI (stripe listen/stripe trigger) y tarjetas de prueba; sin dinero real de por medio.
• Sepay: usa el sandbox con claves SP-TEST-*; simula una transacción entrante y comprueba el webhook.
• Prueba los casos de falla: firma inválida, webhook llegando dos veces, monto que no coincide con el pedido.

Seguridad:

• Nunca expongas tu clave secreta — solo en el servidor, nunca en el bundle del cliente, nunca impresa en los logs.
• Verifica cada webhook: Stripe mediante la firma HMAC (constructEvent), Sepay mediante el header de API Key Authorization: Apikey ....
• Exige HTTPS en producción; considera poner el endpoint del webhook en una allowlist de IP.
• Usa solo Checkout Sessions / PaymentIntents / SetupIntents; evita los antiguos Sources/Tokens/Charges para reducir tu alcance de PCI. Si tocas un PAN en crudo, caes en el cubo complejo de cumplimiento de PCI — no lo hagas.

Salida a producción: Stripe tiene su propia lista de go-live (cambiar a claves live, configurar webhooks de producción). Sepay exige aprobación de NAPAS QR/tarjeta, normalmente de 3 a 7 días — reserva tiempo para eso. Antes de publicar, haz una pasada más de una revisión de seguridad y auditoría con Claude Code para atrapar fugas de claves y huecos de verificación.

Publica mucho más rápido con una skill lista (AgentKit)

Si prefieres no escribir cada handler a mano, hay un camino más rápido: la skill ak-payment-integration del AgentKit Engineer Kit. Esta skill ya empaqueta las tres pasarelas — SePay, Polar y Stripe — cubriendo checkout, verificación de webhook (con scripts listos), QR, suscripciones y pedidos con múltiples proveedores, así que Claude Code solo la activa y construye en minutos, en lugar de escarbar en la documentación de cada pasarela.

Una línea para evitar confusiones: el AgentKit de aquí es el kit para Claude Code en agentkit.best (20% de descuento por el enlace) (el CLI ak), no el AgentKit de OpenAI. El Engineer Kit cuesta $99 (el sitio no lista ninguna cuota recurrente). Si quieres ver qué resuelve de verdad esta skill, lee la reseña detallada del Engineer Kit y qué es AgentKit antes de decidir — no compres por una sola skill si solo necesitas un flujo.

Límites y precauciones cuando dejas que la IA toque el dinero

Los pagos están cerca de YMYL, así que esta sección importa tanto como el código. Algunos límites firmes cuando dejas que Claude Code maneje pagos:

• Revisa siempre el código relacionado con dinero. Lee con cuidado los cálculos de montos, las conversiones de unidades y las condiciones que actualizan el estado de un pedido.
• No dejes que el agente ejecute comandos de producción o reembolsos por su cuenta. Mantén a Claude Code en modo de prueba/sandbox; los comandos live los aprietas tú misma después de revisar.
• Verifica montos y unidades. Stripe cuenta en la unidad más pequeña (centavos); el VND no tiene decimales — es aquí donde la IA suele resbalar en las conversiones.
• Prueba a fondo los casos límite del webhook (llegando dos veces, firma equivocada, monto que no coincide) y conserva los logs para conciliar cuando surja una disputa.

En resumen: la IA te ayuda a moverte rápido, pero la responsabilidad por el dinero sigue siendo tuya. La velocidad no sustituye una revisión hecha con la cabeza fría.

Preguntas frecuentes (FAQ)

¿Claude Code integrará los pagos por completo por mí?

Construye la mayor parte: lee el repositorio, genera la ruta de checkout, escribe el handler del webhook y escribe pruebas. Pero todavía tienes que revisar el código, registrarte tú misma en la pasarela, configurar las claves de producción y apretar el comando de go-live. Como hay dinero de por medio, la persona es la que da la aprobación final.

Para clientes vietnamitas, ¿debo elegir Stripe o Sepay?

Para clientes de Vietnam que pagan en VND, Sepay encaja mejor gracias a VietQR/NAPAS, a las transferencias entre más de 44 bancos y a que el dinero cae directo en tu cuenta bancaria. Stripe encaja cuando vendes internacionalmente y aceptas tarjeta de crédito. Muchas apps corren ambas en paralelo.

¿Qué hago si el webhook nunca recibe una transacción?

Comprueba que el endpoint sea público y HTTPS, que la verificación de firma/API Key sea correcta y que el handler devuelva 2xx en menos de 5 segundos. Sepay reintenta automáticamente hasta 7 veces a lo largo de aproximadamente 5 horas, así que, si tu handler es idempotente, un reintento posterior lo registra igual correctamente.

¿Cómo pruebo el flujo de pago sin gastar dinero de verdad?

Usa el modo de prueba: Stripe tiene el Stripe CLI (stripe listen/stripe trigger) y tarjetas de prueba; Sepay tiene un sandbox con claves SP-TEST-*. Ambos te dejan simular transacciones y webhooks sin tocar dinero real.

¿Puedo seguir este artículo si no soy buena programando?

Necesitas conocimientos básicos de programación para leer y revisar los diffs que produce Claude Code — como hay dinero en juego, no deberías hacer merge de código que no entiendes. Claude Code recorta la cantidad de tipeo manual, pero la capacidad de leer y entender el código sigue siendo esencial.

¿En qué se diferencia la skill ak-payment-integration de escribirlo a mano?

Escribir a mano te da control sobre cada línea, pero cuesta tiempo escarbando en la documentación de tres pasarelas. La skill ak-payment-integration empaqueta checkout, verificación de webhook, QR y suscripciones para SePay/Polar/Stripe, lo que construye más rápido; a cambio, aún deberías revisar la salida, ya que cada app tiene su propia lógica de negocio.

Conclusión y próximos pasos

Recapitulando los cinco pasos: elegir una pasarela (Stripe para internacional / Sepay para clientes de Vietnam), orientar a Claude Code con un CLAUDE.md, crear el checkout, escribir un webhook idempotente y luego probar y reforzar antes de salir a producción. Los puntos que lo definen todo son los webhooks idempotentes y una revisión humana, porque esto es dinero de verdad. Desde aquí, puedes pasar a construir una API de backend completa o ajustar una auditoría de seguridad antes del lanzamiento.