Cum adaugi plăți în aplicația ta: checkout, abonamente și webhook-uri

Cel mai simplu mod de a adăuga plăți în aplicația ta este Stripe: folosește un Payment Link dacă ai nevoie doar de un buton „Cumpără” și poți gestiona comenzile manual, Stripe Checkout dacă aplicația ta trebuie să știe cine a plătit și să reacționeze automat, iar Checkout în modul de abonament plus portalul de clienți Stripe pentru facturarea recurentă. În fiecare caz, cu excepția celui mai simplu, ai nevoie și de un webhook — un endpoint de server pe care Stripe îl apelează când o plată reușește — și ar trebui să testezi totul cu cheile de test și cardurile de test Stripe înainte de a trece la cheile live.

Acest ghid explică fiecare opțiune, partea de webhook pe care o sar majoritatea tutorialelor și ce trebuie verificat înainte să încasezi bani reali. Detaliile Stripe provin din documentația proprie a Stripe, la zi cu septembrie 2026.

De ce să folosești un furnizor de plăți

Nu colecta niciodată numere de card în propriile formulare. Gestionarea datelor brute de card te aduce în sfera PCI DSS (standardul de securitate al industriei cardurilor) și este o responsabilitate serioasă. Un furnizor de plăți precum Stripe găzduiește formularul de plată, stochează cardul, se ocupă de autentificarea bancară și îi spune aplicației tale rezultatul. Aplicația ta vede doar „clientul X a plătit pentru Y”.

Acest ghid folosește Stripe pentru că este foarte utilizat, bine documentat și suportat de majoritatea constructorilor de aplicații cu AI. Există și alți furnizori, iar unii acționează ca „merchant of record” și preiau gestionarea taxei pe vânzări în locul tău; dacă conformitatea fiscală te preocupă, merită comparat acest model.

Cele trei moduri de a accepta plăți cu Stripe

Payment Links

Un Payment Link este o pagină de plată găzduită de Stripe, pe care o creezi în Dashboard-ul Stripe fără cod. Primești un URL pe care îl poți pune în spatele unui buton din aplicația ta, îl poți trimite într-un email sau îl poți afișa ca cod QR. Documentația Stripe spune că Payment Links pot vinde un produs, un abonament sau pot accepta o donație, iar poți lăsa clienții să aleagă ce plătesc sau poți limita numărul de achiziții.

Capcana: aplicația ta nu știe automat că un anumit utilizator autentificat a plătit. Pentru o pagină de donații sau un magazin mic în care livrezi comenzile manual, din notificările de email ale Stripe, este în regulă. Pentru „plătește ca să deblochezi funcțiile Pro”, nu este.

Stripe Checkout

Checkout este o pagină de plată pe care serverul tău o creează la cerere, pentru o achiziție concretă. Serverul tău îi spune Stripe ce se cumpără (și, opțional, care client cumpără), Stripe returnează un URL și tu trimiți clientul acolo. Documentația Stripe descrie Checkout ca fiind suport atât pentru plăți unice, cât și pentru abonamente, ca pagină completă găzduită de Stripe, ca pagină încorporată în site-ul tău sau ca formular încorporat.

Fluxul:

1. Clientul apasă Cumpără în aplicația ta.
2. Serverul tău creează o sesiune Checkout folosind cheia ta secretă, incluzând un ID care o leagă de utilizatorul sau comanda ta.
3. Clientul este redirecționat către Stripe și plătește.
4. Stripe îl redirecționează înapoi către pagina ta de succes.
5. Stripe trimite un eveniment checkout.session.completed către webhook-ul tău, iar serverul tău marchează comanda ca plătită sau deblochează accesul.

Pasul 2 trebuie să se întâmple pe server, pentru că folosește cheia ta secretă. Acesta este motivul principal pentru care Checkout are nevoie de backend.

Abonamente

Abonamentele folosesc Checkout în modul de abonament, cu un preț recurent pe care îl configurezi în Stripe. Prima plată funcționează ca fluxul de mai sus. După aceea, reînnoirile, cardurile care eșuează, upgrade-urile și anulările se întâmplă în timp — adesea când clientul nu mai este în aplicația ta — deci aplicația ta află despre ele doar prin webhook-uri.

