Како да додадете плаќања во вашата апликација: Checkout, претплати и webhook-ови

Наједноставниот начин да додадете плаќања во апликација е Stripe: користете Payment Link ако ви треба само копче „Купи“ и можете да ги обработувате нарачките рачно; Stripe Checkout ако апликацијата треба да знае кој платил и да реагира автоматски; и Checkout во режим на претплата плус порталот за клиенти на Stripe за повторувачко наплатување. Во секој случај освен во наједноставниот, ви треба и webhook — крајна точка на серверот што Stripe ја повикува кога ќе успее плаќањето — и сè треба да тестирате со тест клучевите и тест картичките на Stripe пред да преминете на живи клучеви.

Овој водич ги објаснува секоја опција, делот со webhook-ови што повеќето упатства го прескокнуваат и што да проверите пред да примате вистински пари. Деталите за Stripe се од сопствената документација на Stripe од септември 2026.

Зошто воопшто користите давател на плаќања

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

Овој водич го користи Stripe затоа што е широко користен, добро документиран и поддржан од повеќето AI градители на апликации. Постојат и други даватели, а некои делуваат како „merchant of record“ и ја преземаат обработката на данокот на промет наместо вас; ако даночната усогласеност ви е загриженост, таа опција вреди да се спореди.

Трите начини за примање плаќања со Stripe

Payment Links

Payment Link е страница за плаќање хостирана од Stripe што ја создавате во Stripe Dashboard без код. Добивате URL што можете да го ставите зад копче во вашата апликација, да го споделите во е-пошта или да го прикажете како QR код. Документацијата на Stripe вели дека Payment Links можат да продаваат производ, претплата или да прифаќаат донација, а можете да им дозволите на клиентите да изберат што да платат или да ограничите бројот на купувања.

Уловот: вашата апликација автоматски не знае дека одреден најавен корисник платил. За страница за донации или мала продавница каде нарачките ги исполнувате рачно од е-поштите на Stripe, тоа е во ред. За „платете за да ги отклучите Pro функциите“, не е.

Stripe Checkout

Checkout е страница за плаќање што вашиот сервер ја создава по барање за конкретна купувачка. Серверот му кажува на Stripe што се купува (и по избор кој клиент купува), Stripe враќа URL, а вие го праќате клиентот таму. Документацијата на Stripe опишува дека поддржува и еднократни и претплатнички плаќања, како целосно страница хостирана од Stripe, страница вградена во вашата веб-страница или вграден образец.

Тек:

1. Клиентот кликнува Купи во вашата апликација.
2. Вашиот сервер создава Checkout Session со вашиот тајен клуч, вклучувајќи ID што ја поврзува со вашиот корисник или нарачка.
3. Клиентот се пренасочува на Stripe и плаќа.
4. Stripe го враќа назад на вашата страница за успех.
5. Stripe испраќа настан checkout.session.completed до вашиот webhook, а вашиот сервер ја означува нарачката како платена или отклучува пристап.

Чекор 2 мора да се случи на серверот, бидејќи користи ваш тајен клуч. Тоа е главната причина Checkout да бара backend.

Претплати

Претплатите користат Checkout во режим на претплата со повторувачка цена што ја поставувате во Stripe. Првото плаќање работи како тек погоре. Потоа, обновувањата, неуспешните картички, надградбите и откажувањата се случуваат со тек на времето — често кога клиентот воопшто не е во вашата апликација — па вашата апликација дознава за нив само преку webhook-ови.

За клиентите да ја управуваат сопствената претплата, Stripe нуди хостиран портал за клиенти. Според документацијата на Stripe, клиентите таму можат да ги ажурираат начините на плаќање и податоците за наплата, да ги менуваат или откажуваат претплатите, и да ги гледаат и преземаат фактурите. Го конфигурирате во Stripe Dashboard и додавате копче „Управувај со наплатата“ што ги праќа клиентите таму. Така не мора сами да ги градите тие екрани.

Webhook-овите: делот што не може да се прескокне

Webhook е HTTP барање што Stripe го испраќа до вашиот сервер кога ќе се случи нешто. (Видете што е webhook за општата идеја.) Водичот за исполнување на Stripe е експлицитен: не можете да се потпирате само на страницата за успех за исполнување на нарачки, бидејќи клиентот може да плати и потоа да ја изгуби врската пред таа страница да се вчита. За претплати и одложени начини на плаќање, webhook-овите се задолжителни.

