Añadir pagos a tu producto con Stripe

Cobrar con tarjeta es una semana de trabajo. Operar un sistema que siga cuadrando con Stripe después de seis meses de reembolsos, disputas, renovaciones fallidas y capturas parciales es el proyecto de verdad, y es la parte que las estimaciones se saltan.

Esto es lo que realmente implica.

Qué estás construyendo en realidad

Escenario	Esfuerzo realista	Qué lo provoca
Pago único con tarjeta	1 semana	Checkout, webhook, recibo
Suscripciones	3 a 4 semanas	Cambios de plan, prorrateo, reintentos, cancelación
Dispersión en marketplace	6 a 10 semanas	Onboarding de Connect, verificación, lógica de reparto, tiempos de pago
Fondos retenidos hasta la entrega	8 a 12 semanas	Todo lo anterior más un ledger y un proceso de disputas

El patrón es que la complejidad escala con cuánto tiempo el dinero permanece en un estado incierto, no con cuántos métodos de pago aceptas.

El webhook es la integración de verdad

Lo más importante que hay que entender: la redirección del navegador después del checkout no es prueba de pago. El cliente puede cerrar la pestaña, perder señal o darle atrás. El webhook es la fuente de verdad y llega de forma independiente.

De ahí salen tres reglas, y saltarse cualquiera produce bugs exasperantes de diagnosticar porque solo aparecen en condiciones que no puedes reproducir fácilmente.

Verifica la firma. Un endpoint de webhook sin verificar es una API abierta que concede lo que el payload diga. Usa la verificación de la librería con tu secreto de firma y rechaza lo que no pase.

Sé idempotente. Stripe reintenta, y entregará el mismo evento más de una vez. Guarda los ids de eventos procesados y haz que una repetición no haga nada. Sin esto, un reintento concede la suscripción dos veces o manda dos recibos.

Acepta eventos fuera de orden. A veces recibirás un cargo exitoso antes de que exista localmente el registro al que pertenece. Maneja el evento contra los ids de objeto de Stripe en vez de asumir que tu propio estado ya es correcto.

No copies mal el modelo de datos de Stripe

Dos modos de fallo, y los dos son comunes.

El primero es tratar tu base de datos como autoritativa para el estado de pago. No lo es. Stripe sabe si un cargo se completó; tu fila es una caché de ese hecho.

El segundo es no guardar nada en local y llamar a la API en cada lectura. Eso vuelve tu producto lento, frágil cuando Stripe se degrada, y tu propia analítica imposible.

El camino intermedio: guarda el id del objeto de Stripe, el estado y los pocos campos que muestras o consultas, y actualízalos desde los webhooks. Trata tu copia como un modelo de lectura que Stripe actualiza.

Las suscripciones son donde está la complejidad callada

Una suscripción parece simple hasta que escribes qué pasa en cada uno de estos casos, y todos van a pasar:

• Un cliente sube de plan a mitad de ciclo. ¿Prorrateas, y qué ve en la factura?
• Una tarjeta caduca en la renovación. ¿Cuántas veces reintentas, durante cuántos días, y qué ve el cliente mientras tanto?
• Alguien cancela el día 3 de 30. ¿Pierde el acceso al instante o al final del periodo?
• Un pago falla después de haber concedido el acceso. ¿En qué momento lo revocas, y cómo se lo avisas antes?
• Alguien disputa un cargo de hace cuatro meses. ¿A quién se le avisa, y cambia el acceso?

Cada uno es una decisión de producto antes que de ingeniería, y dejar que se decidan implícitamente durante la implementación es como las suscripciones acaban tardando tres semanas más de lo previsto.

Marketplaces: la verificación es el camino crítico

Si pagas a terceros, Stripe Connect resuelve la mecánica, pero los requisitos de alrededor son el riesgo de calendario. Los vendedores deben estar verificados antes de cobrar, lo que implica documentos de identidad, datos de empresa e información fiscal, con requisitos exactos que varían por país.

Cuenta con que una fracción apreciable de vendedores se quede a medias del onboarding, así que construye desde el principio para el estado parcialmente verificado en vez de asumir un binario limpio. También debes decidir cuándo se mueve el dinero: en la compra, en la entrega, o con un calendario. Esa elección determina si necesitas un ledger propio, que es la diferencia entre seis semanas y doce.

Prueba las rutas que nadie prueba

Todo el mundo prueba un pago exitoso. Los bugs viven en otra parte, y todas estas son reproducibles con las tarjetas de prueba de Stripe y su CLI:

• Tarjeta rechazada y luego reintentada con éxito con otra tarjeta.
• El cliente cierra la pestaña tras pagar. ¿El webhook concede el acceso igual?
• Entrega duplicada de webhook. ¿Algo ocurre dos veces?
• Reembolso total y parcial. ¿El acceso y la analítica lo siguen?
• Disputa abierta y después perdida.
• Renovación que falla tres veces y luego funciona.

Córrelas en CI contra modo de prueba. Son las rutas que cuestan dinero real cuando están mal, que es el mismo argumento que hacemos sobre cobertura en nuestra guía para elegir agencia: cubre lo que toca dinero, no todo.

Preguntas frecuentes

Por dónde empezar

Escribe qué pasa en cada uno de los cinco casos de suscripción de arriba antes de escribir código. Si tu equipo no se pone de acuerdo en una reunión, la integración nunca iba a tomar una semana.

Si el movimiento de dinero es central en lo que construyes, cuéntanos su forma y te decimos en cuál de esas cuatro filas estás realmente.