Si të shtosh pagesa në aplikacionin tënd: arkëtim, abonime dhe webhook-e

Mënyra më e thjeshtë për të shtuar pagesa në aplikacionin tënd është Stripe: përdor një Payment Link nëse të duhet vetëm një buton "Bli" dhe mund t'i trajtosh porositë me dorë; Stripe Checkout nëse aplikacioni yt duhet të dijë kush ka paguar dhe të reagojë automatikisht; dhe Checkout në modalitetin e abonimit plus portalin e klientit të Stripe për faturimin e përsëritur. Në çdo rast përveç më të thjeshtit, të duhet edhe një webhook — një endpoint në server që Stripe e thërret kur një pagesë përfundon me sukses — dhe duhet të testosh gjithçka me çelësat test dhe kartat test të Stripe përpara se të kalosh te çelësat live.

Ky udhëzues shpjegon çdo opsion, pjesën e webhook-ut që shumica e tutorialeve e kalojnë shpejt, dhe çfarë duhet kontrolluar përpara se të pranosh para të vërteta. Detajet e Stripe janë nga dokumentacioni i vetë Stripe, sipas shtatorit 2026.

Pse të përdorësh fare një ofrues pagesash

Kurrë mos mblidh numra kartash në format e tua. Trajtimi i të dhënave të papërpunuara të kartës të bën subjekt të PCI DSS (standardi i sigurisë i industrisë së kartave) dhe është një përgjegjësi e rëndë. Një ofrues pagesash si Stripe e hoston formën e pagesës, ruan kartën, merret me vërtetimin e bankës dhe i tregon aplikacionit tënd rezultatin. Aplikacioni yt sheh vetëm "klienti X paguan për Y".

Ky udhëzues përdor Stripe sepse është i përdorur gjerësisht, i dokumentuar mirë dhe i mbështetur nga shumica e ndërtuesve të aplikacioneve me AI. Ekzistojnë edhe ofrues të tjerë, dhe disa veprojnë si "tregtar i regjistruar" që merr përsipër trajtimin e taksës së shitjes për ty; nëse përputhshmëria tatimore të shqetëson, ky model vlen të krahasohet.

Tre mënyrat për të pranuar pagesa me Stripe

Payment Links

Një Payment Link është një faqe pagese e hostuar nga Stripe që e krijon në Stripe Dashboard pa kod. Merr një URL që mund ta vendosësh pas një butoni në aplikacion, ta ndash në një email ose ta shfaqësh si kod QR. Dokumentacioni i Stripe thotë se Payment Links mund të shesin një produkt, një abonim ose të pranojnë një donacion, dhe mund t'i lësh klientët të zgjedhin çfarë paguajnë ose të kufizosh numrin e blerjeve.

Kurthi: aplikacioni yt nuk e di automatikisht që një përdorues i caktuar i kyçur ka paguar. Për një faqe donacionesh ose një dyqan të vogël ku i përmbush porositë me dorë nga njoftimet email të Stripe, kjo është në rregull. Për "paguaj për të zhbllokuar veçoritë Pro", nuk është.

Stripe Checkout

Checkout është një faqe pagese që serveri yt e krijon sipas kërkesës për një blerje specifike. Serveri yt i tregon Stripe çfarë po blihet (dhe opsionalisht cili klient po blen), Stripe kthen një URL, dhe ti e dërgon klientin atje. Dokumentacioni i Stripe e përshkruan si mbështetës për pagesa të vetme dhe për abonime, si një faqe e plotë e hostuar nga Stripe, një faqe e integruar në sajtin tënd ose një formë e integruar.

Rrjedha:

1. Klienti klikon Bli në aplikacionin tënd.
2. Serveri yt krijon një Checkout Session duke përdorur çelësin tënd sekret, duke përfshirë një ID që e lidh me përdoruesin ose porosinë tënde.
3. Klienti ridrejtohet te Stripe dhe paguan.
4. Stripe e ridrejton përsëri te faqja jote e suksesit.
5. Stripe dërgon një ngjarje checkout.session.completed te webhook-u yt, dhe serveri yt e shënon porosinë si të paguar ose hap aksesin.

Hapi 2 duhet të ndodhë në server, sepse përdor çelësin tënd sekret. Ky është arsyeja kryesore pse Checkout kërkon një backend.

Abonimet

Abonimet përdorin Checkout në modalitetin e abonimit me një çmim të përsëritur që ke konfiguruar në Stripe. Pagesa e parë funksionon si rrjedha e mësipërme. Pas kësaj, rinovimet, kartat e dështuara, përmirësimet dhe anulimet ndodhin me kalimin e kohës — shpesh kur klienti nuk është fare në aplikacionin tënd — kështu që aplikacioni yt i mëson ato vetëm përmes webhook-ëve.