Pentru ca un client să își gestioneze singur abonamentul, Stripe oferă un portal de clienți găzduit. Conform documentației Stripe, clienții pot actualiza metodele de plată și datele de facturare, pot schimba sau anula abonamentele și pot vedea și descărca facturile acolo. Îl configurezi în Dashboard-ul Stripe și adaugi un buton „Gestionează facturarea” care îl trimite pe client acolo. Așa nu mai trebuie să construiești tu aceste ecrane.

Webhook-urile: partea pe care nu o poți sări

Un webhook este o cerere HTTP pe care Stripe o trimite serverului tău când se întâmplă ceva. (Vezi ce este un webhook pentru ideea generală.) Ghidul de livrare al Stripe este clar: nu te poți baza doar pe pagina de succes ca să livrezi comenzi, pentru că un client poate plăti și apoi își poate pierde conexiunea înainte să se încarce pagina. Pentru abonamente și metode de plată întârziate, webhook-urile sunt obligatorii.

Evenimentele care merită gestionate

Reguli pentru un handler de webhook corect

Acestea provin direct din documentația Stripe pentru webhook-uri, iar handler-ele generate cu AI le ratează uneori:

• Verifică semnătura. Fiecare eveniment include un header Stripe-Signature. Handler-ul tău o verifică folosind secretul de semnare al endpoint-ului (începe cu whsec_). Fără asta, oricine ar putea trimite un fals „plată reușită” către serverul tău.
• Folosește corpul brut al cererii. Verificările de semnătură eșuează dacă framework-ul tău parsează sau modifică întâi corpul.
• Returnează rapid un răspuns 2xx, apoi fă lucrul mai lent. Timeout-urile contează ca eșecuri.
• Tratează duplicatele. Stripe poate livra același eveniment de mai multe ori. Înregistrează ID-urile evenimentelor procesate sau fă livrarea sigură la rulare dublă.
• Nu presupune ordinea. Stripe nu garantează că evenimentele sosesc în ordinea în care au avut loc.
• Așteaptă reîncercări. În modul live, Stripe reîncearcă livrările eșuate timp de până la trei zile, deci o scurtă pană nu pierde plăți — dar handler-ul tău trebuie să facă față evenimentelor târzii.

Webhook-urile au nevoie de o adresă HTTPS publică, deci de obicei funcționează doar după ce aplicația ta este publicată (CLI-ul Stripe poate redirecționa evenimentele către o mașină locală pentru dezvoltatori).

Un prompt care acoperă întregul flux

Adaugă o achiziție unică cu Stripe Checkout pentru „Pro pack” (ID-ul prețului în STRIPE_PRICE_ID). Creează sesiunea Checkout pe server folosind STRIPE_SECRET_KEY din secrete și include ID-ul utilizatorului autentificat în sesiune. Adaugă un endpoint POST /api/stripe/webhook care verifică semnătura Stripe cu STRIPE_WEBHOOK_SECRET folosind corpul brut al cererii, gestionează checkout.session.completed și marchează acel utilizator ca având Pro pack. Asigură-te că e sigur dacă același eveniment sosește de două ori. Pagini de succes și de anulare. Nu expune niciodată cheia secretă în browser.

Pentru abonamente, adaugă: „Folosește modul de abonament cu STRIPE_PRICE_ID. Gestionează invoice.paid, invoice.payment_failed, customer.subscription.updated și customer.subscription.deleted. Adaugă un buton Gestionează facturarea care deschide portalul de clienți Stripe.”

Modul de test

Stripe are medii separate de sandbox (test) și live, cu chei separate. Cheile de sandbox încep cu pk_test_, sk_test_ sau rk_test_; cheile live încep cu pk_live_, sk_live_ sau rk_live_. Tranzacțiile de test nu mută bani.

Carduri de test utile din documentația Stripe pentru testare (orice dată de expirare din viitor, orice CVC de trei cifre):

