VOXIBLY
← Volver a las funciones

Integración de la pasarela de pago Stripe en el checkout (Proyecto Aurora)

Convierte un encargo hablado en un brief estructurado listo para entregar.

Ejemplo de un resultado real

Resumen

Marc, del equipo de Pagos, dictó un brief para conectar la pasarela de pago Stripe al checkout del e-commerce Proyecto Aurora. El objetivo es sustituir la facturación manual actual por pagos con tarjeta online, con soporte para Apple Pay y Google Pay. El plazo para el despliegue en producción es el 15 de julio, con un MVP en el entorno de pruebas para finales de junio.

Minutas detalladas

Qué hay que construir

El objetivo es añadir el pago con tarjeta vía Stripe al checkout existente del Proyecto Aurora. Tras rellenar el carrito, el cliente elige un método de pago y paga directamente en la página, sin redirección a una pasarela externa. Marc insistió en que el formulario de pago debe ir embebido mediante Stripe Elements para que se mantenga dentro del diseño del e-commerce.

Además de la tarjeta estándar, deben soportarse Apple Pay y Google Pay, porque según la analítica los pedidos desde móvil suponen más de la mitad del tráfico. El pago en efectivo y por factura se mantienen como alternativas; Stripe es solo una tercera opción adicional.

Requisitos técnicos y salvaguardas

La fiabilidad de la confirmación del pago es lo crítico. El estado del pedido no debe cambiar nunca según la respuesta del navegador, sino exclusivamente mediante un webhook de Stripe en el backend (el evento payment_intent.succeeded). Marc advirtió explícitamente contra la situación en la que el cliente paga pero la conexión se cae y el pedido se queda colgado como impagado.

Cada llamada debe ser idempotente (volver a ejecutarla no crea un segundo pago) mediante una idempotency key. Los webhooks deben verificarse por firma para que no se puedan falsificar. En caso de caída de Stripe se requiere un fallback — el checkout no debe caerse por completo; la opción de tarjeta simplemente se oculta y se ofrecen los métodos de pago restantes.

Tareas

  • Crear un endpoint de backend para crear un PaymentIntent con Stripe (importe, moneda, idempotency key). · responsable equipo de backend · plazo antes del 27 de junio alta
  • Integrar Stripe Elements en el checkout del frontend (tarjeta, Apple Pay, Google Pay) con el diseño del e-commerce. · responsable equipo de frontend · plazo antes del 30 de junio alta
  • Implementar un handler de webhooks para payment_intent.succeeded y payment_intent.payment_failed con verificación de firma. · responsable equipo de backend · plazo antes del 27 de junio alta
  • Añadir un fallback: cuando Stripe no esté disponible, ocultar el pago con tarjeta y ofrecer efectivo y factura. · responsable equipo de frontend · plazo antes del 3 de julio media
  • Preparar escenarios de prueba (éxito, fallo de tarjeta, caída del webhook, pago duplicado) en el entorno de pruebas. · responsable Lucía (QA) · plazo antes del 8 de julio media

Decisiones

  • El formulario de pago se embeberá mediante Stripe Elements directamente en el checkout, sin redirección a una página externa. 💬 de la transcripción: „"Lo quiero dentro, con el mismo diseño, no que rebote a la persona a una página de terceros."“
  • La confirmación del pago la gestiona el webhook payment_intent.succeeded del lado del servidor, no la respuesta del cliente. 💬 de la transcripción: „"La fuente de la verdad es el webhook en el backend, y punto."“
  • Apple Pay y Google Pay forman parte del primer MVP, no de una fase posterior. 💬 de la transcripción: „"Trata Apple Pay y Google Pay como parte de la base, no como un extra para luego."“

Ideas clave

  • El estado del pedido lo gobierna exclusivamente el webhook del lado del servidor, no la respuesta del navegador — esto protege frente a perder un pago cuando se cae la conexión. 💬 de la transcripción: „"Nunca, y lo digo en serio, confirméis un pedido según lo que vuelve al navegador. Solo según el webhook en el servidor."“
  • Los pedidos desde móvil suponen más del 50 % del tráfico, por eso Apple Pay y Google Pay forman parte del MVP, no de una segunda fase. 💬 de la transcripción: „"Más de la mitad de la gente compra desde el móvil, así que Apple Pay y Google Pay tienen que estar desde el principio, no para más adelante."“
  • Si Stripe se cae, el checkout entero no debe romperse — solo se oculta el pago con tarjeta y quedan el efectivo y la factura. 💬 de la transcripción: „"Si Stripe se cae, que no se venga abajo todo el checkout. Simplemente se oculta la tarjeta y la gente paga de otra forma."“

Datos

  • 15 de julio fecha Despliegue en producción Plazo para lanzar la pasarela de pago en operación real.
  • finales de junio fecha MVP en el entorno de pruebas Una integración funcional lista para probar.
  • alta prioridad Prioridad de la tarea Marc marcó los pagos con tarjeta como bloqueantes para la campaña de verano.
  • más del 50 % Porcentaje de pedidos desde móvil La razón para incluir Apple Pay y Google Pay en el MVP.

