Как да добавите плащания в приложението си: checkout, абонаменти и webhooks

Най-простият начин да добавите плащания в приложението си е Stripe: използвайте Payment Link, ако ви трябва само бутон „Купи“ и можете да обработвате поръчките ръчно; Stripe Checkout, ако приложението ви трябва да знае кой е платил и да реагира автоматично; и Checkout в режим на абонамент, плюс клиентския портал на Stripe, за периодично таксуване. Във всеки случай, различен от най-простия, ви трябва и webhook — сървърна крайна точка, която Stripe извиква, когато плащането е успешно — и трябва да тествате всичко с тестовите ключове и тестовите карти на Stripe, преди да преминете към живи ключове.

Това ръководство обяснява всяка опция, частта с webhooks, която повечето уроци пропускат, и какво да проверите, преди да приемате реални пари. Данните за Stripe са от собствената документация на Stripe към септември 2026 г.

Защо изобщо да използвате доставчик на плащания

Никога не събирайте номера на карти във ваши собствени формуляри. Работата със сурови данни за карти ви поставя в обхвата на PCI DSS (стандарта за сигурност на картовата индустрия) и е сериозен риск. Доставчик на плащания като Stripe хоства формуляра за плащане, съхранява картата, обработва банковото удостоверяване и казва на приложението ви резултата. Вашето приложение вижда само „клиент X е платил за Y“.

Това ръководство използва Stripe, защото е широко използван, добре документиран и се поддържа от повечето AI строители на приложения. Съществуват и други доставчици; някои действат като „търговец на запис“ (merchant of record) и поемат обработката на данъка върху продажбите вместо вас. Ако данъчното съответствие ви притеснява, този модел си заслужава сравнение.

Трите начина за приемане на плащания със Stripe

Payment Links

Payment Link е платежна страница, хоствана от Stripe, която създавате в таблото на Stripe без код. Получавате URL, който можете да поставите зад бутон в приложението си, да споделите в имейл или да покажете като QR код. Според документацията на Stripe Payment Links могат да продават продукт, абонамент или да приемат дарение, а вие можете да позволите на клиентите сами да изберат сумата или да ограничите броя покупки.

Уловката: приложението ви автоматично не знае, че конкретен влязъл потребител е платил. За страница за дарения или малък магазин, където изпълнявате поръчките ръчно от имейл известията на Stripe, това е достатъчно. За „плати, за да отключиш Pro функциите“ — не е.

Stripe Checkout

Checkout е платежна страница, която вашият сървър създава при поискване за конкретна покупка. Сървърът ви казва на Stripe какво се купува (и по желание кой купува), Stripe връща URL, а вие изпращате клиента там. Според документацията на Stripe Checkout поддържа както еднократни, така и абонаментни плащания — като страница, хоствана от Stripe, страница, вградена във вашия сайт, или вграден формуляр.

Потокът:

1. Клиентът натиска Купи в приложението ви.
2. Сървърът ви създава Checkout Session с таен ключ, включвайки ID, което свързва сесията с потребителя или поръчката ви.
3. Клиентът се пренасочва към Stripe и плаща.
4. Stripe го пренасочва обратно към страницата ви за успех.
5. Stripe изпраща събитие checkout.session.completed към вашия webhook, а сървърът ви маркира поръчката като платена или отключва достъпа.

Стъпка 2 трябва да се случи на сървъра, защото използва таен ключ. Това е основната причина Checkout да изисква бекенд.

Абонаменти

Абонаментите използват Checkout в режим на абонамент с периодична цена, която настроите в Stripe. Първото плащане работи по описания по-горе поток. След това подновяванията, неуспешните карти, надграждането и отказите се случват във времето — често когато клиентът вече не е във вашето приложение — затова приложението ви научава за тях само чрез webhooks.

За клиентите, които искат сами да управляват абонамента си, Stripe предлага хостиран клиентски портал. Според документацията на Stripe клиентите могат там да обновяват методите за плащане и данните за фактуриране, да сменят или отказват абонаменти и да преглеждат и изтеглят фактури. Конфигурирате го в таблото на Stripe и добавяте бутон „Управление на фактурирането“, който изпраща клиента към него. Така не е нужно сами да създавате тези екрани.

Webhooks: частта, която не можете да пропуснете

Webhook е HTTP заявка, която Stripe изпраща до сървъра ви, когато нещо се случи. (Вижте какво е webhook за общата идея.) Ръководството на Stripe за изпълнение на поръчки е категорично: не можете да разчитате само на страницата за успех, защото клиент може да плати и да загуби връзка, преди тя да се зареди. За абонаменти и отложени методи на плащане webhooks са задължителни.

Събития, които си заслужава да обработвате

Правила за коректен webhook обработчик

Те идват директно от документацията на Stripe за webhooks, а генерираните от AI обработчици понякога пропускат някое от тях:

• Проверявайте подписа. Всяко събитие включва заглавка Stripe-Signature. Обработчикът ви я проверява със signing secret на крайната точка (започва с whsec_). Без това всеки може да изпрати фалшиво съобщение „плащането е успешно“ към сървъра ви.
• Използвайте суровото тяло на заявката. Проверките на подписа се провалят, ако фреймуъркът ви парсне или промени тялото първо.
• Връщайте 2xx бързо, след което извършвайте по-бавната работа. Изтичането на времето се брои като грешка.
• Обработвайте дублиращите се. Stripe може да достави едно и също събитие повече от веднъж. Записвайте обработените ID-та на събитията или направете изпълнението безопасно за двукратно изпълнение.
• Не разчитайте на реда. Stripe не гарантира, че събитията пристигат в реда, в който са се случили.
• Очаквайте повторни опити. В live режим Stripe повтаря неуспешните доставки до три дни, така че кратък срив не губи плащания — но обработчикът ви трябва да се справя със закъснели събития.

