Cum adaugi abonamente cu Stripe: planuri, perioade de probă, webhook-uri și plăți eșuate

Pentru a adăuga abonamente cu Stripe, creează un produs cu un preț recurent în Dashboard-ul Stripe, trimite clienții la Stripe Checkout în modul de abonament din serverul tău și lasă un webhook să îți spună aplicației când fiecare plată reușește, eșuează, se schimbă sau se încheie. Stochează starea abonamentului pe utilizator și acordă accesul pe baza ei, nu pe baza paginii de succes. Adaugă un buton Gestionează facturarea care deschide portalul de clienți găzduit de Stripe, ca oamenii să poată schimba cardurile, schimba planurile și anula fără să construiești tu acele ecrane.

Acest ghid se bazează pe cum adaugi plăți în aplicația ta, care acoperă Checkout pentru o singură plată, modul de test și trecerea în producție. Aici ne concentrăm pe ce este diferit la facturarea recurentă. Detaliile Stripe provin din documentația Stripe la zi cu septembrie 2026.

De ce abonamentele sunt mai grele decât plățile unice

O plată unică se întâmplă cât timp clientul este în aplicația ta. Un abonament continuă să se întâmple după ce pleacă: reînnoiri lunare, carduri care expiră, upgrade-uri în mijlocul ciclului, anulări care intră în vigoare la sfârșitul perioadei. Aplicația ta află despre acestea doar prin webhook-uri. Majoritatea bug-urilor de abonament apar când se tratează prima plată ca fiind toată povestea.

Opțiunile tale

Pentru majoritatea aplicațiilor, Checkout plus portalul este compromisul potrivit. Compară furnizorii în Stripe vs Paddle vs Lemon Squeezy dacă gestionarea taxelor te preocupă.

Planifică-ți prețurile în Stripe întâi

În Stripe, un produs este ce vinzi („Planul Pro”), iar un preț este cum îl încasezi („99 lei pe lună”, „990 lei pe an”). Un produs poate avea mai multe prețuri. Decide:

• Ce niveluri oferi și ce deblochează fiecare în aplicația ta
• Lunar, anual sau ambele
• Dacă oferi o perioadă de probă și dacă aceasta cere un card din start

Creează produsele și prețurile în modul de test și păstrează ID-urile prețurilor; aplicația ta se referă la ele. Dacă nu ți-ai stabilit încă prețurile, citește cum stabilești prețul unui produs SaaS și freemium vs perioadă de probă gratuită.

Ciclul de viață al abonamentului pe care trebuie să îl gestionezi

Documentația Stripe despre abonamente listează stările pe care le poate avea un abonament. Cele care contează cel mai mult pentru acces:

Stochează starea pe înregistrarea utilizatorului sau a contului și bazează accesul pe ea. Actualizeaz-o de fiecare dată când sosește un webhook relevant.

Evenimentele webhook de gestionat

Regulile pentru handler din documentația Stripe despre webhook-uri se aplică în continuare: verifică semnătura folosind corpul brut, returnează rapid un 2xx, gestionează evenimentele duplicate și care sosesc în altă ordine și așteaptă reîncercări. Ghidul ce este un webhook explică ideea, iar ghidul despre plăți enumeră regulile în detaliu.

Pas cu pas

1. Creează produse și prețuri în modul de test Stripe.
2. Adaugă secretele: cheia secretă, ID-urile prețurilor și, mai târziu, secretul de semnare al webhook-ului. Niciodată în codul de frontend.
3. Pagina de prețuri: butonul fiecărui plan apelează serverul tău, care creează o sesiune Checkout în modul de abonament pentru utilizatorul conectat. Trimite ID-ul utilizatorului tău, ca webhook-ul să potrivească plata cu contul.
4. Endpoint de webhook: verifică semnăturile și gestionează evenimentele de mai sus, actualizând câte o înregistrare de abonament pe utilizator.
5. Blochează funcțiile pe baza stării și planului stocate, verificate pe server pentru fiecare acțiune protejată, nu doar butoane ascunse.
6. Portalul de clienți: configureaz-l în Dashboard-ul Stripe (la ce planuri pot trece oamenii, dacă pot anula), apoi adaugă un buton Gestionează facturarea care creează o sesiune de portal pe server și redirecționează acolo.
7. Plăți eșuate: în setările de facturare Stripe, alege comportamentul de reîncercare și ce se întâmplă după ultima reîncercare. Afișează un banner în aplicație cât timp este past_due.
8. Testează întregul ciclu de viață, apoi publică și înregistrează webhook-ul live.

Prompturi pentru constructorul tău cu AI

