Todo lo que necesitas para construir una integración Stripe que aguante en producción: cómo funcionan los pagos y el modelo de objetos de Stripe, Payment Element y Checkout, Billing y ciclo de vida de suscripciones, precios por uso, Connect para plataformas y marketplaces, webhooks e idempotencia, conciliación, dunning, reglas Radar antifraude, reducción del alcance PCI y en qué consiste realmente una migración desde otro procesador. Sin rodeos ni omisiones.
Stripe es la plataforma de pagos más completa disponible, y esa completitud es también su principal riesgo de complejidad. Hay múltiples formas de aceptar un pago, múltiples superficies de producto para suscripciones y un modelo de eventos que requiere un manejo cuidadoso a escala de producción. Esta guía describe cómo pensamos e implementamos cada capa, en el orden en que normalmente se encuentran.
Antes de escribir una línea de código de integración, vale la pena entender cómo Stripe modela el movimiento de dinero, porque la jerarquía de objetos condiciona cada decisión posterior. Los tres objetos fundamentales son el Customer, el PaymentMethod y el PaymentIntent.
Un Customer es una identidad en Stripe que posee métodos de pago y tiene un historial de facturación. Un PaymentMethod representa un instrumento de pago almacenado: una tarjeta, una cuenta bancaria, un monedero digital. Un PaymentIntent es un registro de un intento de cobrar dinero y es el objeto que impulsa el flujo de pago. Todo lo demás, Subscriptions, Invoices, Charges, Transfers, se construye sobre estos tres.
Una consecuencia de este modelo importa más que cualquier otra en una primera integración: nunca completes un pedido basándote en una redirección del navegador. Las redirecciones pueden fallar, actualizarse o falsificarse. El disparador correcto para completar el pedido es el webhook payment_intent.succeeded entregado de servidor a servidor por Stripe. Aquí es donde la mayoría de las primeras integraciones se equivoca.
Stripe ofrece dos formas de recoger un pago en el frontend. El Payment Element es un componente React embebible que montas dentro de tu propia página, dándote control total sobre la interfaz que lo rodea mientras Stripe gestiona los campos sensibles de la tarjeta y el flujo de autenticación. Checkout es una página alojada en el dominio de Stripe a la que rediriges, que requiere casi ningún trabajo frontend a cambio de menos flexibilidad en el diseño.
La elección entre ambos depende normalmente de cuánto control necesitas y cuánto alcance PCI quieres asumir. Las dos opciones usan el iframe de Stripe para manejar los datos de la tarjeta, por lo que ninguna aumenta significativamente el alcance PCI, pero Payment Element exige más código frontend y una implementación de webhooks más cuidadosa. Para la mayoría de los productos SaaS, Payment Element es la elección correcta porque el control sobre el diseño y la conversión vale el trabajo extra.
payment_intent.succeeded, payment_intent.payment_failed y charge.dispute.created como mínimo.La regla de la clave de idempotencia. Cada llamada API de Stripe que crea o modifica un objeto debería incluir una cabecera Idempotency-Key. Usa un identificador estable derivado de lo que estás creando, como tu ID de pedido interno, no un UUID aleatorio generado en el momento de la solicitud. Así, un reintento por un fallo de red o un crash del servidor es seguro.
Stripe se comunica de forma asíncrona mediante webhooks: solicitudes HTTP POST a un endpoint de tu servidor, con un payload JSON que describe un evento. El webhook es la fuente de verdad canónica del estado del pago. Si no lo procesas, no sabes qué ha ocurrido.
Stripe garantiza la entrega al menos una vez, lo que significa que el mismo evento puede llegar más de una vez, especialmente después de que tu servidor devuelva un 5xx o se agote el tiempo de espera. Tu webhook handler debe ser idempotente: procesar el mismo evento dos veces debe producir el mismo resultado que procesarlo una vez. En la práctica, esto significa almacenar el ID del evento Stripe en tu base de datos antes de hacer cualquier trabajo y comprobarlo antes de procesar cualquier entrega posterior del mismo evento.
customer.subscription.trial_will_end (avisa al usuario), invoice.payment_failed (inicia la secuencia de dunning), customer.subscription.updated (sincroniza cambios de plan en la base de datos) y customer.subscription.deleted (revoca el acceso). Perderse cualquiera de ellos crea una situación en la que Stripe y tu sistema no están de acuerdo sobre lo que un cliente tiene acceso.Verifica cada webhook entrante usando la verificación de firma de Stripe antes de procesarlo. La firma está en la cabecera Stripe-Signature y el SDK de Stripe proporciona un método constructEvent que la valida frente a tu webhook signing secret. Saltarse esta comprobación significa que cualquier actor que descubra la URL de tu webhook puede enviar eventos falsos.
Devuelve un 200 inmediatamente después de verificar la firma y poner el evento en cola para su procesamiento asíncrono. No hagas el trabajo de forma síncrona en el handler HTTP: la lógica de reintentos de Stripe trata cualquier respuesta que tarde más de 30 segundos como un fallo, y tu procesamiento puede tardar más.
Stripe Billing añade una capa de objetos sobre las primitivas de pago fundamentales: Products, Prices, Subscriptions e Invoices. Un Product es lo que vendes; un Price define las condiciones (tarifa plana, por puesto, por uso, único). Una Subscription vincula a un Customer con un Price y genera Invoices según un calendario. Un Invoice es el intento de cobro.
La ventaja de usar Billing frente a construir tu propia lógica de suscripciones es que Stripe gestiona la programación, la prorración en cambios de plan, la generación de PDF de facturas, los recibos por email a clientes y la lógica de reintentos en pagos fallidos. El coste es que tu base de datos debe mantenerse sincronizada con la representación de Stripe de cada suscripción, lo que requiere un manejo cuidadoso de los webhooks.
Cuando un cliente hace un upgrade o downgrade a mitad de ciclo, Stripe calcula la prorración por defecto: el valor restante del plan antiguo se acredita y el nuevo plan se cobra por el resto del ciclo. Puedes controlar el comportamiento de la prorración al actualizar la suscripción, cobrando de inmediato, aplazándolo a la próxima factura o desactivando la prorración por completo. La elección correcta depende de tu modelo de precios y de las expectativas de tus clientes.
Stripe soporta períodos de prueba a nivel de Price, que los aplica automáticamente a cada nuevo suscriptor, o a nivel de Subscription para anulaciones personalizadas. Durante una prueba, Stripe puede recoger un método de pago de antemano sin cobro inmediato (el comportamiento por defecto para la mayoría de los SaaS) o saltarse el método de pago y pedirlo solo cuando termine la prueba. Exigir una tarjeta de antemano reduce la fricción de prueba a pago al coste de menos inicios de prueba. Los datos sobre qué enfoque convierte mejor varían significativamente por producto y franja de precio.
Los precios por uso, también llamados metered billing, cobran a los clientes según cuánto usan en lugar de una tarifa plana. Stripe lo soporta mediante Billing Meter, que acepta registros de eventos de uso y los agrega en líneas de factura al final de cada período de facturación.
El patrón de implementación es: tu aplicación envía eventos de uso a la API Meter Events de Stripe siempre que ocurra una acción facturable. Al final del período de facturación, Stripe agrega los eventos según la estrategia de agregación configurada (suma, máximo o último valor) y genera la línea de factura a partir del resultado. Tu base de datos no necesita mantener un total acumulado para la facturación; Stripe es la fuente de verdad del uso.
Idempotencia en los eventos de uso. Los registros de Meter Event aceptan un campo identifier. Ponlo a un ID estable para la acción específica (por ejemplo, tu ID de evento interno). Si envías el mismo evento dos veces con el mismo identificador, Stripe lo deduplica. Sin esto, un reintento por un fallo de red duplica el recuento de uso y cobra de más al cliente.
El churn involuntario, clientes que dejan de pagar porque su tarjeta ha caducado o ha sido rechazada en lugar de haber elegido irse, representa típicamente entre el 20 y el 40 por ciento del churn total para un SaaS con facturación mensual. La mayor parte es recuperable si construyes la secuencia correcta. Stripe proporciona Smart Retries, que usa machine learning para programar los reintentos en los momentos en que las tasas de aprobación son más altas. Además de eso, deberías construir una secuencia de dunning en tu propio producto.
Una secuencia de dunning básica funciona así: ante invoice.payment_failed, envía al cliente un email con un enlace para actualizar su método de pago. Espera de tres a cuatro días y reintenta. Si el segundo intento falla, envía un segundo email con un asunto más contundente. Reintenta de nuevo tres días después. Si el tercer intento falla, pon al cliente en un estado de gracia en lugar de cancelar de inmediato, envía un aviso final y cancela tras siete días sin acción. El estado de gracia importa: preserva la cuenta y la relación mientras el cliente soluciona su tarjeta y evita la fricción de un flujo de cancelación y reactivación.
El customer portal de Billing de Stripe gestiona el flujo de actualización del método de pago sin configuración adicional si quieres evitar construirlo tú mismo. Es una página alojada en el dominio de Stripe, similar a Checkout, a la que los clientes llegan desde el enlace en tu email de dunning.
Stripe Connect es la superficie de producto para plataformas y marketplaces donde el dinero fluye a través de tu aplicación hacia otros negocios o personas. Si cobras una comisión de reserva y pasas el resto a un proveedor de servicios, o cobras a un comprador y divides el pago entre un marketplace y un vendedor, estás construyendo una integración Connect.
Existen tres tipos de cuenta Connect y la elección tiene consecuencias reales. Las cuentas Standard tienen su propio panel Stripe y gestionan sus propias disputas y reembolsos; tu plataforma tiene control limitado pero carga mínima de cumplimiento. Las cuentas Express usan un flujo de onboarding alojado por Stripe y un panel simplificado; tu plataforma tiene más control y Stripe gestiona la mayor parte del cumplimiento. Las cuentas Custom le dan a tu plataforma control total sobre la experiencia y la interfaz, pero asumes una responsabilidad de cumplimiento significativamente mayor. La mayoría de los builds de marketplace empiezan con Express.
Stripe retiene los fondos en el saldo de una cuenta conectada hasta que se ejecuta un payout. La programación del payout puede ser automática en una cadencia diaria, semanal o mensual, o manual activada por el código de tu plataforma. Para plataformas donde el momento de los payouts es una característica del producto (por ejemplo, una opción de pago bajo demanda), los payouts manuales son la elección correcta. Para la mayoría de los marketplaces, los payouts automáticos semanales o mensuales son más sencillos y reducen el volumen de soporte.
La conciliación es el proceso de confirmar que lo que Stripe muestra como pagado coincide con lo que tu base de datos muestra como debido y recibido. A pequeños volúmenes es manejable manualmente; a cualquier escala real requiere una pipeline. La materia prima es la API Balance Transactions de Stripe, que lista cada movimiento de fondos en tu cuenta Stripe con tipo, importe, comisión, importe neto y el cobro o payout vinculado.
Una pipeline de conciliación básica: extrae Balance Transactions de Stripe en una programación nocturna, almacena cada una en tu data warehouse con clave en su ID Stripe, une con tus registros de pedidos internos y reporta cualquier discrepancia. Las discrepancias suelen caer en cuatro categorías: cobros en Stripe sin pedido correspondiente en tu base de datos (fallo en el procesamiento del webhook), pedidos en tu base de datos sin cobro correspondiente en Stripe (payment intent creado pero nunca confirmado), importes que no coinciden (error de conversión de moneda o cálculo de comisión) y diferencias de tiempo que se resuelven en pocos días.
Los payouts no son ingresos. Un payout mueve dinero de tu saldo Stripe a tu cuenta bancaria. No es una nueva transacción; es la liquidación de transacciones que ya ocurrieron. Muchas primeras implementaciones tratan el evento de payout como reconocimiento de ingresos, lo que crea una discrepancia con la contabilidad por devengo. Los ingresos deben reconocerse en el evento charge.succeeded o invoice.paid, no en el payout.
Stripe Radar es la capa de detección de fraude integrada en toda integración Stripe. Por defecto bloquea transacciones que coinciden con patrones de fraude conocidos, usando machine learning entrenado en el volumen de transacciones de todos los merchants de Stripe. Para la mayoría de los negocios, las reglas por defecto son un punto de partida razonable. Para negocios con un perfil de fraude específico, las reglas Radar personalizadas permiten añadir lógica sobre los valores predeterminados.
Las reglas Radar se escriben en un sencillo lenguaje de expresiones booleanas y se evalúan en orden. Una regla puede bloquear un cobro, permitirlo (anulando un bloqueo por defecto) o solicitar un paso de autenticación 3D Secure. Reglas personalizadas habituales: bloquear cobros de países de alto riesgo que no atiendes, exigir 3DS para cobros por encima de un importe umbral, bloquear tarjetas que han aparecido en demasiadas transacciones rechazadas en la última hora y permitir cobros de clientes empresariales verificados en tu base de datos incluso cuando el modelo por defecto los marca como sospechosos.
Revisa tu tasa de disputas y la tasa de falsos positivos (cobros legítimos que Radar bloquea) mensualmente. Una tasa de disputas por encima del 0,5 por ciento es una señal de endurecer las reglas; un volumen significativo de reclamaciones de clientes por pagos legítimos bloqueados es una señal de aflojarlas o añadir reglas de lista blanca para clientes conocidos.
El Payment Card Industry Data Security Standard (PCI DSS) define los requisitos de seguridad para cualquier sistema que almacena, procesa o transmite datos de titulares de tarjetas. Los productos de integración de Stripe están diseñados específicamente para minimizar tu alcance PCI, es decir, la superficie de tus sistemas que cae bajo los requisitos PCI.
Cuando usas Payment Element o Checkout, el número de tarjeta, la fecha de caducidad y el CVV se introducen directamente en el iframe de Stripe o en la página alojada y nunca pasan por tus servidores. Tu servidor solo ve el ID del PaymentIntent y el token que devuelve Stripe. Esto te califica para SAQ A, el cuestionario de autoevaluación más sencillo, que requiere aproximadamente 20 controles en lugar de los cientos requeridos para SAQ D (almacenamiento completo de datos de tarjeta).
Lo que no debes hacer: registrar datos de tarjeta en bruto, almacenar el PAN completo en tu base de datos, pasar detalles de tarjeta a través de tu backend aunque sea brevemente, o usar Stripe de una forma que haga que los datos de titulares de tarjetas pasen por tu red. Estos comportamientos te descalifican para SAQ A. La propia documentación de Stripe es clara sobre el límite; los patrones de integración de esta guía se mantienen dentro de él.
La migración desde un procesador de pago existente a Stripe es factible sin interrumpir las suscripciones activas, pero requiere una secuencia cuidadosa. Los dos problemas difíciles son: migrar los métodos de pago almacenados (datos de tarjeta que viven en el vault del antiguo procesador) y migrar las suscripciones activas (cobros recurrentes que tu antiguo procesador ejecuta según una programación).
La migración de tarjetas almacenadas requiere que tu procesador actual exporte datos de tarjeta cifrados en un formato que el equipo de migración de Stripe pueda importar en su vault. No todos los procesadores lo soportan, y los que lo hacen requieren un acuerdo formal de transferencia de datos. Stripe ha hecho esto con la mayoría de los principales procesadores y tiene un proceso documentado. La alternativa es pedir a los clientes que reintroduzcan su tarjeta, que es más sencillo de implementar pero introduce un riesgo significativo de churn en el paso de reintroducción.
Migración de suscripciones: una vez que los datos de tarjeta están en Stripe, creas objetos Customer y Subscription correspondientes con billing_cycle_anchor configurado para alinear la fecha de cobro con tu antiguo procesador, de modo que los clientes no sean cobrados dos veces ni menos de lo debido durante la transición. Ejecuta los sistemas nuevo y antiguo en paralelo durante al menos un ciclo de facturación completo, reconcilia el resultado y haz el cutover solo cuando los dos coincidan. Establece una fecha de cutover, cancela las suscripciones en el antiguo procesador el día antes de su próxima renovación y deja que Stripe gestione el próximo ciclo.
La auditoría de migración cubre: el procesador que estás dejando, si soporta la exportación cifrada de tarjetas, el número y la estructura de tus planes de suscripción, cualquier lógica de facturación no estándar (duraciones de prueba personalizadas, créditos a mitad de ciclo, planes multidivisa) y tu tolerancia al riesgo de cutover. Eso da forma al plan de migración antes de que se escriba cualquier código.
Este es el cuadro completo de implementación. Cuando quieras aplicarlo a tu producto, el próximo paso es una auditoría gratuita: miramos lo que tienes o lo que estás planificando, mapeamos las lagunas y te decimos qué construir y en qué orden.
Una auditoría gratuita de tu configuración, las lagunas mapeadas y un alcance fijo para cerrarlas. Hallazgos en una semana.
Solicita una auditoría Stripe gratuita