Com afegir subscripcions amb Stripe: plans, proves, webhooks i pagaments fallits
Per afegir subscripcions amb Stripe, crea un producte amb un preu recurrent al Dashboard de Stripe, envia els clients a Stripe Checkout en mode subscripció des del teu servidor, i deixa que un webhook digui a la teva app quan cada pagament es completa, falla, canvia o acaba. Guarda l'estat de la subscripció associat a l'usuari i dona'n accés a partir d'aquest estat, no de la pàgina d'èxit. Afegeix un botó de Gestiona la facturació que obri el portal de clients allotjat de Stripe perquè la gent pugui canviar la targeta, canviar de pla i cancel·lar sense que hagis de construir aquestes pantalles.
Aquesta guia es basa en com afegir pagaments a la teva app, que cobreix el Checkout puntual, el mode de prova i la sortida en directe. Aquí ens centrem en el que és diferent de la facturació recurrent. Els detalls de Stripe provenen de la seva documentació a setembre de 2026.
Per què les subscripcions són més difícils que els pagaments puntuals
Un pagament puntual passa mentre el client és a la teva app. Una subscripció continua passant després que marxi: renovacions cada mes, targetes que caduquen, actualitzacions a mig cicle, cancel·lacions que tenen efecte al final del període. La teva app només se n'assabenta a través dels webhooks. La majoria d'errors de subscripció vénen de tractar el primer pagament com si fos tota la història.
Les teves opcions
| Enfocament | Què construeixes | Ideal per a |
|---|---|---|
| Payment Link amb preu recurrent | Només un enllaç | Provar la demanda; gestionar l'accés a mà |
| Checkout (mode subscripció) + portal de clients | Una ruta de servidor, un webhook, un botó de facturació | La majoria d'apps SaaS i membresies |
| API de subscripcions amb el teu propi formulari de pagament | Molt més: interfície de pagament, autenticació, reintents | Apps amb fluxos de facturació poc habituals |
| Proveïdor de comerciant registrat | Similar al Checkout | Venedors que volen que el proveïdor gestioni l'impost de vendes |
Per a la majoria d'apps, Checkout més el portal és el compromís adequat. Compara proveïdors a Stripe vs Paddle vs Lemon Squeezy si la gestió dels impostos et preocupa.
Planifica primer els preus a Stripe
A Stripe, un producte és el que vens («Pla Pro») i un preu és com ho cobres («20 $ al mes», «200 $ a l'any»). Un producte pot tenir diversos preus. Decideix:
- Quins nivells ofereixes i què desbloqueja cadascun a la teva app
- Mensual, anual o les dues coses
- Si ofereixes una prova, i si necessita una targeta per endavant
Crea els productes i els preus en mode de prova, i guarda els seus IDs de preu; la teva app els referencia. Si encara no has decidit els preus, llegeix com fixar el preu d'un producte SaaS i freemium vs prova gratuïta.
El cicle de vida de la subscripció que has de gestionar
La visió general de subscripcions de Stripe enumera els estats que pot tenir una subscripció. Els que més importen per a l'accés són:
| Estat | Què vol dir | Donar accés? |
|---|---|---|
trialing | En període de prova | Sí |
active | En bon estat | Sí |
incomplete | El primer pagament encara no s'ha completat; Stripe dona al client 23 hores | No |
incomplete_expired | El primer pagament mai no ha reeixit | No |
past_due | L'últim pagament ha fallat o no s'ha intentat; poden seguir reintents | Tu decideixes; moltes apps permeten un període de gràcia curt |
unpaid | Els reintents han acabat, les factures queden obertes i no hi ha més intents | No; la documentació de Stripe diu que cal revocar l'accés |
canceled | Ha acabat; no es pot reiniciar | No |
paused | Una prova ha acabat sense mètode de pagament i s'ha configurat perquè es pausi | No |
Guarda l'estat al registre de l'usuari o del compte i basa-hi l'accés. Actualitza'l cada vegada que arribi un webhook rellevant.
Els esdeveniments de webhook que cal gestionar
| Esdeveniment | Què fa la teva app |
|---|---|
checkout.session.completed | Vincula els IDs nous de client i de subscripció de Stripe al teu usuari |
invoice.paid | Marca la subscripció com a activa i registra el nou final de període |
invoice.payment_failed | Informa l'usuari que la seva targeta ha fallat i enllaça al portal |
invoice.payment_action_required | Demana a l'usuari que completi l'autenticació de la targeta |
customer.subscription.updated | Actualitza el pla, l'estat i qualsevol cancel·lació programada |
customer.subscription.deleted | Elimina l'accés de pagament |
customer.subscription.trial_will_end | Recorda a l'usuari que la prova s'acaba; Stripe l'envia tres dies abans |
Les regles per als gestors de la documentació de webhooks de Stripe continuen aplicant-se: verifica la signatura amb el cos en brut, retorna un 2xx ràpidament, gestiona els esdeveniments duplicats i fora d'ordre, i espera reintents. La guia què és un webhook explica la idea, i la guia de pagaments detalla les regles.
Pas a pas
- Crea els productes i els preus en mode de prova de Stripe.
- Afegeix els secrets: la clau secreta, els IDs de preu i, més endavant, el secret de signatura del webhook. Mai no els posis al codi del frontend.
- Pàgina de preus: el botó de cada pla crida el teu servidor, que crea una sessió de Checkout en mode subscripció per a l'usuari que ha iniciat sessió. Passa l'ID del teu usuari perquè el webhook pugui associar el pagament al compte.
- Endpoint de webhook: verifica les signatures i gestiona els esdeveniments anteriors, actualitzant un registre de subscripció per usuari.
- Restringeix les funcions segons l'estat i el pla guardats, comprovats al servidor per a cada acció protegida, no només amb botons amagats.
- Portal de clients: configura'l al Dashboard de Stripe (a quins plans es poden canviar les persones, si poden cancel·lar), després afegeix un botó de Gestiona la facturació que crea una sessió del portal al servidor i redirigeix cap a ell.
- Pagaments fallits: a la configuració de facturació de Stripe, tria el comportament de reintents i què passa després de l'últim reintent. Mostra un avís a l'app mentre estigui en
past_due. - Prova tot el cicle de vida, després publica i registra el webhook de producció.
Indicacions per al teu constructor d'IA
Afegeix facturació per subscripció amb Stripe. Plans: Starter (ID de preu a STRIPE_PRICE_STARTER) i Pro (STRIPE_PRICE_PRO). La pàgina de preus crea una sessió de Checkout en mode subscripció al servidor fent servir STRIPE_SECRET_KEY, amb l'ID de l'usuari que ha iniciat sessió adjunt. Guarda a l'usuari l'ID de client de Stripe, l'ID de subscripció, el pla i l'estat. Mai no exposis la clau secreta al navegador.
Afegeix POST /api/stripe/webhook. Verifica la signatura amb STRIPE_WEBHOOK_SECRET fent servir el cos de la petició en brut. Gestiona checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted i customer.subscription.trial_will_end. Registra els IDs d'esdeveniments processats perquè els duplicats s'ignorin. Actualitza l'estat de l'usuari a partir de l'objecte de subscripció, no a partir de l'ordre en què arribin els esdeveniments.
Restringeix les funcions Pro al servidor: permet-les només quan l'estat sigui active o trialing i el pla sigui Pro. Mostra un avís «el pagament ha fallat, actualitza la teva targeta» quan l'estat sigui past_due. Afegeix un botó de Gestiona la facturació que obri el portal de clients de Stripe per a aquest usuari.
Actualitzacions, rebaixes i prorrateig
Quan un client canvia de pla, la documentació de Stripe diu que el canvi sovint crea un prorrateig: el preu nou s'aplica a la resta del període de facturació actual. Pots previsualitzar els prorrateigs o desactivar-los. Si els plans tenen el mateix interval, les dates de facturació es mantenen; passar de mensual a anual mou la data de facturació al dia del canvi. Deixar que els clients canviïn de pla al portal t'estalvia escriure aquesta lògica, però decideix a la configuració del portal quins canvis estan permesos.
Llista de comprovació de proves
Fes servir el mode de prova de Stripe i les targetes de prova, i repassa cada estat:
- Una subscripció nova dona el pla correcte a l'usuari correcte
- Tancar la pestanya just després de pagar encara dona accés (demostra que el webhook funciona)
- Una targeta rebutjada en registrar-se no dona res
- Una renovació fallida posa el compte en past_due i mostra l'avís
- Actualitzar la targeta al portal restaura l'estat active
- Pujar i baixar de pla canvia les funcions correctament
- Cancel·lar al final del període manté l'accés fins a la data final, i després el treu
- Els usuaris en prova tenen accés, reben el recordatori i es converteixen o perden l'accés correctament
- Enviar el mateix esdeveniment de webhook dues vegades no canvia res
Els rellotges de prova de Stripe et permeten simular el pas del temps, així que pots provar les renovacions sense esperar un mes. Consulta la documentació de proves actual de Stripe per saber com fer-los servir.
Errors habituals
- Donar accés a la pàgina d'èxit. Els clients poden pagar i no arribar-hi mai. Fes servir el webhook.
- Gestionar només el primer pagament. Les renovacions, els fallits i les cancel·lacions arriben més tard, com a esdeveniments.
- Comprovar l'estat del pla només al frontend. Qualsevol pot cridar la teva API directament.
- Un usuari, moltes subscripcions per accident. Comprova si ja hi ha una subscripció abans de crear una nova sessió de Checkout, o envia els clients existents al portal.
- Revocar l'accés al primer renovament fallit. Les targetes fallen per motius avorrits. Un període de gràcia curt amb un avís clar retén els clients.
- Oblidar el webhook de producció. Els endpoints de prova i de producció tenen secrets de signatura diferents.
- Ignorar els impostos i els reembossaments. Decideix la teva política de reembossaments i revisa les teves obligacions fiscals amb un comptable abans del llançament.
Subscripcions a Mythex
Les apps que construeixes a Mythex fan servir el teu propi compte i les teves pròpies claus de Stripe; no hi ha cap connexió d'un sol clic amb Stripe per a la teva app. Afegeix les teves claus de prova i els IDs de preu com a secrets del projecte, fes servir indicacions com les de dalt i prova amb les targetes de prova de Stripe a la Vista prèvia. Els webhooks necessiten la URL pública de la teva app, així que publica abans de registrar l'endpoint a Stripe, i torna a publicar després de passar a les claus de producció perquè l'app en directe les recolleixi. Consulta Accepta pagaments amb Stripe i Gestiona webhooks al teu backend. Per al producte en general, com construir un MVP de SaaS explica què construir al voltant de la facturació.
Preguntes
Quina és la manera més senzilla d'afegir subscripcions amb Stripe?
Crea un producte amb un preu recurrent al Dashboard de Stripe, envia els clients a Stripe Checkout en mode subscripció, gestiona els esdeveniments de subscripció amb un webhook i enllaça un botó de Gestiona la facturació amb el portal de clients allotjat de Stripe. Així t'estalvies construir tu mateix els formularis de targeta i les pantalles de canvi de pla.
Quins esdeveniments de webhook de Stripe necessito per a les subscripcions?
Com a mínim checkout.session.completed per vincular la nova subscripció al teu usuari, invoice.paid per confirmar cada pagament correcte, invoice.payment_failed per avisar de les renovacions fallides, i customer.subscription.updated i customer.subscription.deleted per fer el seguiment dels canvis de pla i les cancel·lacions.
Què passa quan falla un pagament de subscripció?
Segons la documentació de Stripe a setembre de 2026, la subscripció normalment passa a past_due i Stripe pot reintentar el pagament segons la teva configuració. Després de l'últim reintent, la configuració del Dashboard decideix si es cancel·la, es marca com a no pagada o es queda com a past_due.
Puc oferir una prova gratuïta sense demanar una targeta?
Sí. Stripe admet proves gratuïtes, i la seva documentació descriu un estat paused per a les proves que acaben sense mètode de pagament quan està configurat així. Demanar una targeta per endavant normalment vol dir menys registres però més clients que paguen; prova què encaixa amb el teu producte.