Për t'i lënë klientët të menaxhojnë vetë abonimin, Stripe ofron një portal klienti të hostuar. Sipas dokumentacionit të Stripe, aty klientët mund të përditësojnë mënyrat e pagesës dhe të dhënat e faturimit, të ndryshojnë ose anulojnë abonimet, dhe të shohin e shkarkojnë faturat. E konfiguron në Stripe Dashboard dhe shton një buton "Menaxho faturimin" që e dërgon klientin atje. Kjo të kursen ndërtimin e atyre ekraneve vetë.

Webhook-et: pjesa që nuk mund ta kalosh

Një webhook është një kërkesë HTTP që Stripe ia dërgon serverit tënd kur ndodh diçka. (Shiko çfarë është një webhook për idenë e përgjithshme.) Udhëzuesi i përmbushjes së Stripe është i qartë: nuk mund të mbështetesh vetëm në faqen e suksesit për të përmbushur porositë, sepse një klient mund të paguajë dhe pastaj të humbasë lidhjen para se ajo faqe të ngarkohet. Për abonimet dhe metodat e pagesës me vonesë, webhook-et janë të detyrueshme.

Ngjarjet që meriton të trajtosh

Rregullat për një trajtues webhook të saktë

Këto vijnë drejtpërdrejt nga dokumentacioni i Stripe për webhook-et, dhe trajtuesit e gjeneruar me AI ndonjëherë i humbasin:

• Verifiko nënshkrimin. Çdo ngjarje përfshin një header Stripe-Signature. Trajtuesi yt e kontrollon me çelësin e nënshkrimit të endpoint-it (fillon me whsec_). Pa këtë, kushdo mund t'i dërgonte serverit tënd një "pagesë u krye" të rremë.
• Përdor trupin e papërpunuar të kërkesës. Kontrollet e nënshkrimit dështojnë nëse framework-u yt e analizon ose e ndryshon trupin para se të kontrollohet.
• Kthe përgjigje 2xx shpejt, pastaj bëj punën më të ngadaltë. Kohët e pritjes numërohen si dështime.
• Trajto dublikatat. Stripe mund të dërgojë të njëjtën ngjarje më shumë se një herë. Regjistro ID-të e ngjarjeve të përpunuara, ose bëj përmbushjen të sigurt për t'u ekzekutuar dy herë.
• Mos supozo renditjen. Stripe nuk garanton që ngjarjet të arrijnë në të njëjtën renditje me të cilën ndodhën.
• Prit rifillime. Në modalitetin live, Stripe i riprovon dërgimet e dështuara deri në tre ditë, kështu që një ndërprerje e shkurtër nuk humb pagesa — por trajtuesi yt duhet t'i përballojë ngjarjet e vonuara.

