Как да добавите абонаменти със Stripe: планове, пробни периоди, webhooks и неуспешни плащания
За да добавите абонаменти със Stripe, създайте продукт с периодична цена в таблото на Stripe, изпращайте клиентите от сървъра си към Stripe Checkout в режим на абонамент, а webhook нека казва на приложението ви кога всяко плащане е успешно, неуспешно, променено или прекратено. Записвайте статуса на абонамента към потребителя и давайте достъп според него, а не според страницата за успех. Добавете бутон Управление на фактурирането, който отваря хостнатия клиентски портал на Stripe, за да могат хората да сменят картите, да сменят плана и да се откажат, без да строите тези екрани сами.
Това ръководство се основава на как да добавите плащания в приложението си, което обхваща еднократния Checkout, тестовия режим и пускането на живо. Тук се фокусираме върху това, какво е различно при периодичното таксуване. Данните за Stripe са от документацията на Stripe към септември 2026 г.
Защо абонаментите са по-трудни от еднократните плащания
Еднократното плащане се случва, докато клиентът е в приложението ви. Абонаментът продължава да се случва, след като той си е тръгнал: подновявания всеки месец, карти, които изтичат, надграждания по средата на периода, отказвания, които влизат в сила в края на периода. Приложението ви научава за тях само чрез webhooks. Повечето грешки с абонаментите идват от това, че се третира първото плащане като цялата история.
Вашите опции
| Подход | Какво строите | Най-подходящ за |
|---|---|---|
| Payment Link с периодична цена | Нищо освен линк | Проверка на търсенето; ръчно управление на достъпа |
| Checkout (режим на абонамент) + клиентски портал | Сървърен маршрут, webhook, бутон за фактуриране | Повечето SaaS приложения и членства |
| Subscriptions API със собствен формуляр за плащане | Много повече: UI за плащане, удостоверяване, повторни опити | Приложения с необичайни схеми на таксуване |
| Доставчик тип търговец на запис | Подобно на Checkout | Продавачи, които искат доставчикът да се грижи за данъка върху продажбите |
За повечето приложения Checkout плюс порталът е правилният компромис. Сравнете доставчиците в Stripe срещу Paddle срещу Lemon Squeezy, ако обработката на данъци ви притеснява.
Първо планирайте цените си в Stripe
В Stripe продуктът е това, което продавате („Pro план“), а цената е как го таксувате („20 долара на месец“, „200 долара на година“). Един продукт може да има няколко цени. Решете:
- Кои нива предлагате и какво отключва всяко от тях във вашето приложение
- Месечно, годишно или и двете
- Дали предлагате пробен период и дали той изисква карта предварително
Създайте продуктите и цените в тестов режим и запазете ID-тата на цените; приложението ви ги използва. Ако още не сте определили цените си, прочетете как да определите цена на SaaS продукт и фриемиум срещу безплатен пробен период.
Жизненият цикъл на абонамента, който трябва да обработите
Преглед на абонаментите на Stripe изброява статусите, които един абонамент може да има. Тези, които най-много важат за достъпа:
| Статус | Какво означава | Дава ли достъп? |
|---|---|---|
trialing | В пробен период | Да |
active | В добро състояние | Да |
incomplete | Първото плащане още не е завършено; Stripe дава на клиента 23 часа | Не |
incomplete_expired | Първото плащане никога не е успяло | Не |
past_due | Последното плащане е неуспешно или не е опитано; може да има повторни опити | Ваш избор; много приложения дават кратък гратисен период |
unpaid | Повторните опити са свършили, фактурите остават отворени, без нови опити | Не; документацията на Stripe препоръчва да се отнеме достъпът |
canceled | Приключил; не може да бъде рестартиран | Не |
paused | Пробен период е приключил без метод на плащане и е настроен да се постави на пауза | Не |
Запазвайте статуса в записа на потребителя или акаунта и базирайте достъпа на него. Актуализирайте го всеки път, когато пристигне съответният webhook.
Webhook събитията, които трябва да обработвате
| Събитие | Какво прави приложението ви |
|---|---|
checkout.session.completed | Свързва новите ID-та на клиента и абонамента в Stripe с потребителя ви |
invoice.paid | Маркира абонамента като активен и записва края на новия период |
invoice.payment_failed | Казва на потребителя, че картата му е неуспешна, и дава връзка към портала |
invoice.payment_action_required | Моли потребителя да завърши удостоверяването на картата |
customer.subscription.updated | Актуализира плана, статуса и всяко насрочено отказване |
customer.subscription.deleted | Премахва платения достъп |
customer.subscription.trial_will_end | Напомня на потребителя преди края на пробния период; Stripe го изпраща три дни по-рано |
Правилата за обработчици от документацията на Stripe за webhooks важат: проверявайте подписа със суровото тяло, връщайте 2xx бързо, обработвайте дублиращи се и извънредно подредени събития и очаквайте повторни опити. Ръководството какво е webhook обяснява идеята, а ръководството за плащания изброява правилата подробно.
Стъпка по стъпка
- Създайте продукти и цени в тестовия режим на Stripe.
- Добавете тайни: таен ключ, ID-тата на цените и по-късно signing secret на webhook-а. Никога не ги слагайте във фронтенд кода.
- Страница с цени: бутонът на всеки план извиква сървъра ви, който създава Checkout Session в режим на абонамент за влезлия потребител. Подайте ID-то на потребителя, за да може webhook-ът да свърже плащането с акаунта.
- Крайна точка за webhook: проверява подписите и обработва събитията по-горе, като обновява един запис за абонамента на потребител.
- Ограничавайте функциите според записания статус и план, проверени на сървъра за всяко защитено действие, а не само скрити бутони.
- Клиентски портал: конфигурирайте го в таблото на Stripe (към кои планове могат да сменят и дали могат да се откажат), после добавете бутон Управление на фактурирането, който създава портална сесия на сървъра и пренасочва към нея.
- Неуспешни плащания: в настройките за фактуриране на Stripe изберете поведението при повторни опити и какво става след последния опит. Показвайте банер в приложението, докато е
past_due. - Тествайте целия жизнен цикъл, после публикувайте и регистрирайте webhook-а в live режим.
Подсказки за вашия AI строител
Добави абонаментно таксуване със Stripe. Планове: Starter (ID на цената в STRIPE_PRICE_STARTER) и Pro (STRIPE_PRICE_PRO). Страницата с цени създава Checkout Session в режим на абонамент на сървъра, като използва STRIPE_SECRET_KEY, и прикачва ID-то на влезлия потребител. Запази ID-то на клиента в Stripe, ID-то на абонамента, плана и статуса към потребителя. Никога не излагай таен ключ към браузъра.
Добави POST /api/stripe/webhook. Провери подписа с STRIPE_WEBHOOK_SECRET, като използваш суровото тяло на заявката. Обработвай checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted и customer.subscription.trial_will_end. Записвай ID-тата на обработените събития, за да се игнорират дубликатите. Обновявай статуса на потребителя от обекта на абонамента, а не от реда, в който пристигат събитията.
Ограничи Pro функциите на сървъра: разрешавай ги само когато статусът е active или trialing и планът е Pro. Показвай банер „Плащането е неуспешно, актуализирайте картата си“, когато статусът е past_due. Добави бутон Управление на фактурирането, който отваря клиентския портал на Stripe за този потребител.
Надграждания, понижения и пропорционално таксуване
Когато клиент сменя плановете, документацията на Stripe казва, че промяната често създава пропорционално таксуване (proration): новата цена се прилага за останалата част от текущия период на таксуване. Можете да прегледате пропорциите или да ги изключите. Ако плановете са с един и същ интервал, датите на таксуване остават същите; при преминаване от месечен към годишен датата на таксуване се мести на деня на смяната. Позволяването на клиентите сами да сменят плановете в портала ви спестява писането на тази логика, но решете в настройките на портала кои смени са разрешени.
Списък за тестване
Използвайте тестовия режим на Stripe и тестовите карти и минете през всяко състояние:
- Новият абонамент дава правилния план на правилния потребител
- Затварянето на раздела веднага след плащане все пак дава достъп (доказва, че webhook-ът работи)
- Отхвърлена карта при регистрация не дава нищо
- Неуспешно подновяване поставя акаунта в past_due и показва банера
- Смяната на картата в портала възстановява статус active
- Надграждането и понижаването сменят функциите правилно
- Отказването в края на периода запазва достъпа до крайната дата, след което го премахва
- Потребителите в пробен период получават достъп, получават напомнянето и преминават или губят достъп правилно
- Изпращането на едно и също webhook събитие два пъти не променя нищо
Тестовите часовници на Stripe ви позволяват да симулирате минаване на времето, така че да тествате подновявания, без да чакате месец. Проверете текущата документация на Stripe за тестване, за да видите как се използват.
Чести грешки
- Даване на достъп на страницата за успех. Клиентите може да платят и никога да не стигнат до нея. Използвайте webhook.
- Обработка само на първото плащане. Подновяванията, неуспехите и отказванията идват по-късно, като събития.
- Проверка на статуса на плана само във фронтенда. Всеки може да извика API-то ви директно.
- Един потребител, много абонаменти по случайност. Проверявайте за съществуващ абонамент, преди да създадете нова Checkout Session, или изпращайте съществуващите клиенти към портала.
- Отнемане на достъпа при първото неуспешно подновяване. Картите се провалят по скучни причини. Кратък гратисен период с ясен банер задържа клиентите.
- Забравен live webhook. Тестовата и живата крайна точка имат различни signing secrets.
- Игнориране на данъците и възстановяванията. Решете политиката си за възстановяване и проверете данъчните си задължения със счетоводител преди пускане.
Абонаменти в Mythex
Приложенията, които строите в Mythex, използват вашия собствен акаунт и ключове в Stripe; няма едно-кликово свързване със Stripe за вашето приложение. Добавете тестовите си ключове и ID-та на цените като тайни на проекта, използвайте подсказки като горните и тествайте с тестовите карти на Stripe в Preview. Webhooks изискват публичния URL адрес на приложението ви, затова публикувайте, преди да регистрирате крайната точка в Stripe, и публикувайте отново, след като превключите на живи ключове, за да може живото приложение да ги вземе. Вижте Приемане на плащания със Stripe и Обработка на webhooks в бекенда. За по-широката картина как да създадете SaaS MVP обхваща какво да строите около таксуването.
Въпроси
Кой е най-простият начин да добавя абонаменти със Stripe?
Създайте продукт с периодична цена в таблото на Stripe, изпращайте клиентите към Stripe Checkout в режим на абонамент, обработвайте събитията за абонаменти с webhook и свържете бутон „Управление на фактурирането“ с хостнатия клиентски портал на Stripe. Така не строите сами формуляри за карти и екрани за смяна на план.
Кои webhook събития на Stripe са ми нужни за абонаменти?
Най-малко checkout.session.completed, за да свържете новия абонамент с потребителя си, invoice.paid, за да потвърдите всяко успешно плащане, invoice.payment_failed, за да предупредите за неуспешни подновявания, и customer.subscription.updated и customer.subscription.deleted, за да следите смените на план и отказванията.
Какво се случва, когато плащане по абонамент се провали?
Според документацията на Stripe към септември 2026 г. абонаментът обикновено става past_due и Stripe може да опита плащането отново според настройките ви. След последния опит настройките в таблото решават дали той се отменя, маркира като unpaid или остава past_due.
Мога ли да предложа безплатен пробен период без да искам карта?
Да. Stripe поддържа безплатни пробни периоди, а документацията му описва статус paused за пробни периоди, които завършват без метод на плащане, когато е настроено така. Искането на карта предварително обикновено означава по-малко регистрации, но повече платени клиенти; тествайте какво подхожда на продукта ви.