Webhooks изискват публичен HTTPS адрес, затова обикновено работят само след като приложението ви е публикувано. (CLI на Stripe може да препраща събитията към локална машина за разработчици.)

Подсказка, която покрива целия поток

Добави еднократна покупка със Stripe Checkout за „Pro пакета“ (ID на цената в STRIPE_PRICE_ID). Създай Checkout Session на сървъра, като използваш STRIPE_SECRET_KEY от тайните, и включи ID-то на влезлия потребител в сесията. Добави POST /api/stripe/webhook, който проверява подписа на Stripe с STRIPE_WEBHOOK_SECRET, като използва суровото тяло на заявката, обработва checkout.session.completed и маркира този потребител като притежаващ Pro пакета. Направи го безопасно, ако едно и също събитие пристигне два пъти. Страници за успех и отказ. Никога не излагай таен ключ към браузъра.

За абонаменти добави: „Използвай режим на абонамент с STRIPE_PRICE_ID. Обработвай invoice.paid, invoice.payment_failed, customer.subscription.updated и customer.subscription.deleted. Добави бутон Управление на фактурирането, който отваря клиентския портал на Stripe.“

Тестов режим

Stripe има отделни тестови (sandbox) и живи среди с отделни ключове. Тестовите ключове започват с pk_test_, sk_test_ или rk_test_; живите — с pk_live_, sk_live_ или rk_live_. Тестовите транзакции не движат пари.

Полезни тестови карти от документацията на Stripe за тестване (произволна бъдеща дата на изтичане, произволен трицифрен CVC):

Тествайте поне:

• Успешно плащане отключва правилното нещо за правилния потребител
• Отхвърлена карта показва ясно съобщение и не отключва нищо
• Затварянето на браузърния раздел веднага след плащане все пак дава достъп (това доказва, че webhook-ът работи, а не само страницата за успех)
• Отказът на страницата на Stripe връща потребителя в приложението без таксуване
• За абонаменти: откажете в клиентския портал и потвърдете, че достъпът спира, когато трябва

Пускане на живо

1. Активирайте акаунта си в Stripe с данните на бизнеса и банката.
2. Сменете с живи ключове в тайните на приложението. Stripe препоръчва ограничени ключове само с правата, нужни на интеграцията ви, вместо неограничен таен ключ.
3. Създайте крайна точка за webhook в live режим, която сочи към публикуваното ви приложение. Тя има собствен signing secret, различен от тестовия — актуализирайте го.
4. Пресъздайте продуктите и цените в live режим; ID-тата от тестовия режим там не съществуват.
5. Направете една реална малка покупка и я възстановете.

Пазете всеки ключ в тайните на проекта, никога в кода или в чата. Контролният списък за сигурност обхваща ключовете и проверката на webhooks по-подробно.

Данъци, възстановявания и документи

Плащанията носят задължения, които кодът не решава. Това не е данъчен съвет; консултирайте се с регистриран счетоводител.

• Данък върху продажбите, ДДС и GST. В зависимост от това къде сте вие и клиентите ви, може да се наложи да се регистрирате, да начислявате и да подавате данъци. Stripe Tax може да изчислява и събира данък при checkout, да следи къде продажбите ви могат да създадат задължение и да помага с регистрациите и подаването — но отговорността остава ваша. Търговците на запис са алтернатива, която поема повече от това.
• Възстановявания и спорове. Решете политиката си за възстановяване преди пускане и я публикувайте на сайта си. Спорове (chargebacks) се случват; пазете записи какво е било купено и доставено.
• Разписки и фактури. Stripe може да изпраща разписки по имейл; бизнесите може да се нуждаят от истински фактури.
• Такси. Всеки доставчик таксува на транзакция. Проверете текущата страница с цените на доставчика, вместо да разчитате на числа от статии.

Кой вариант подхожда на вашето приложение

• Дарения или няколко продукта: Payment Links. Вижте как да създадете уебсайт за дарения на нестопанска организация.
• Магазин с количка: Checkout с редове от поръчката и webhook. Вижте как да създадете онлайн магазин.
• SaaS или членства: Checkout в режим на абонамент, webhooks и клиентският портал. Вижте как да създадете SaaS MVP и как да определите цена на SaaS продукт.
• Пазар, който изплаща на продавачи: различна, по-регулирана настройка (Stripe Connect или подобно). Планирайте я отделно.

Добавяне на плащания в Mythex

Плащанията в приложенията, които създавате в Mythex, използват вашия собствен акаунт и ключове в Stripe; няма едно-кликово „Свържи Stripe“ за приложението ви. Обичайният поток:

1. Вземете тестовите ключове на Stripe.
2. Добавете STRIPE_SECRET_KEY (а по-късно и тайната за webhook) в тайните на проекта — през /secrets, настройките на проекта или картата с тайни, която агентът показва, когато му трябва ключ.
3. Поискайте от агента Checkout с подсказка, подобна на горната.
4. Тествайте в Preview с тестови карти. Публикувайте, преди да регистрирате webhook-а, тъй като той изисква публичния ви URL.
5. След смяна на живи ключове публикувайте отново, за да може живото приложение да ги вземе.

Вижте Приемане на плащания със Stripe и Обработка на webhooks в бекенда в документацията.

Въпроси