Kuidas lisada äppi makseid: kassa, tellimused ja webhook'id

Kõige lihtsam viis makseid oma äppi lisada on Stripe: kasuta makselinki (Payment Link), kui vajad ainult nuppu „Osta“ ja saad tellimusi käsitsi töödelda; Stripe Checkouti, kui su äpp peab teadma, kes maksis, ja reageerima automaatselt; ning Checkouti tellimusrežiimis koos Stripe'i kliendiportaaliga korduva arveldamise jaoks. Igal juhul peale kõige lihtsama variandi vajad ka webhook'i – serveri lõpp-punkti, kuhu Stripe pöördub, kui makse õnnestub – ja enne päris raha vastu võtmist tuleb kõike testida Stripe'i testvõtmetega ja testkaartidega.

See juhend selgitab iga valikut, webhook'i osa, mida enamik õpetusi vahele jätab, ja mida kontrollida enne päris raha vastu võtmist. Stripe'i üksikasjad on pärit Stripe'i enda dokumentatsioonist seisuga september 2026.

Miks üldse kasutada makseteenuse pakkujat

Ära kogu kunagi kaardinumbreid oma vormides. Kaardiandmete käsitlemine seab sind PCI DSS-i (kaarditööstuse turvastandard) reguleerimisalasse ja on tõsine vastutus. Makseteenuse pakkuja, nagu Stripe, hostib makse vormi, salvestab kaardi, tegeleb panga autentimisega ja ütleb sinu äpile tulemuse. Su äpp näeb ainult: „klient X maksis Y eest“.

See juhend kasutab Stripe'i, sest seda kasutatakse laialdaselt, see on hästi dokumenteeritud ja enamik AI-äpiloojaid toetab seda. On ka teisi pakkujaid ning mõned toimivad „müügi pidajana“ (merchant of record), kes võtavad enda kanda müügimaksu käsitluse; kui maksuvastavus muret teeb, tasub seda mudelit võrrelda.

Kolm võimalust makseteks Stripe'iga

Payment Links

Payment Link on Stripe'i hostitud maksmislehekülg, mille loed Stripe'i juhtpaneelis ilma koodita. Saad URL-i, mille võid panna nupu taha oma äpis, jagada e-kirjas või näidata QR-koodina. Stripe'i dokumentatsiooni järgi saab Payment Linkidega müüa toodet, tellimust või koguda annetusi, ning võid lasta klientidel valida, mida maksta, või piirata ostude arvu.

Lõks: su äpp ei tea automaatselt, et konkreetne sisseloginud kasutaja maksis. Annetuste lehe või väikese poe puhul, kus tellimused täidad käsitsi Stripe'i e-posti teavituste põhjal, on see sobiv. „Maksa Pro-funktsioonide avamiseks“ jaoks see ei sobi.

Stripe Checkout

Checkout on maksmisleht, mille su server loob nõudmisel konkreetse ostu jaoks. Su server ütleb Stripe'ile, mida ostetakse (ja vajadusel, milline klient ostab), Stripe tagastab URL-i ja saadad kliendi sinna. Stripe'i dokumentatsiooni järgi toetab see nii ühekordseid kui tellimusmakseid, olles täielikult Stripe'i hostitud leht, sinu saidi sisse põimitud leht või sisse põimitud vorm.

Voog:

1. Klient vajutab äpis nuppu Osta.
2. Sinu server loob Checkouti sessiooni, kasutades oma salajast võtit, sealhulgas ID-d, mis seob sessiooni sinu kasutaja või tellimusega.
3. Klient suunatakse Stripe'i ja maksab.
4. Stripe suunab ta tagasi sinu edulehele.
5. Stripe saadab sündmuse checkout.session.completed sinu webhook'ile ja su server märgib tellimuse makstuks või avab ligipääsu.

Samm 2 peab toimuma serveris, sest see kasutab sinu salajast võtit. Just see on peamine põhjus, miks Checkout vajab taustateenust.

Tellimused

Tellimused kasutavad Checkouti tellimusrežiimi, kus on seadistatud korduv hind Stripe'is. Esimene makse toimub nagu ülal kirjeldatud voog. Pärast seda toimuvad uuendamised, ebaõnnestunud kaardimaksed, paketi muutmised ja tühistamised aja jooksul – sageli siis, kui klient ei ole sinu äpis – seega saab sinu äpp neist teada ainult webhook'ide kaudu.

