El cobro recurrente de tu producto, con el estado que Stripe confirma.
Un módulo de suscripciones para meter en lo tuyo: planes publicados en Stripe Billing, suscriptores con su historial de ciclos, cobranza con cada intento fallido y su motivo, y un estado por suscripción que escribe el aviso de Stripe, no una casilla que alguien marca. Con tus colores y en tu dominio.
Cobrar una vez es fácil. Cobrar cada mes sin cobrarle a quien ya se fue, no.
Abrir un Checkout de Stripe toma una tarde. Lo que toma meses es que tu base y la de Stripe digan lo mismo cuando un webhook llega tarde, repetido o desordenado. Eso es lo que este módulo trae resuelto.
El estado lo confirma Stripe
Nada de aquí declara «al corriente» por su cuenta. El estado de una suscripción lo escribe el aviso de Stripe, porque es quien sabe si la tarjeta pasó. Cuando pides una baja, la pantalla dice «cancelación solicitada» hasta que llega la confirmación: es la verdad, y decir otra cosa acabaría en un cargo a quien ya se despidió.
Pago vencido no es servicio cortado
Son dos estados distintos y se ven distintos. Un cobro fallido deja a la persona con servicio mientras Stripe reintenta; el corte llega cuando Stripe se rinde y declara la factura incobrable. Cortar el mismo día que venció la tarjeta pierde clientes que iban a pagar.
El precio de un plan publicado no se edita
Cambiar el precio es crear un plan nuevo y archivar el viejo, porque el precio vive en Stripe y allá es inmutable. Quien ya estaba suscrito sigue pagando lo que firmó hasta que alguien lo mueva de plan a propósito, con su permiso y su rastro.
Tres pasos, y ninguno escribe un estado que Stripe no haya contado
Publicas un plan
Nombre, precio en centavos enteros, moneda, periodicidad y días de prueba. Al publicarlo se crea el precio en Stripe, y desde ese momento importe y periodicidad quedan sellados: cambiarlos es un plan nuevo.
Tu producto abre el checkout
Desde el widget o con una llamada a la API: suscriptor y plan. El módulo devuelve la URL de Stripe Checkout y tu pantalla redirige. Dos clics en «dar de alta» devuelven la misma suscripción, no dos.
Stripe cuenta cada ciclo
Cada factura llega por webhook y se escribe como un ciclo con el importe que se cobró de verdad. Un evento repetido no hace nada; uno que llegó tarde no pisa a uno más nuevo; una suscripción cancelada no vuelve a la vida.
Tres estados que importan y todo lo que hay alrededor
La frontera entre vencido y suspendido la pone Stripe cuando declara la factura incobrable, no un contador nuestro. Lo que significa «suspendida» para tu servicio lo decide tu producto: este módulo avisa, no apaga nada de nadie.
Al corriente
Stripe cobró el ciclo
Pago vencido
Falló un cobro · hay servicio
Suspendida
Stripe agotó los reintentos · sin servicio
Planes con el precio sellado en Stripe
Precio en centavos enteros y nunca en decimales: 19.99 no existe en binario y un redondeo en el tercer año es un descuadre que nadie sabe explicar. Diario, semanal, mensual o anual, con días de prueba y visibilidad por plan.
Un suscriptor, un cliente de Stripe
Persona o empresa, con un solo cliente de Stripe. Un mismo cliente con dos acaba con dos métodos de pago, dos historiales y una cancelación que sólo apaga la mitad. El módulo lo impide en la base, no en la pantalla.
Historial con el importe que se cobró
Cada factura de Stripe es un ciclo, con impuestos, descuentos y prorrateos ya incluidos. La misma factura contada dos veces escribe una fila, y un ciclo pagado no vuelve atrás porque un fallo viejo llegó tarde.
Cobranza con motivo y fecha
Cada intento fallido con su código, su mensaje en español y la fecha en la que Stripe va a volver a intentar. Los reintentos los lleva Stripe: dos calendarios sobre la misma factura es la definición del doble cobro.
Cambio de plan con el prorrateo de Stripe
La pantalla estima cuánto costará el cambio; el cargo real lo calcula Stripe con su reloj, sus descuentos y sus impuestos, y entra como un ciclo más. Bajar de plan deja crédito para la siguiente factura, no un reembolso automático.
Quien atiende ve, no cobra distinto
Atención da de alta suscriptores, abre el checkout y ve todo el historial. Mover a alguien de plan es de supervisión. Cancelar, descontar y crear planes es de dirección: apagar un ingreso recurrente no se decide por teléfono con prisa.
Tus suscripciones, con tu equipo, en cinco minutos
Una cuenta por persona: el mismo correo que usas en los demás productos del sitio sirve aquí. El espacio se crea solo; después pones tu llave de Stripe, publicas el primer plan e invitas a quien atiende, a quien supervisa y a quien dirige, cada uno con lo suyo.
El tablero, con una etiqueta. El alta, con una llamada.
El token lo emite tu backend con tu llave secreta y dura quince minutos. La llave nunca llega al navegador, y la llave de Stripe nunca sale del servidor: el módulo te devuelve la URL del checkout y tu pantalla redirige.
El tablero embebido
<script src="https://nexusnorth.dev/embed/v1/nexus-suscripciones.js" defer></script>
<nexus-suscripciones
tenant-id="tu-tenant"
workspace-id="tu-espacio"
auth-token="token-efimero-de-tu-backend"
style="--nexus-primary: #0f766e; --nexus-radius: 0.75rem"
></nexus-suscripciones>Un alta desde tu backend
POST /api/v1/suscripciones/subscriptions
Authorization: Bearer <token>
{ "subscriberId": "s_7c2e…", "planId": "p_41af…" }
→ 200
{
"subscriptionId": "sub_9d1b…",
"url": "https://checkout.stripe.com/c/pay/cs_live_…",
"already": false
}- Tu producto no aprende a hablar con Stripe Billing: manda suscriptor y plan, recibe la URL del checkout y redirige.
- La misma pareja suscriptor y plan devuelve la suscripción viva con already: true. Puedes reintentar tu llamada sin abrir un segundo cobro.
- El estado te llega por eventos: activada, cobro fallido, suspendida, cancelada y prueba por terminar. Tu producto decide qué hace con cada uno.
- Los eventos se entregan al menos una vez con su id: tu escuchador los desduplica por id y listo.
- Sin cookies de terceros: el token viaja en memoria, no en el navegador.
- Aislado en Shadow DOM, un solo archivo, con tus colores heredados por variables CSS.
Lo que suelen preguntar antes de integrarlo
¿Cobra con mi cuenta de Stripe o con la de ustedes?
Con la tuya. La llave vive en el servidor, nunca en el navegador, y el tablero sólo sabe si está puesta: sin ella, «Publicar en Stripe» y «Dar de alta» se apagan y dicen por qué, en vez de dejar que alguien llene un formulario que va a fallar. Tus clientes ven tu nombre en el recibo, no una marca ajena.
¿Qué pasa cuando cancelo a alguien desde mi pantalla?
Se le pide a Stripe y la fila se queda como está hasta que Stripe confirma. Mientras, la pantalla dice «cancelación solicitada», que es la verdad. Por omisión la baja es al final del ciclo que el cliente ya pagó; la inmediata existe, pero es una decisión que alguien toma a propósito.
¿Cuándo se le corta el servicio a quien no paga?
Cuando Stripe agota sus reintentos y declara la factura incobrable. Hasta entonces la suscripción está en «pago vencido» y la persona conserva el servicio, porque la mayoría de las tarjetas rebotadas acaban pagando. Al pasar a «suspendida» el módulo emite un evento; qué significa eso para tu servicio lo decide tu producto.
¿Puedo cambiar el precio de un plan?
No editándolo. El precio vive en Stripe y allá es inmutable, así que el módulo lo rechaza en la base con la suscripción viva. Lo que se hace es crear un plan nuevo y archivar el viejo: quien ya estaba suscrito sigue pagando lo que firmó hasta que alguien lo mueva de plan, con su permiso y su rastro de auditoría.
¿Y si muevo a alguien de plan a mitad de mes?
El prorrateo lo calcula Stripe con su reloj, los descuentos que ya aplicó y el impuesto vigente de cada línea. La pantalla te enseña una estimación etiquetada como tal para que nadie cambie a ciegas, pero el cargo real entra por webhook como un ciclo más. Bajar de plan deja el crédito para la siguiente factura; devolver dinero es una decisión comercial, no automática.
¿Qué pasa si un webhook llega dos veces o desordenado?
Tres capas. El evento se reclama por su id, así que la segunda llegada no hace nada. Cada suscripción guarda la fecha del último evento aplicado, y uno más viejo no se aplica: un «vencido» que tardó cuarenta segundos no pisa al pago que ya lo arregló. Y «cancelada» es terminal: ningún evento la resucita.
¿Se puede reactivar una suscripción cancelada?
No la misma: Stripe no resucita una suscripción cancelada, así que se crea una nueva con su propio checkout, y la vieja conserva su historial, que es lo que cobranza necesita para saber que esa persona ya se fue una vez. Lo que sí se deshace es una cancelación al final del ciclo que todavía no llegó.
¿Qué día cobra a quien se dio de alta un 31?
El 28 de febrero, o el 29 en bisiesto, y vuelve al 31 en marzo. El ciclo siguiente se calcula siempre desde la fecha de alta original y no desde la anterior, así que nadie se queda clavado en el 28 para siempre. Todo en UTC, para que la mitad del planeta no cobre un día corrido.
¿Tu producto cobra cada mes?
Cuéntanos qué vendes por suscripción y cómo lo cobras hoy, y te decimos si este módulo encaja — o si lo tuyo necesita otra cosa.
Hablemos