Kuidas lisada Stripe'iga tellimusi: paketid, prooviperioodid, webhook'id ja ebaõnnestunud maksed
Tellimuste lisamiseks Stripe'iga loo korduva hinnaga toode Stripe'i juhtpaneelis, saada kliendid oma serverist Stripe Checkouti tellimusrežiimi ning lase webhook'il öelda sinu äpile, millal iga makse õnnestub, ebaõnnestub, muutub või lõpeb. Salvesta tellimuse olek kasutaja juurde ja anna ligipääs selle põhjal, mitte edulehe järgi. Lisa nupp Halda arveldust, mis avab Stripe'i hostitud kliendiportaali, kus inimesed saavad vahetada kaarti, muuta paketti ja tühistada, ilma et sa neid ekraane ise ehitaksid.
See juhend tugineb juhendile kuidas lisada äppi makseid, mis käsitleb ühekordset Checkouti, testrežiimi ja live-minekut. Siin keskendume sellele, mis on korduva arveldusega teisiti. Stripe'i üksikasjad on pärit Stripe'i dokumentatsioonist seisuga september 2026.
Miks tellimused on keerukamad kui ühekordsed maksed
Ühekordne makse toimub siis, kui klient on sinu äpis. Tellimus jätkub ka pärast seda, kui klient lahkub: iga kuu uuendused, aeguvad kaardid, paketi muutmine perioodi keskel, tühistamised, mis jõustuvad perioodi lõpus. Sinu äpp kuuleb nendest ainult webhook'ide kaudu. Enamik tellimuste vigu tuleb sellest, et esimest makset peetakse kogu loo ühe osaks.
Sinu valikud
| Lähenemine | Mida sa ehitad | Sobib kõige paremini |
|---|---|---|
| Makselink korduva hinnaga | Ainult link | Nõudluse testimine; ligipääsu haldamine käsitsi |
| Checkout (tellimusrežiim) + kliendiportaal | Serveri marsruut, webhook, arveldusnupp | Enamik SaaS-äppe ja liikmelisusi |
| Tellimuste API oma makse vormiga | Palju rohkem: makseliides, autentimine, uuesti proovimised | Äpid, millel on ebatavalised arveldusvoogud |
| Müügi pidaja pakkuja | Sarnane Checkoutiga | Müüjad, kes soovivad, et pakkuja tegeleks käibemaksuga |
Enamiku äppide jaoks on Checkout pluss portaal õige kompromiss. Kui maksunduse käsitlus muret teeb, vaata võrdlust Stripe vs Paddle vs Lemon Squeezy.
Planeeri hinnastus enne Stripe'is
Stripe'is on toode see, mida müüd („Pro-pakett“), ja hind see, kuidas selle eest küsid („20 $ kuus“, „200 $ aastas“). Ühel tootel võib olla mitu hinda. Otsusta:
- Milliseid pakette pakud ja mida iga pakett sinu äpis avab
- Kas kuu-, aasta- või mõlemad hinnad
- Kas pakud prooviperioodi ja kas see nõuab kaarti ette
Loo tooted ja hinnad testrežiimis ja hoia nende hinna-ID-d alles; sinu äpp viitab neile. Kui hinnastus pole veel paigas, loe kuidas hinnastada SaaS-toodet ja freemium vs tasuta prooviperiood.
Tellimuse elutsükkel, mida pead käsitlema
Stripe'i tellimuste ülevaates on loetletud olekud, mida tellimus võib omada. Need, mis ligipääsu jaoks kõige rohkem loevad:
| Olek | Mida see tähendab | Kas anda ligipääs? |
|---|---|---|
trialing | Prooviperioodil | Jah |
active | Korras | Jah |
incomplete | Esimene makse on tegemata; Stripe annab kliendile 23 tundi | Ei |
incomplete_expired | Esimene makse ei õnnestunud kunagi | Ei |
past_due | Viimane makse ebaõnnestus või ei proovitud; võivad järgneda korduskatsed | Sinu valik; paljud äpid lubavad lühikese karenssi |
unpaid | Korduskatsed on lõppenud, arved jäävad avatuks, rohkem katseid ei tehta | Ei; Stripe'i dokumentatsioon soovitab ligipääsu tühistada |
canceled | Lõppenud; ei saa uuesti alustada | Ei |
paused | Prooviperiood lõppes ilma makseviisita ja seati pausile | Ei |
Salvesta olek oma kasutaja või konto kirjele ja põhine ligipääs sellel. Uuenda seda iga kord, kui asjakohane webhook saabub.
Webhook'i sündmused, mida käsitleda
| Sündmus | Mida su äpp teeb |
|---|---|
checkout.session.completed | Seosta uus Stripe'i kliendi ja tellimuse ID-d oma kasutajaga |
invoice.paid | Märgi tellimus aktiivseks ja salvesta uus perioodi lõpp |
invoice.payment_failed | Teavita kasutajat, et tema kaart ebaõnnestus, ja lisa link portaali |
invoice.payment_action_required | Palu kasutajal lõpetada kaardi autentimine |
customer.subscription.updated | Uuenda pakett, olek ja kõik planeeritud tühistamised |
customer.subscription.deleted | Eemalda tasuline ligipääs |
customer.subscription.trial_will_end | Tuleta kasutajale meelde enne prooviperioodi lõppu; Stripe saadab selle kolm päeva ette |
Webhook'i käitleja reeglid Stripe'i webhook'ide dokumentatsioonist kehtivad endiselt: kontrolli allkirja toorkeha põhjal, tagasta 2xx kiiresti, käsitle dubleerunud ja järjekorrast väljas sündmusi ning arvesta kordusprobleemidega. Juhend mis on webhook selgitab ideed ja makse juhend loetleb reeglid üksikasjalikult.
Samm-sammult
- Loo tooted ja hinnad Stripe'i testrežiimis.
- Lisa saladused: salajane võti, hinna-ID-d ja hiljem webhook'i allkirjastamise saladus. Ära kunagi pane neid esilõpu koodi.
- Hinnalehekülg: iga paketi nupp kutsub sinu serverit, mis loob sisse logitud kasutaja jaoks Checkouti sessiooni tellimusrežiimis. Lisa oma kasutaja ID, et webhook saaks makse konto külge siduda.
- Webhook'i lõpp-punkt: kontrolli allkirju ja käsitle ülaltoodud sündmusi, uuendades ühte tellimuse kirjet kasutaja kohta.
- Ava funktsioonid salvestatud oleku ja paketi alusel, mida kontrollitakse serveris iga kaitstud tegevuse puhul, mitte ainult peidetud nuppude järgi.
- Kliendiportaal: seadista see Stripe'i juhtpaneelis (milliseid pakette inimesed saavad vahetada, kas nad saavad tühistada), seejärel lisa nupp Halda arveldust, mis loob serveris portaali sessiooni ja suunab sinna.
- Ebaõnnestunud maksed: vali Stripe'i arveldusseadetes kordusproovide käitumine ja see, mis juhtub pärast viimast kordust. Näita äpis bännerit, kui olek on
past_due. - Testi kogu elutsüklit, siis avalda ja registreeri live-webhook.
Juhised AI-äpiloojale
Lisa tellimusarveldus Stripe'iga. Paketid: Starter (hinna ID STRIPE_PRICE_STARTER-is) ja Pro (STRIPE_PRICE_PRO). Hinnalehekülg loob serveris Checkouti sessiooni tellimusrežiimis, kasutades STRIPE_SECRET_KEY-d ja lisades sisse logitud kasutaja ID. Salvesta kasutaja kirjele Stripe'i kliendi ID, tellimuse ID, pakett ja olek. Ära kunagi too salajast võtit brauserisse.
Lisa POST /api/stripe/webhook. Kontrolli allkirja STRIPE_WEBHOOK_SECRET-iga toorkeha põhjal. Käsitle checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted ja customer.subscription.trial_will_end. Salvesta töödeldud sündmuste ID-d, et dubleerunud sündmused ignoreeritaks. Uuenda kasutaja olekut tellimuse objektist, mitte sündmuste saabumise järjekorrast.
Ava Pro-funktsioonid serveris: luba neid ainult siis, kui olek on active või trialing ja pakett on Pro. Kui olek on past_due, näita bännerit „makse ebaõnnestus, uuenda oma kaarti“. Lisa nupp Halda arveldust, mis avab selle kasutaja jaoks Stripe'i kliendiportaali.
Paketi muutmine, alandamine ja proratsioon
Kui klient vahetab paketti, loob Stripe'i dokumentatsiooni järgi muutus sageli proratsiooni: uus hind rakendatakse praeguse arveldusperioodi ülejäänud osale. Võid prorateerimist eelvaadata või välja lülitada. Kui paketid on sama intervalliga, jäävad arvelduskuupäevad samaks; kuust aastasse üleminek viib arvelduskuupäeva ümber vahetuse päevale. Kui lased klientidel paketti portaalis muuta, säästad sellele loogikale kirjutamise vaeva, aga otsusta portaali seadetes, milliseid vahetusi lubad.
Testimise nimekiri
Kasuta Stripe'i testrežiimi ja testkaarte ning käi läbi iga olek:
- Uus tellimus annab õige paketi õigele kasutajale
- Brauseri sulgemine kohe pärast maksmist annab siiski ligipääsu (see tõestab, et webhook töötab)
- Tagasilükatud kaart registreerimisel ei anna midagi
- Ebaõnnestunud uuendus viib konto olekusse past_due ja näitab bännerit
- Kaardi uuendamine portaalis taastab oleku active
- Paketi tõstmine ja alandamine muudavad funktsioone õigesti
- Perioodi lõpus tühistamine hoiab ligipääsu kuni lõpukuupäevani ja eemaldab selle seejärel
- Prooviperioodi kasutajad saavad ligipääsu, saavad meeldetuletuse ning konverteeruvad või kaotavad ligipääsu õigesti
- Sama webhook'i sündmuse kahekordne saatmine ei muuda midagi
Stripe'i testikellad võimaldavad simuleerida aja möödumist, nii et saad testida uuendusi ilma kuud ootamata. Vaata Stripe'i praegust testimise dokumentatsiooni, kuidas neid kasutada.
Levinud vead
- Ligipääsu andmine edulehe põhjal. Kliendid võivad maksta ja lehele kunagi jõudmata. Kasuta webhook'i.
- Ainult esimese makse käsitlemine. Uuendused, ebaõnnestumised ja tühistamised tulevad hiljem, sündmustena.
- Paketi oleku kontrollimine ainult esilõpus. Igaüks saab sinu API-d otse kutsuda.
- Üks kasutaja, mitu tellimust kogemata. Kontrolli enne uue Checkouti sessiooni loomist, kas olemasolev tellimus on olemas, või suuna olemasolevad kliendid portaali.
- Ligipääsu tühistamine esimese ebaõnnestunud uuenduse korral. Kaardid ebaõnnestuvad igavatel põhjustel. Lühike karens ja selge bänner hoiavad kliente.
- Live-webhook'i unustamine. Testi ja live-lõpp-punktidel on erinevad allkirjastamise saladused.
- Maksu ja tagastuste ignoreerimine. Otsusta tagastuspoliitika ja kontrolli oma maksukohustusi raamatupidajaga enne starti.
Tellimused Mythexis
Mythexi abil ehitatud äppides kasutavad tellimused sinu enda Stripe'i kontot ja võtmeid; sinu äpi jaoks ei ole ühe klikiga Stripe'i ühendust. Lisa oma testvõtmed ja hinna-ID-d projekti saladustena, kasuta ülaltoodud sarnaseid prompte ja testi Stripe'i testkaartidega eelvaates. Webhook'id vajavad sinu äpi avalikku URL-i, seega avalda enne lõpp-punkti registreerimist Stripe'is ja avalda uuesti pärast live-võtmetele üleminekut, et live-äpp need kätte saaks. Vaata makse vastuvõtmine Stripe'iga ja webhook'ide käsitlemine oma taustateenuses. Laiema toote jaoks katab kuidas ehitada SaaS MVP-d arvelduse ümber ehitatava.
Küsimused
Mis on lihtsaim viis tellimuste lisamiseks Stripe'iga?
Loo Stripe'i juhtpaneelis toode korduva hinnaga, saada kliendid Stripe Checkouti tellimusrežiimi, käsitle tellimuse sündmusi webhook'iga ja lingi nupp Halda arveldust Stripe'i hostitud kliendiportaali. Nii ei pea ise ehitama kaardivorme ega paketi muutmise ekraane.
Milliseid Stripe'i webhook'i sündmusi tellimuste jaoks vajan?
Vähemalt checkout.session.completed, et seostada uus tellimus oma kasutajaga, invoice.paid, et kinnitada iga õnnestunud makse, invoice.payment_failed, et hoiatada ebaõnnestunud uuendamiste eest, ning customer.subscription.updated ja customer.subscription.deleted, et jälgida paketi muudatusi ja tühistamisi.
Mis juhtub, kui tellimuse makse ebaõnnestub?
Stripe'i dokumentatsiooni järgi (seisuga september 2026) läheb tellimus tavaliselt olekusse past_due ja Stripe võib makset sinu seadete alusel uuesti proovida. Pärast viimast korduskatset otsustavad sinu juhtpaneeli seaded, kas see tühistatakse, märgitakse tasumata (unpaid) või jäetakse past_due olekusse.
Kas ma saan pakkuda tasuta prooviperioodi ilma kaarti küsimata?
Jah. Stripe toetab tasuta prooviperioode, ja selle dokumentatsioon kirjeldab olekut paused prooviperioodidele, mis lõppevad ilma makseviisita, kui see nii seadistatud on. Kaardi ette küsimine tähendab tavaliselt vähem registreerumisi, aga rohkem maksvaid kliente; testi, mis sobib sinu tootele.