Қолданбаға төлем қосу: Checkout, жазылымдар және webhook-тер

Қолданбаңызға төлем қосудың ең қарапайым жолы — Stripe: тек «Сатып алу» түймесі керек болса және тапсырыстарды қолмен өңдей алсаңыз, Payment Link; қолданбаңыз кім төлегенін білуі және автоматты түрде әрекет етуі керек болса, Stripe Checkout; ал жазылым түріндегі қайталама төлем үшін Checkout-тың жазылым режимі мен Stripe-тың клиент порталы. Кез келген күрделірек жағдайда webhook да керек — төлем сәтті өткенде Stripe шақыратын серверлік endpoint. Барлығын нақты кілттерге ауыспас бұрын Stripe-тың тест кілттері мен тест карталарымен сынаңыз.

Бұл нұсқаулық әр нұсқаны, көп оқулықтар өткізіп жіберетін webhook бөлігін және нақты ақша қабылдамас бұрын не тексеру керектігін түсіндіреді. Stripe мәліметтері 2026 жылдың қыркүйегі бойынша Stripe-тың өз құжаттамасынан алынған.

Неге төлем провайдері керек

Карта нөмірлерін ешқашан өз формаңызда жинамаңыз. Картаның шикі деректерімен жұмыс істеу сізді PCI DSS (карта индустриясының қауіпсіздік стандарты) аясына әкеледі және бұл үлкен жауапкершілік. Stripe сияқты төлем провайдері төлем формасын хостингтейді, картаны сақтайды, банк аутентификациясын өңдейді және нәтижені қолданбаңызға хабарлайды. Қолданбаңыз тек «клиент X төлеп, Y үшін» деген ақпаратты көреді.

Бұл нұсқаулық Stripe-ты пайдаланады, себебі ол кеңінен таралған, жақсы құжатталған және көптеген ЖИ қолданба құрастырушыларында қолдау бар. Басқа провайдерлер де бар, кейбіреулері «merchant of record» ретінде сатылым салығын өздері өңдейді; егер салық талабы сізді алаңдатса, бұл үлгіні салыстыру тиімді.

Stripe арқылы төлем қабылдаудың үш жолы

Payment Links

Payment Link — Stripe Dashboard-та кодсыз жасалатын 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-қа backend керек болуының негізгі себебі де осы.

Жазылымдар

Жазылымдар Checkout-тың жазылым режимін пайдаланады, Stripe-та орнатылған қайталанатын бағамен. Алғашқы төлем жоғарыдағы ағым сияқты жұмыс істейді. Одан кейін жаңартулар, сәтсіз карталар, мерзім ішіндегі жоғарылатулар және бас тартулар уақыт өте келе болады — көбінесе клиент қолданбаңызда болмай-ақ — сондықтан қолданбаңыз мұны тек webhook арқылы біледі.

Клиенттің өз жазылымын басқаруы үшін Stripe хостингтейтін клиент порталын ұсынады. Stripe құжаттамасына сәйкес клиенттер сонда төлем әдістерін және біллинг деректерін жаңарта алады, жазылымдарын өзгерте немесе бас тарта алады, ал шот-фактураларын көріп, жүктей алады. Оны Stripe Dashboard-та баптайсыз және клиентті оған жіберетін «Біллингті басқару» түймесін қоясыз. Бұл сізге сол экрандарды өзіңіз жасамауға мүмкіндік береді.

Webhook-тер: өткізіп жіберуге болмайтын бөлік

Webhook — бірдеңе болғанда Stripe сіздің серверіңізге жіберетін HTTP сұрауы. (Жалпы идея үшін webhook дегеніміз не бөлімін қараңыз.) Stripe-тың тапсырысты орындау нұсқаулығы айқын: тапсырысты тек сәтті төлем бетіне сүйеніп орындауға болмайды, себебі клиент төлеп, бет жүктелмей тұрып байланысын жоғалтуы мүмкін. Жазылымдар мен кейінге қалған төлем әдістері үшін webhook міндетті.

Өңдеуге тұрарлық оқиғалар

Дұрыс webhook өңдеушісінің ережелері

Бұл Stripe-тың webhook құжаттамасынан тікелей алынған, ал ЖИ жасаған өңдеушілер кейде оның біреуін өткізіп жібереді:

• Қолтаңбаны тексеріңіз. Әр оқиғада Stripe-Signature тақырыбы бар. Өңдеушіңіз оны endpoint-тің қол қою құпиясымен (ол whsec_ деп басталады) тексереді. Мұнсыз кез келген адам серверіңізге жалған «төлем сәтті өтті» жібере алады.
• Шикі сұрау денесін пайдаланыңыз. Фреймворк денені алдын ала талдаса немесе өзгертсе, қолтаңба тексерісі сәтсіз аяқталады.
• Тез 2xx жауап қайтарыңыз, содан кейін баяу жұмысты орындаңыз. Тайм-аут сәтсіздік болып саналады.
• Қайталануларды өңдеңіз. Stripe бір оқиғаны бірнеше рет жеткізуі мүмкін. Өңделген оқиға ID-лерін жазыңыз немесе орындауды екі рет іске қосқанда қауіпсіз етіңіз.
• Реттілікке сенбеңіз. Stripe оқиғалардың болған ретімен келетінін кепілдемейді.
• Қайталауларды күтіңіз. Нақты режимде Stripe сәтсіз жеткізілімдерді үш күнге дейін қайталайды, сондықтан қысқа үзіліс төлемдерді жоғалтпайды — бірақ өңдеушіңіз кешіккен оқиғаларды да дұрыс өңдеуі керек.

