Pagos y suscripciones

---
name: pagos-y-suscripciones
description: cobrar todos los meses sin perseguir a nadie.
---

# Pagos y suscripciones

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques checkout, planes, prueba gratis, cancelaciones o el estado de cuenta que decide
qué puede usar cada quien.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Quieres cobrar por la versión que estás construyendo, no solo usarla tú.
- Hay funciones que solo deben existir en un plan de paga.
- Vendes por asiento, por uso o con prueba gratuita.
- Necesitas facturas, impuestos o comprobantes para tus clientes.

Cobrar una vez es fácil; lo difícil es que tu base de datos y la del proveedor de pagos
digan lo mismo después de un pago fallido, un cambio de plan a medio mes o un reembolso.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Stripe Checkout +
Customer Portal**, o **Lemon Squeezy** / **Paddle** si prefieres que ellos sean el
comerciante registrado.

1. No construyas formularios de tarjeta. Redirige a Checkout alojado y vuelve con una
   sesión.
2. Guarda solo tres cosas de tu lado: `customerId`, `subscriptionId` y estado del plan.
   El proveedor es la fuente de la verdad del dinero, no tu tabla.
3. Deriva los permisos del estado (`active`, `trialing`, `past_due`, `canceled`), nunca
   de "pagó una vez".
4. Escucha los webhooks de suscripción y hazlos idempotentes: llegan repetidos y
   desordenados.
5. Manda a Customer Portal para cambios de plan, tarjeta y cancelación. Es la pantalla
   que menos vale la pena rehacer tú mismo.
6. Prueba con tarjetas de fallo: pago rechazado, disputa y reembolso. Ese es el camino
   que rompe la app en producción.

## En qué te vas a trabar

- **Impuestos y facturación son el moat real:** IVA, retenciones y comerciante
  registrado no son código, son cumplimiento. No los subestimes por ser "solo un
  webhook".
- **Si tu webhook falla en silencio, la gente paga y no recibe acceso.** Alerta cuando
  falle, no dejes que lo descubra el cliente.
- **Prorrateos y cambios de plan a medio ciclo son la fuente número uno de facturas
  equivocadas.** Prueba ese camino explícitamente, no solo el flujo feliz.

## Criterio de terminado

No declares esto listo hasta que un pago rechazado, una disputa y un reembolso pasen por
el sistema completo sin dejar al usuario con acceso equivocado, y hasta que el estado de
tu base de datos coincida con el de Stripe después de cada webhook de prueba.