Настани што вреди да се обработат

Правила за исправен webhook обработувач

Овие доаѓаат директно од документацијата на Stripe за webhook-ови, а AI-генерираните обработувачи понекогаш некое од нив го пропуштаат:

• Проверете го потписот. Секој настан има заглавие Stripe-Signature. Обработувачот го проверува со тајниот клуч за потпишување на крајната точка (започнува со whsec_). Без тоа, секој би можел да испрати лажна порака „плаќањето успеа“ до вашиот сервер.
• Користете сурово тело на барањето. Проверките на потписот не успеваат ако рамката прво го парсира или измени телото.
• Вратете 2xx одговор брзо, па потоа направете побавна работа. Истекувањата на времето се сметаат за неуспеси.
• Ракувајте со дупликати. Stripe може да го достави истиот настан повеќе пати. Евидентирајте ги ID-овите на обработените настани или направете исполнувањето безбедно да се изврши двапати.
• Не претпоставувајте редослед. Stripe не гарантира дека настаните ќе пристигнат по редоследот по којшто се случиле.
• Очекувајте повторувања. Во live режим Stripe повторно ги обидува неуспешните испораки до три дена, па краток прекин не губи плаќања — но обработувачот мора да се справи со доцнечки настани.

Webhook-овите имаат потреба од јавна 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 (тест) и live средини со одделни клучеви. Sandbox клучевите почнуваат со pk_test_, sk_test_ или rk_test_; live клучевите со pk_live_, sk_live_ или rk_live_. Тест трансакциите не движат пари.

Корисни тест картички од документацијата за тестирање на Stripe (кој било идно датум на истекување, кој било трицифрен CVC):

Тестирајте најмалку:

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

Пуштање во живот

1. Активирајте ја вашата сметка на Stripe со деловни и банкарски податоци.
2. Вметнете живи клучеви во тајните на вашата апликација. Stripe препорачува ограничени клучеви само со дозволите што ги бара вашата интеграција, наместо неограничен тајен клуч.
3. Создајте жива webhook крајна точка што покажува кон објавената апликација. Има свој тајен клуч за потпишување, различен од тестовиот — ажурирајте го.
4. Повторно создајте производи и цени во live режим; ID-овите од тест режимот таму не постојат.
5. Направете една вистинска мала купувачка и вратете ја парата.

Чувајте го секој клуч во тајните на вашиот проект, никогаш во кодот или во чатот. Нашата контролна листа за безбедност ги опфаќа клучевите и проверката на webhook-ови подетално.

Даноци, враќања и документација

Плаќањата носат обврски што кодот не ги решава. Ова не е даночен совет; проверете со сметководител.

• Данок на промет, ДДВ и ГСТ. Зависно од тоа каде сте вие и вашите клиенти, можеби треба да се регистрирате, да наплатите и да поднесете данок. Stripe Tax може да пресмета и да наплати данок при Checkout, да следи каде вашите продажби може да создадат обврска и да помогне со регистрации и поднесување — но одговорноста останува кај вас. Даватели од типот merchant-of-record се алтернатива што презема повеќе од тоа.
• Враќања и спорови. Одлучете ја политиката за враќање пред пуштање и објавете ја на вашата страница. Спорови (chargebacks) се случуваат; чувајте евиденција за тоа што е купено и испорачано.
• Потврди и фактури. Stripe може да испраќа потврди по е-пошта; бизнисите можеби им требаат правилни фактури.
• Провизии. Секој давател наплатува по трансакција. Проверете ја тековната страница со цени на давателот, а не верувајте на бројки од статии.

Која поставка одговара на вашата апликација

• Донации или неколку производи: Payment Links. Видете како да направите веб-страница за непрофитни донации.
• Продавница со кошничка: Checkout со ставки и webhook. Видете како да направите онлајн продавница.
• SaaS или членарини: Checkout во режим на претплата, webhook-ови и порталот за клиенти. Видете како да направите 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 и Ракување со webhook-ови во вашиот backend во документацијата.

Прашања