Webhook-терге ашық HTTPS мекенжайы керек, сондықтан олар әдетте қолданба жарияланғаннан кейін ғана жұмыс істейді (әзірлеушілер үшін Stripe CLI оқиғаларды жергілікті машинаға жібере алады).

Бүкіл ағымды қамтитын промпт

Бір реттік сатып алу үшін «Pro пакет» үшін Stripe Checkout қосыңыз (бағаның ID-і STRIPE_PRICE_ID ішінде). Checkout Session-ды серверде құпиялардағы STRIPE_SECRET_KEY арқылы жасаңыз, сессияға кірген пайдаланушының ID-ін қосыңыз. POST /api/stripe/webhook endpoint-ін қосыңыз, ол STRIPE_WEBHOOK_SECRET арқылы Stripe қолтаңбасын шикі сұрау денесінде тексеріп, checkout.session.completed оқиғасын өңдеп, сол пайдаланушыны Pro пакетке ие деп белгілеуі керек. Егер бірдей оқиға екі рет келсе, қауіпсіз болсын. Сәтті және бас тарту беттерін қосыңыз. Құпия кілтті браузерге ешқашан көрсетпеңіз.

Жазылымдар үшін қосыңыз: «STRIPE_PRICE_ID арқылы жазылым режимін пайдаланыңыз. invoice.paid, invoice.payment_failed, customer.subscription.updated және customer.subscription.deleted оқиғаларын өңдеңіз. Stripe клиент порталын ашатын «Біллингті басқару» түймесін қосыңыз.»

Тест режимі

Stripe-та бөлек sandbox (тест) және нақты орталықтары бар, олардың кілттері де бөлек. Sandbox кілттері pk_test_, sk_test_ немесе rk_test_ деп басталады; нақты кілттер pk_live_, sk_live_ немесе rk_live_ деп басталады. Тест транзакциялар ақшаны жылжытпайды.

Stripe-тың тест құжаттамасынан пайдалы тест карталары (кез келген болашақ мерзім мен кез келген үш таңбалы CVC):

Кемінде мынаны сынаңыз:

• Сәтті төлем дұрыс нәрсені дұрыс пайдаланушыға ашады
• Бас тартылған карта айқын хабарлама көрсетеді және ештеңе ашпайды
• Төлегеннен кейін браузер қойындысын бірден жапқанның өзінде қолжетімділік бар (бұл сәтті бет емес, webhook жұмыс істейтінін дәлелдейді)
• Stripe бетінде бас тарту пайдаланушыны қолданбаға ешқандай төлемсіз қайтарады
• Жазылымдар үшін: клиент порталында бас тартыңыз және қолжетімділік дұрыс уақытта аяқталатынын растаңыз

Нақты іске қосу

1. Stripe аккаунтыңызды белсендіріңіз бизнес және банк деректеріңізбен.
2. Нақты кілттерді қолданба құпияларына ауыстырыңыз. Stripe интеграцияңызға қажет рұқсаттары бар шектелген кілттерді ұсынады, толық құпия кілтті емес.
3. Нақты webhook endpoint-ін жасаңыз, жарияланған қолданбаңызға бағыттаңыз. Оның тест құпиясынан бөлек өз қол қою құпиясы бар — оны жаңартыңыз.
4. Өнімдер мен бағаларды нақты режимде қайта жасаңыз; тест режиміндегі ID-лер сонда болмайды.
5. Бір нақты шағын сатып алуды жасап, қайтарыңыз.

Әр кілтті жоба құпияларында сақтаңыз, кодта немесе чатта ешқашан. Қауіпсіздік тексеру тізіміміз кілттер мен webhook тексеруі туралы толығырақ жазылған.

Салық, қайтару және құжаттар

Төлем кодпен шешілмейтін міндеттемелер әкеледі. Бұл салық кеңесі емес; бухгалтермен кеңесіңіз.

• Сатылым салығы, ҚҚС және GST. Сіз және клиенттеріңіз қай жерде екеніңізге байланысты тіркелуіңіз, салық салып, есеп беруіңіз қажет болуы мүмкін. Stripe Tax салықты checkout кезінде есептеп жинай алады, сатылымдарыңыздың міндеттеме туғызуы мүмкін жерлерін бақылай алады және тіркелу мен есеп беруге көмектесе алады — бірақ жауапкершілік сізде қалады. Merchant-of-record провайдерлері көбірек жүктемені өз мойнына алатын балама.
• Қайтару және дауларды қарау (chargeback). Ысыққа дейін қайтару саясатын шешіп, сайтыңызға қойыңыз. Дауларда болады; не сатылғанын және жеткізілгенін жазып қойыңыз.
• Түбіртектер мен шот-фактуралар. 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 арқылы төлем қабылдау және backend-те webhook өңдеу бар.

Сұрақтар