Testează cel puțin:

• O plată reușită deblochează lucrul corect pentru utilizatorul corect
• Un card refuzat afișează un mesaj clar și nu deblochează nimic
• Închiderea tab-ului browserului imediat după plată tot duce la acces (asta dovedește că webhook-ul funcționează, nu doar pagina de succes)
• Anularea pe pagina Stripe îl întoarce pe utilizator în aplicația ta, fără nicio sumă debitată
• Pentru abonamente: anulează în portalul de clienți și confirmă că accesul se termină când trebuie

Trecerea în producție

1. Activează-ți contul Stripe cu datele firmei și ale băncii.
2. Pune cheile live în secretele aplicației tale. Stripe recomandă chei restricționate, cu doar permisiunile de care are nevoie integrarea ta, nu o cheie secretă nerestricționată.
3. Creează un endpoint de webhook live care indică spre aplicația ta publicată. Are propriul secret de semnare, diferit de cel de test — actualizează-l.
4. Recreează produsele și prețurile în modul live; ID-urile din modul de test nu există acolo.
5. Fă o cumpărătură reală, mică și rambursează-o.

Păstrează fiecare cheie în secretele proiectului tău, niciodată în cod sau în chat. Lista noastră de verificare pentru securitate acoperă mai detaliat cheile și verificarea webhook-urilor.

Taxe, rambursări și documente

Plățile aduc obligații pe care codul nu le rezolvă. Acesta nu este sfat fiscal; verifică cu un contabil.

• Taxa pe vânzări, TVA și GST. În funcție de locul în care ești tu și clienții tăi, s-ar putea să trebuiască să te înregistrezi, să aplici și să depui taxa. Stripe Tax poate calcula și colecta taxa la checkout, poate monitoriza unde vânzările tale pot crea o obligație și poate ajuta cu înregistrările și declarațiile — dar responsabilitatea rămâne a ta. Furnizorii de tip merchant of record sunt o alternativă care preia mai mult din asta.
• Rambursări și dispute. Decide politica de rambursare înainte de lansare și pune-o pe site. Disputele (chargeback-urile) se întâmplă; păstrează evidențe despre ce a fost cumpărat și livrat.
• Chitanțe și facturi. Stripe poate trimite chitanțe prin email; firmele pot avea nevoie de facturi în regulă.
• Comisioane. Fiecare furnizor percepe o taxă per tranzacție. Verifică pagina actuală de prețuri a furnizorului, în loc să te bazezi pe cifrele din articole.

Ce configurare se potrivește aplicației tale

• Donații sau câteva produse: Payment Links. Vezi cum construiești un site de donații pentru o organizație nonprofit.
• Un magazin cu coș: Checkout cu line items și webhook. Vezi cum construiești un magazin online.
• SaaS sau abonamente de membru: Checkout în modul de abonament, webhook-uri și portalul de clienți. Vezi cum construiești un MVP SaaS și cum stabilești prețul unui produs SaaS.
• Un marketplace care plătește vânzătorii: o configurare diferită, mai reglementată (Stripe Connect sau similar). Planific-o separat.

Adăugarea plăților în Mythex

Plățile din aplicațiile construite pe Mythex folosesc propriul tău cont Stripe și propriile chei; nu există o conectare „Connect Stripe” cu un singur clic pentru aplicația ta. Fluxul obișnuit:

1. Ia chei Stripe de test.
2. Adaugă STRIPE_SECRET_KEY (și secretul webhook-ului mai târziu) în secretele proiectului — prin /secrets, setările proiectului sau cardul de secrete pe care îl arată agentul când are nevoie de o cheie.
3. Cere agentului Checkout folosind un prompt ca cel de mai sus.
4. Testează în Preview cu carduri de test. Publică înainte să înregistrezi webhook-ul, pentru că are nevoie de URL-ul tău public.
5. După ce treci la cheile live, publică din nou ca aplicația live să le preia.

Vezi Acceptă plăți cu Stripe și Gestionează webhook-uri în backend-ul tău în documentație.

Întrebări