Poco claro / riesgos

  • No se especifica si debe soportarse el guardado de tarjetas para pagos recurrentes (saved cards) o solo pagos puntuales.
  • Marc no mencionó un umbral concreto para las devoluciones automáticas (refunds) — hay que cerrarlo con el equipo de soporte.
  • No se dijo en qué monedas se pagará (solo CZK, o también EUR para clientes internacionales).

Brief para el implementador

Brief de implementación — Integración de la pasarela de pago Stripe (Proyecto Aurora)

Objetivo

Añadir el pago con tarjeta vía Stripe al checkout existente del e-commerce Proyecto Aurora, incluyendo Apple Pay y Google Pay, como tercer método de pago junto al efectivo y la factura.

Alcance (scope)

  • Formulario de pago embebido mediante Stripe Elements directamente en el checkout (sin redirección a una pasarela externa).
  • Soporte para los métodos de pago: tarjeta, Apple Pay, Google Pay.
  • Confirmación de pagos del lado del servidor mediante webhooks (fuente de la verdad = backend, no el navegador).
  • Fallback cuando Stripe no esté disponible (degradación elegante sin tumbar todo el checkout).

Fuera de alcance (out of scope)

  • Guardado de tarjetas para pagos recurrentes (saved cards) — no se aborda por ahora, pendiente de decisión.
  • Devoluciones (refunds) desde la UI de administración — para el MVP basta con devoluciones a través del Stripe Dashboard.

Requisitos funcionales

  1. Creación del pago
    • El endpoint de backend crea un PaymentIntent (importe, moneda, idempotency_key).
    • El frontend solicita el client_secret y renderiza Stripe Elements.
  2. Confirmación del pago
    • El estado del pedido lo cambia exclusivamente el webhook payment_intent.succeeded.
    • La respuesta del cliente sirve solo para mostrar la pantalla de «gracias», nunca para confirmar el pedido.
  3. Fallo del pago
    • Webhook payment_intent.payment_failed → el pedido se queda en estado «pendiente de pago» y el cliente recibe la opción de intentarlo de nuevo.
  4. Fallback
    • Cuando Stripe no esté disponible, el pago con tarjeta se oculta y se muestran efectivo + factura. El checkout no debe caerse por completo.

Requisitos no funcionales

  • Idempotencia: cada llamada a PaymentIntent usa una idempotency key (reenviar no crea un segundo pago).
  • Seguridad de los webhooks: verificación de firma (Stripe-Signature), rechazo de las peticiones no verificadas.
  • Secrets: las claves de la API de Stripe exclusivamente en GCP Secret Manager, nunca en el código ni en un archivo .env en git.
  • Logging: cada fallo de pago y cada webhook entrante van al structured logging (Cloud Logging).

Criterios de aceptación

  • El cliente paga con tarjeta y el pedido se marca como pagado solo después de recibir el webhook payment_intent.succeeded.
  • Apple Pay y Google Pay aparecen en los dispositivos compatibles y funcionan de extremo a extremo.
  • Si la conexión se cae tras el pago (navegador cerrado), el pedido se marca igualmente como pagado gracias al webhook.
  • Enviar un pago dos veces no crea dos pagos (verificado mediante la idempotency key).
  • Un webhook falsificado sin firma válida se rechaza (HTTP 400).
  • Durante una caída simulada de Stripe, el checkout no se rompe — el pago con tarjeta simplemente desaparece.

Plazos

  • MVP en pruebas: finales de junio
  • Producción: 15 de julio

Preguntas abiertas

  • Guardado de tarjetas para pagos recurrentes — ¿sí/no?
  • Monedas: ¿solo CZK, o también EUR?
  • ¿Umbral para la devolución automática?

Ejemplo de transcripción

Marc (solicitante)

Venga, vamos a pagos. Quiero que por fin metamos el pago con tarjeta vía Stripe en el checkout de Aurora. Ahora mismo la gente paga o en efectivo contra reembolso o por factura, y eso nos frena.

Marc (solicitante)

Lo importante es que se quede dentro, con el mismo diseño. Nada de rebotar a una página de terceros. Lo embebemos con sus Elements para que parezca parte del e-commerce.

Marc (solicitante)

Y ahora lo más importante. Nunca, y lo digo en serio, confirméis un pedido según lo que vuelve al navegador. Solo según el webhook en el servidor. Ya tuvimos una vez un caso en que la persona pagó, se le cayó la conexión y el pedido se quedó colgado como impagado. Eso no puede repetirse.

Marc (solicitante)

Trata Apple Pay y Google Pay como parte de la base, no como un extra para luego. Más de la mitad de la gente compra desde el móvil, así que tiene que estar desde el principio.

Marc (solicitante)

Y una cosa más. Si Stripe se cae, que no se venga abajo todo el checkout. Simplemente se oculta la tarjeta y la gente paga de otra forma. No quiero perder una venta entera por una caída de la pasarela.

Marc (solicitante)

Como objetivo lo quiero en real antes del quince de julio, por la campaña de verano. En pruebas, que funcione para finales de junio, para que a Lucía le dé tiempo a clicarlo a fondo.

Probar Voxibly