Webhook-et kanë nevojë për një adresë publike HTTPS, kështu që zakonisht funksionojnë vetëm pasi aplikacioni yt të jetë publikuar (CLI i Stripe mund t'i përcjellë ngjarjet te një kompjuter lokal për zhvilluesit).

Një prompt që mbulon gjithë rrjedhën

Shto një blerje të vetme me Stripe Checkout për "Pro pack" (ID e çmimit në STRIPE_PRICE_ID). Krijo Checkout Session në server duke përdorur STRIPE_SECRET_KEY nga sekretet, dhe përfshi ID-në e përdoruesit të kyçur në sesion. Shto një endpoint POST /api/stripe/webhook që verifikon nënshkrimin e Stripe me STRIPE_WEBHOOK_SECRET duke përdorur trupin e papërpunuar të kërkesës, trajton checkout.session.completed, dhe shënon atë përdorues si të pajisur me Pro pack. Bëje të sigurt nëse i njëjti event arrin dy herë. Faqe suksesi dhe anulimi. Mos e ekspozo kurrë çelësin sekret në shfletues.

Për abonimet, shto: "Përdor modalitetin e abonimit me STRIPE_PRICE_ID. Trajto invoice.paid, invoice.payment_failed, customer.subscription.updated dhe customer.subscription.deleted. Shto një buton Menaxho faturimin që hap portalin e klientit të Stripe."

Modaliteti test

Stripe ka mjedise sandbox (test) dhe live të ndara me çelësa të ndarë. Çelësat sandbox fillojnë me pk_test_, sk_test_ ose rk_test_; çelësat live fillojnë me pk_live_, sk_live_ ose rk_live_. Transaksionet test nuk lëvizin para.

Karta test të dobishme nga dokumentacioni i testimit të Stripe (çdo datë skadimi në të ardhmen, çdo CVC me tre shifra):

Testo të paktën:

• Një pagesë e suksesshme hap atë që duhet për përdoruesin e duhur
• Një kartë e refuzuar shfaq një mesazh të qartë dhe nuk hap asgjë
• Mbyllja e skedës së shfletuesit menjëherë pas pagesës ende jep akses (kjo vërteton që webhook-u funksionon, jo vetëm faqja e suksesit)
• Anulimi në faqen e Stripe e kthen përdoruesin te aplikacioni yt pa asnjë ngarkesë
• Për abonimet: anulo në portalin e klientit dhe konfirmo që aksesi përfundon kur duhet

Hyrja në publik

1. Aktivizo llogarinë tënde Stripe me të dhënat e biznesit dhe bankës.
2. Vendos çelësat live në sekretet e aplikacionit tënd. Stripe rekomandon çelësa të kufizuar me vetëm lejet që ka nevojë integrimi yt, në vend të një çelësi sekret pa kufizime.
3. Krijo një endpoint webhook live që tregon te aplikacioni yt i publikuar. Ka çelësin e vet nënshkrimi, të ndryshëm nga ai test — përditëso.
4. Rikrijo produktet dhe çmimet në modalitetin live; ID-të e modalitetit test nuk ekzistojnë atje.
5. Bëj një blerje reale të vogël dhe rimburso.

Mbaj çdo çelës në sekretet e projektit tënd, kurrë në kod ose në chat. Lista jonë e sigurisë mbulon më në detaj çelësat dhe verifikimin e webhook-ëve.

Taksat, rimbursimet dhe dokumentet

Pagesat sjellin detyrime që kodi nuk i zgjidh. Ky nuk është këshillim tatimor; konsulto një kontabilist.

• Taksa e shitjes, TVSH-ja dhe GST. Varësisht nga ku ndodheni ti dhe klientët e tu, mund të duhet të regjistrohesh, të aplikosh dhe të dorëzosh taksë. Stripe Tax mund ta llogarisë dhe mbledhë taksën në checkout, të monitorojë ku shitjet e tua mund të krijojnë një detyrim, dhe të ndihmojë me regjistrimet dhe dorëzimin — por përgjegjësia mbetet e jotja. Ofruesit e tregtarit të regjistruar janë një alternativë që merr përsipër më shumë nga kjo.
• Rimbursimet dhe kontestet. Vendos politikën e rimbursimit para lansimit dhe vendose në sajt. Kontestet (chargebacks) ndodhin; mbaj regjistrime të asaj që u bler dhe u dorëzua.
• Faturat dhe kuponat. Stripe mund t'i dërgojë faturat me email; bizneset mund të kenë nevojë për fatura të rregullta.
• Tarifat. Çdo ofrues merr një tarifë për transaksion. Kontrollo faqen aktuale të çmimeve të ofruesit në vend që të mbështetesh në shifrat e artikujve.

Cila konfigurim i përshtatet aplikacionit tënd

• Donacione ose disa produkte: Payment Links. Shiko si të ndërtosh një faqe donacionesh jofitimprurëse.
• Një dyqan me shportë: Checkout me artikuj rreshtash dhe një webhook. Shiko si të ndërtosh një dyqan online.
• SaaS ose anëtarësime: Checkout në modalitetin e abonimit, webhook-et dhe portali i klientit. Shiko si të ndërtosh një MVP SaaS dhe si të vendosësh çmimin e një produkti SaaS.
• Një treg që paguan shitësit: një konfigurim tjetër, më i rregulluar (Stripe Connect ose e ngjashme). Planifikoje veçmas.

Shtimi i pagesave në Mythex

Pagesat në aplikacionet që ndërton në Mythex përdorin llogarinë tënde Stripe dhe çelësat e tu; nuk ka një "Connect Stripe" me një klik për aplikacionin tënd. Rrjedha e zakonshme:

1. Merr çelësat test të Stripe.
2. Shto STRIPE_SECRET_KEY (dhe sekretin e webhook-ut më vonë) te sekretet e projektit — përmes /secrets, cilësimeve të projektit, ose kartës së sekreteve që agjenti shfaq kur i duhet një çelës.
3. Kërko nga agjenti Checkout me një prompt si ai më sipër.
4. Testo në Preview me karta test. Publiko përpara se të regjistrosh webhook-un, sepse ai kërkon URL-në tënde publike.
5. Pasi kalon te çelësat live, publiko përsëri që aplikacioni live t'i marrë.

Shiko Prano pagesa me Stripe dhe Trajto webhook-et në backend-in tënd në dokumentacion.

Pyetje