Et kliendid saaksid oma tellimust ise hallata, pakub Stripe hostitud kliendiportaali. Stripe'i dokumentatsiooni järgi saavad kliendid seal muuta makseviise ja arveldusandmeid, muuta või tühistada tellimusi ning vaadata ja alla laadida arveid. Seadistad selle Stripe'i juhtpaneelis ja lisad nupu „Halda arveldust“, mis saadab kliendi sinna. Nii ei pea ise neid ekraane ehitama.

Webhook'id: osa, millest ei saa mööda

Webhook on HTTP-päring, mille Stripe saadab sinu serverile, kui midagi juhtub. (Üldise idee selgitab mis on webhook.) Stripe'i täitmisjuhend on selge: tellimusi ei tohi täita ainult edulehe põhjal, sest klient võib maksta ja kaotada ühenduse enne, kui leht laeb. Tellimuste ja viivitatud makseviiside puhul on webhook'id kohustuslikud.

Sündmused, mida tasub käsitleda

Korrektse webhook'i käitleja reeglid

Need pärinevad otse Stripe'i webhook'ide dokumentatsioonist ning AI-genereeritud käitlejatel jääb neist mõni vahele:

• Kontrolli allkirja. Igal sündmusel on päis Stripe-Signature. Su käitleja kontrollib seda lõpp-punkti allkirjastamise saladuse abil (see algab whsec_-ga). Ilma selleta võiks keegi saata sinu serverile võltsitud „makse õnnestus“.
• Kasuta toorkeha (raw request body). Allkirja kontroll ebaõnnestub, kui raamistik keha enne parsib või muudab.
• Tagasta 2xx vastus kiiresti ja tee aeglasem töö hiljem. Ajalõpud loetakse ebaõnnestumisteks.
• Käsitle dubleerimisi. Stripe võib sama sündmuse kätte toimetada mitu korda. Salvesta töödeldud sündmuste ID-d või tee täitmine turvaliseks kahekordse käivitamise korral.
• Ära eelda järjekorda. Stripe ei taga, et sündmused saabuvad toimumise järjekorras.
• Arvesta kordusprobleemidega. Live-režiimis proovib Stripe ebaõnnestunud toimetamisi uuesti kuni kolm päeva, nii et lühike katkestus ei kao makseid – aga sinu käitleja peab hakkama saama hilinenud sündmustega.

Webhook'id vajavad avalikku HTTPS-aadressit, seega töötavad need tavaliselt alles siis, kui su äpp on avaldatud (Stripe'i CLI saab arendajatele sündmusi edastada kohalikku masinasse).

Üks prompt, mis katab kogu voo

Lisa ühekordne ost Stripe Checkouti abil paketile „Pro pack“ (hinna ID STRIPE_PRICE_ID-s). Loo Checkouti sessioon serveris, kasutades saladustest STRIPE_SECRET_KEY, ja lisa sessiooni sisse sisseloginud kasutaja ID. Lisa POST /api/stripe/webhook lõpp-punkt, mis kontrollib Stripe'i allkirja STRIPE_WEBHOOK_SECRET abil toorkehast, käsitleb checkout.session.completed sündmust ja märgib selle kasutaja Pro pack'i omajaks. Tee see turvaliseks, kui sama sündmus tuleb kaks korda. Lisa edu- ja tühistamislehed. Ära kunagi too salajast võtit brauserisse.

Tellimuste jaoks lisa: „Kasuta tellimusrežiimi STRIPE_PRICE_ID-ga. Käsitle invoice.paid, invoice.payment_failed, customer.subscription.updated ja customer.subscription.deleted. Lisa nupp Halda arveldust, mis avab Stripe'i kliendiportaali.“

Testrežiim

Stripe'il on eraldi liivakasti (test) ja live-keskkonnad eraldi võtmetega. Liivakasti võtmed algavad pk_test_, sk_test_ või rk_test_; live-võtmed algavad pk_live_, sk_live_ või rk_live_. Testtehingud ei liiguta raha.

Kasulikud testkaardid Stripe'i testimise dokumentatsioonist (mis tahes tuleviku aegumiskuupäev, mis tahes kolmekohaline CVC):