Adaugă facturare de abonament cu Stripe. Planuri: Starter (ID-ul prețului în STRIPE_PRICE_STARTER) și Pro (STRIPE_PRICE_PRO). Pagina de prețuri creează o sesiune Checkout în modul de abonament pe server, folosind STRIPE_SECRET_KEY, cu ID-ul utilizatorului conectat atașat. Salvează ID-ul clientului Stripe, ID-ul abonamentului, planul și starea pe utilizator. Nu expune niciodată cheia secretă în browser.

Adaugă POST /api/stripe/webhook. Verifică semnătura cu STRIPE_WEBHOOK_SECRET folosind corpul brut al cererii. Gestionează checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted și customer.subscription.trial_will_end. Înregistrează ID-urile evenimentelor procesate, ca duplicatele să fie ignorate. Actualizează starea utilizatorului din obiectul de abonament, nu din ordinea în care sosesc evenimentele.

Blochează funcțiile Pro pe server: permite-le doar când starea este active sau trialing și planul este Pro. Afișează un banner „plata a eșuat, actualizează-ți cardul” când starea este past_due. Adaugă un buton Gestionează facturarea care deschide portalul de clienți Stripe pentru acest utilizator.

Upgrade-uri, downgrade-uri și proratare

Când un client schimbă planul, documentația Stripe spune că schimbarea creează adesea o proratare: noul preț se aplică pentru restul perioadei de facturare curente. Poți previzualiza proratările sau le poți dezactiva. Dacă planurile au același interval, datele de facturare rămân aceleași; trecerea de la lunar la anual mută data facturării la ziua schimbării. Lăsarea clienților să schimbe planurile în portal te scutește de scrierea acestei logici, dar decide în setările portalului ce schimbări sunt permise.

Lista de verificare a testării

Folosește modul de test Stripe și cardurile de test și parcurge fiecare stare:

• Un abonament nou acordă planul corect utilizatorului corect
• Închiderea tab-ului imediat după plată tot acordă accesul (dovedește că webhook-ul funcționează)
• Un card refuzat la înscriere nu acordă nimic
• O reînnoire eșuată pune contul în past_due și afișează bannerul
• Actualizarea cardului în portal restabilește starea active
• Upgrade-ul și downgrade-ul schimbă corect funcțiile
• Anularea la sfârșitul perioadei păstrează accesul până la data de sfârșit, apoi îl elimină
• Utilizatorii în perioadă de probă au acces, primesc memento-ul și se convertesc sau pierd accesul corect
• Trimiterea aceluiași eveniment webhook de două ori nu schimbă nimic

Testele de ceas ale Stripe îți permit să simulezi trecerea timpului, ca să testezi reînnoirile fără să aștepți o lună. Verifică documentația actuală de testare a Stripe pentru cum se folosesc.

Greșeli frecvente

• Acordarea accesului pe pagina de succes. Clienții pot plăti și să nu ajungă niciodată la ea. Folosește webhook-ul.
• Gestionarea doar a primei plăți. Reînnoirile, eșecurile și anulările sosesc mai târziu, ca evenimente.
• Verificarea stării planului doar în frontend. Oricine poate apela direct API-ul tău.
• Un utilizator, mai multe abonamente din greșeală. Verifică dacă există deja un abonament înainte să creezi o nouă sesiune Checkout sau trimite clienții existenți în portal.
• Revocarea accesului la prima reînnoire eșuată. Cardurile eșuează din motive banale. O scurtă perioadă de grație cu un banner clar îi păstrează pe clienți.
• Uitarea webhook-ului live. Endpoint-urile de test și cele live au secrete de semnare diferite.
• Ignorarea taxelor și a rambursărilor. Decide politica de rambursare și verifică-ți obligațiile fiscale cu un contabil înainte de lansare.

Abonamentele în Mythex

Aplicațiile construite pe Mythex folosesc propriul tău cont Stripe și propriile chei; nu există o conectare Stripe cu un singur clic pentru aplicația ta. Adaugă cheile tale de test și ID-urile prețurilor ca secrete ale proiectului, folosește prompturi ca cele de mai sus și testează cu cardurile de test Stripe în Preview. Webhook-urile au nevoie de URL-ul public al aplicației tale, deci publică înainte să înregistrezi endpoint-ul în Stripe și publică din nou după ce treci la cheile live, ca aplicația live să le preia. Vezi Acceptă plăți cu Stripe și Gestionează webhook-uri în backend-ul tău. Pentru restul produsului, cum construiești un MVP SaaS acoperă ce construiești în jurul facturării.

Întrebări