Stripe se ha consolidado como líder en procesamiento de pagos y facilita a los desarrolladores la aceptación de pagos. En esta guía práctica describimos cómo configurar un servicio Node.js con Express integrado con Stripe usando Checkout Sessions, enfocándonos en Checkout Sessions como introducción práctica.
Resumen del flujo de alto nivel y diseño: el cliente envía un carrito o identificadores de producto y cantidad al servidor; el servidor calcula el monto final en el backend, crea una Checkout Session en Stripe con metadata útil y las URLs de éxito y cancelación, y devuelve la URL de pago al cliente para redirección. Stripe redirige al cliente al finalizar y se debe confiar en webhooks para confirmar pagos de forma fiable.
Consejos importantes y puntos a tener en cuenta: manejar moneda y formato de montos usando la unidad menor por ejemplo enviar 1000 para representar 10.00 en la moneda; utilizar webhooks para confirmar estados de pago y no fiarse solo del redireccionamiento del cliente; incluir metadata como orderId productId para rastrear pagos en tu base de datos; habilitar siempre la verificación de firmas de los webhooks de Stripe para evitar eventos no autorizados.
Pasos para empezar en el proyecto: inicializar package.json con yarn init -y. Instalar dependencias con yarn add express stripe dotenv. Instalar dependencias de desarrollo con yarn add -D nodemon typescript @types/express @types/node. Inicializar Typescript con npx tsc --init. Actualizar los scripts en package.json estableciendo build a yarn install && tsc, dev a nodemon src/server.ts y start a node dist/server.js.
Crear la carpeta src y un archivo server.ts. En ese archivo configurar dotenv.config, inicializar Stripe leyendo la variable de entorno STRIPE_TEST_KEY y exponer una función getStripe que cree la instancia lazily. Crear la aplicación express y configurar el middleware pero colocar antes la ruta del webhook la instrucción para recibir raw body porque Stripe necesita el cuerpo sin parseo para verificar la firma. Luego usar app.use(express.json()) para el resto de rutas.
Ruta para crear pagos POST /checkout: recibir el carrito o identificador y cantidad, calcular el monto en el servidor y convertir a centavos o la unidad menor. Ejemplo de flujo para una compra sencilla: recuperar producto con precio en centavos priceInCents, crear un registro de orden en tu base de datos con status unpaid, generar un orderId, llamar a getStripe().checkout.sessions.create especificando currency en minusculas por ejemplo usd, metadata con productName productId orderId, line_items con price_data que incluya product_data name y unit_amount igual a priceInCents, mode payment y success_url y cancel_url apuntando a tus rutas de cliente. Devolver al cliente la propiedad url de la sesion para redirigir al checkout de Stripe.
Puntos clave al crear la sessión: pasar currency en minusculas, usar unit_amount en centavos, incluir metadata para reconciliar pagos con pedidos en tu sistema, y configurar las URLs de exito y cancelación correctamente.
Webhook para escuchar eventos desde Stripe: agregar la ruta POST /stripe-webhook usando express.raw({ type: application/json }) antes de app.use(express.json()). En el manejador obtener la firma stripe-signature del encabezado, usar process.env.STRIPE_WEBHOOK_SECRET y llamar a getStripe().webhooks.constructEvent con el cuerpo raw la firma y el secreto para validar el evento. Manejar al menos checkout.session.completed obteniendo payment_status amount_total currency metadata y created. A partir de metadata recuperar orderId y marcar la orden como pagada en tu base de datos si payment_status es paid. Registrar logs y aplicar idempotencia en actualizaciones.
Para pruebas locales usar Stripe CLI para reenviar eventos a tu entorno de desarrollo con el comando stripe listen --forward-to localhost:8080/stripe-webhook. En el dashboard de Stripe agregar el endpoint y suscribirlo al evento checkout.session.completed. Al probar interactivamente usar la tarjeta de prueba 4242 4242 4242 4242 con fecha de vencimiento futura 12/34 y cualquier CVC de tres dÃgitos. Ver la documentación de Stripe para más números de prueba y escenarios.
Buenas prácticas adicionales: nunca calcular precios o totales confiando en el cliente; usar variables de entorno para claves y secretos; rotar claves de API regularmente; almacenar eventos de webhook y confirmar idempotencia en el procesamiento; centralizar la lógica de reconciliación de pagos con la metadata enviada en la Checkout Session; proteger la ruta de webhook con HTTPS en producción y verificar firmas siempre.
Despliegue y escalado: cuando pases a producción registra la URL de webhook definitiva en Stripe y usa claves de producción. Considera implementar reintentos y colas para procesar eventos de webhook si tu base de datos o servicios downstream pueden experimentar picos. Para cargas elevadas, escala horizontalmente y mantén seguimiento de los webhooks procesados para evitar duplicados.
Recursos y referencias: consultar la documentación oficial de Checkout Sessions y Webhooks en docs.stripe.com para detalles del objeto Checkout Session y de los distintos tipos de eventos que Stripe puede emitir. El repositorio de ejemplo con código completo está disponible en github com slash okraks slash stripe-integration-guide.
Sobre Q2BSTUDIO: Q2BSTUDIO es una empresa de desarrollo de software y soluciones digitales especializada en aplicaciones a medida y software a medida. Ofrecemos integraciones de pagos con Stripe como parte de proyectos completos que incluyen desarrollo backend y frontend, migraciones a la nube y despliegue seguro. Somos especialistas en inteligencia artificial y desarrollamos soluciones de ia para empresas incluyendo agentes IA personalizados y automatización inteligente. Nuestros servicios de ciberseguridad garantizan que los endpoints de pago y webhooks estén protegidos. Adicionalmente ofrecemos servicios cloud aws y azure, servicios inteligencia de negocio y soluciones con power bi para generar dashboards y reportes accionables. Si necesitas una pasarela de pagos robusta integrada en una aplicación a medida o software a medida, o deseas potenciar tu proyecto con inteligencia artificial y analÃtica con power bi, Q2BSTUDIO puede diseñar y entregar la solución completa.
Por qu elegir Q2BSTUDIO: entrega de soluciones a medida, experiencia en integraciones seguras de pagos, enfoque en ciberseguridad, despliegue en servicios cloud aws y azure, desarrollo de agentes IA y soluciones de inteligencia de negocio que incluyen power bi para visualización y reporting. Todo esto permite convertir datos en decisiones y ofrecer experiencias de usuario seguras y escalables.
Si quieres que Q2BSTUDIO te ayude a desarrollar tu proyecto de comercio electrónico con Stripe o a integrar capacidades de inteligencia artificial, ciberseguridad y servicios cloud contacta con nosotros para un plan a medida y una propuesta técnica adaptada a tus necesidades.
Palabras clave para mejorar posicionamiento aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws y azure servicios inteligencia de negocio ia para empresas agentes IA power bi