Testi vähemalt:

• Õnnestunud makse avab õige asja õigele kasutajale
• Tagasilükatud kaart näitab selget teadet ja ei ava midagi
• Brauseri sulgemine kohe pärast maksmist annab siiski ligipääsu (see tõestab, et webhook töötab, mitte ainult edulehe)
• Stripe'i lehel tühistamine suunab kasutaja tagasi äppi ilma ühegi tasuta
• Tellimuste puhul: tühista kliendiportaalis ja kontrolli, et ligipääs lõppeb õigel ajal

Live-minek

1. Aktiveeri oma Stripe'i konto ettevõtte ja pangaandmetega.
2. Vaheta live-võtmed äpi saladustesse. Stripe soovitab piiratud õigustega võtmeid, millel on ainult integratsiooniks vajalikud õigused, mitte piiranguteta salajast võtit.
3. Loo live-webhook'i lõpp-punkt, mis osutab sinu avaldatud äpile. Sellel on oma allkirjastamise saladus, mis erineb testist – uuenda see.
4. Loo tooted ja hinnad uuesti live-režiimis; testrežiimi ID-d seal ei eksisteeri.
5. Tee üks väike päris ost ja tagasta see.

Hoia iga võti oma projekti saladustes, mitte koodis ega vestluses. Meie turvanimekiri käsitleb võtmeid ja webhook'i kontrolli põhjalikumalt.

Maksud, tagastused ja paberimajandus

Maksed toovad kaasa kohustusi, mida kood ei lahenda. See ei ole maksunõu; küsi nõu raamatupidajalt.

• Käibemaks ja KM. Olenevalt sellest, kus sina ja su kliendid asute, võib tekkida registreerimis-, arvestus- ja aruandluskohustus. Stripe Tax võib arvutada ja koguda maksu kassas, jälgida, kus sinu müük võib tekitada kohustuse, ning aidata registreerimise ja aruandlusega – aga vastutus jääb sinule. Müügi pidaja pakkujad on alternatiiv, mis võtab rohkem sellest enda kanda.
• Tagastused ja vaidlused. Otsusta enne starti tagastuspoliitika ja pane see oma saidile. Vaidlused (tagasikanded) juhtuvad; hoia arvestust selle kohta, mida osteti ja toimetati.
• Kviitungid ja arved. Stripe saab saata kviitungeid e-kirjaga; ettevõtted võivad vajada korrektseid arveid.
• Tasud. Iga pakkuja võtab tehingu eest tasu. Vaata pakkuja praegust hinnalehte, mitte ära toetu artiklites toodud arvudele.

Millise seadistusega sinu äpp sobib

• Annetused või mõned tooted: Payment Links. Vaata kuidas ehitada mittetulundusliku annetuste veebilehte.
• Pood ostukorviga: Checkout ridade ja webhook'iga. Vaata kuidas ehitada veebipoodi.
• SaaS või liikmelisus: Checkout tellimusrežiimis, webhook'id ja kliendiportaal. Vaata kuidas ehitada SaaS MVP-d ja kuidas hinnastada SaaS-toodet.
• Turg, mis maksab müüjatele välja: teistsugune, rangemalt reguleeritud seadistus (Stripe Connect või sarnane). Planeeri see eraldi.

Maksete lisamine Mythexis

Mythexis ehitatud äppides maksed kasutavad sinu enda Stripe'i kontot ja võtmeid; sinu äpi jaoks ei ole ühe klikiga „Ühenda Stripe“ valikut. Tavaline voog:

1. Hangi Stripe'i testvõtmed.
2. Lisa STRIPE_SECRET_KEY (ja webhook'i saladus hiljem) projekti saladustesse – läbi lehe /secrets, projekti seadete või saladuste kaardi, mida agent näitab, kui vajab võtit.
3. Palu agendilt Checkouti, kasutades ülaltoodud sarnast prompti.
4. Testi eelvaates testkaartidega. Avalda enne webhook'i registreerimist, sest see vajab sinu avalikku URL-i.
5. Pärast live-võtmetele vahetamist avalda uuesti, et live-äpp need kätte saaks.

Vaata dokumentatsioonist Makse vastuvõtmine Stripe'iga ja Webhook'ide käsitlemine oma taustateenuses.

Küsimused