როგორ დავამატოთ გადახდები თქვენს აპში: Checkout, გამოწერები და webhook-ები

აპში გადახდების დამატების ყველაზე მარტივი გზა Stripe-ია: გამოიყენეთ Payment Link, თუ მხოლოდ „ყიდვის“ ღილაკი გჭირდებათ და შეკვეთებს ხელით დაამუშავებთ; Stripe Checkout, თუ აპს უნდა იცოდეს, ვინ გადაიხადა და ავტომატურად რეაგირება; და Checkout გამოწერის რეჟიმში და Stripe-ის customer portal-ი, თუ განმეორებადი გადახდა გაქვთ. ყველა შემთხვევაში, გარდა უმარტივესისა, გჭირდებათ webhook — სერვერის endpoint, რომელსაც Stripe იძახებს გადახდის წარმატებისას — და ყველაფერი სატესტო გასაღებებითა და სატესტო ბარათებით უნდა შეამოწმოთ, სანამ რეალურ გასაღებებზე გადახვალთ.

ეს გზამკვლევი განმარტავს ყოველ ვარიანტს, webhook-ის ნაწილს, რომელსაც უმეტესობა გამოტოვებს, და იმას, რაც რეალური ფულის მიღებამდე უნდა შეამოწმოთ. Stripe-ის დეტალები აღებულია Stripe-ის საკუთარი დოკუმენტაციიდან 2026 წლის სექტემბრის მდგომარეობით.

რატომ გჭირდებათ გადახდის პროვაიდერი

ბარათის ნომრები საკუთარ ფორმებში არასდროს შეაგროვოთ. ბარათის ნედლი მონაცემების დამუშავება PCI DSS-ის (ბარათის ინდუსტრიის უსაფრთხოების სტანდარტი) სფეროში გაგაქცევთ და სერიოზულ რისკს ქმნის. გადახდის პროვაიდერი, როგორიცაა Stripe, ჰოსტინგს უწევს გადახდის ფორმას, ინახავს ბარათს, უმკლავდება banking ავთენტიფიკაციას და აპს შედეგს აცნობებს. თქვენი აპი ხედავს მხოლოდ: „მომხმარებელმა 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-ის დოკუმენტაციის მიხედვით, Checkout მხარს უჭერს როგორც ერთჯერად, ისე გამოწერის გადახდას — როგორც Stripe-ის მიერ ჰოსტირებულ გვერდს, თქვენს საიტში ჩაშენებულ გვერდს ან ჩაშენებულ ფორმას.

პროცესი:

1. მომხმარებელი აპში Buy-ს დააჭერს.
2. თქვენი სერვერი ქმნის Checkout Session-ს თქვენი საიდუმლო გასაღებით, მასში ჩართავს ID-ს, რომელიც მას თქვენს მომხმარებელს ან შეკვეთას უკავშირებს.
3. მომხმარებელი გადამისამართდება Stripe-ზე და იხდის.
4. Stripe მას უბრუნებს თქვენს წარმატების გვერდზე.
5. Stripe აგზავნის checkout.session.completed მოვლენას თქვენს webhook-ზე, და თქვენი სერვერი შეკვეთას გადახდილად მონიშნავს ან წვდომას გახსნის.

მე-2 ნაბიჯი სერვერზე უნდა შესრულდეს, რადგან ის იყენებს თქვენს საიდუმლო გასაღებს. სწორედ ამიტომ სჭირდება Checkout-ს backend.

გამოწერები

გამოწერები იყენებს Checkout-ს გამოწერის რეჟიმში, განმეორებადი ფასით, რომელსაც Stripe-ში აყენებთ. პირველი გადახდა იგივე პროცესს მიჰყვება. შემდეგ კი განახლებები, ვადაგასული ბარათები, შუა პერიოდში გაუმჯობესებები და გაუქმებები ხდება დროის განმავლობაში — ხშირად მაშინ, როცა მომხმარებელი აპში აღარ არის — ამიტომ თქვენი აპი ამის შესახებ მხოლოდ webhook-ების გზით იგებს.

მომხმარებლისთვის, რომ საკუთარი გამოწერა მართოს, Stripe გთავაზობთ ჰოსტირებულ customer portal-ს. Stripe-ის დოკუმენტაციის მიხედვით, მომხმარებლებს იქ შეუძლიათ გადახდის მეთოდის და ანგარიშსწორების მონაცემების განახლება, გამოწერის შეცვლა ან გაუქმება და ინვოისების ნახვა და ჩამოტვირთვა. Stripe Dashboard-ში აწყობთ და აპში ამატებთ ღილაკს „ანგარიშის მართვა“, რომელიც მომხმარებელს იქ გადაიყვანს. ეს ეკრანებს თავად აშენებისგან გიხსნით.

Webhook-ები: ნაწილი, რომლის გამოტოვებაც არ შეიძლება

Webhook არის HTTP მოთხოვნა, რომელსაც Stripe თქვენს სერვერზე აგზავნის, როცა რაღაც ხდება. (იხილეთ რა არის webhook ზოგადი აზრისთვის.) Stripe-ის შესრულების გზამკვლევი მკაფიოა: მხოლოდ წარმატების გვერდზე დაყრდნობით შეკვეთას ვერ შეასრულებთ, რადგან მომხმარებელმა შეიძლება გადაიხადოს და გვერდის ჩატვირთვამდე კავშირი გაწყდეს. გამოწერებისთვის და გადახდის გადავადებული მეთოდებისთვის webhook-ები აუცილებელია.

მოვლენები, რომლებიც უნდა დაამუშავოთ

წესები სწორი webhook დამმუშავებლისთვის

ეს პირდაპირ Stripe-ის webhook დოკუმენტაციიდან მოდის, და AI-ით დაგენერირებული დამმუშავებლები ზოგჯერ ერთ-ერთს გამოტოვებს:

• გადაამოწმეთ ხელმოწერა. ყოველ მოვლენას აქვს Stripe-Signature სათაური. თქვენი დამმუშავებელი მას ამოწმებს endpoint-ის ხელმოწერის საიდუმლოთი (იწყება whsec_-ით). ამის გარეშე ნებისმიერს შეეძლო თქვენს სერვერზე ყალბი „გადახდა წარმატებულია“ გაეგზავნა.
• გამოიყენეთ ნედლი მოთხოვნის ტანი. ხელმოწერის შემოწმება ვერ მოხერხდება, თუ ჩარჩო ტანს ადრე გარდაქმნის ან დაამუშავებს.
• სწრაფად დააბრუნეთ 2xx პასუხი, შემდეგ კი ნელი სამუშაო შეასრულეთ. დროის ამოწურვა წარუმატებლობად ითვლება.
• დაამუშავეთ დუბლიკატები. Stripe შეიძლება იგივე მოვლენა ერთზე მეტჯერ მოგაწოდოთ. ჩაიწერეთ დამუშავებული მოვლენის ID-ები, ან გახადეთ შესრულება უსაფრთხო ორჯერ გაშვებისთვისაც.
• არ ივარაუდოთ თანმიმდევრობა. Stripe არ იძლევა გარანტიას, რომ მოვლენები იმ თანმიმდევრობით მოვა, როგორც მოხდა.
• მოელოდით ხელახალ ცდებს. რეჟიმში „live“ Stripe წარუმატებელ მიწოდებას სამ დღემდე იმეორებს, ასე რომ მოკლე გაუმართაობა გადახდებს არ დაკარგავს — მაგრამ თქვენმა დამმუშავებელმა გვიან მოსულ მოვლენებსაც უნდა გაუძლოს.

Webhook-ებს საჯარო HTTPS მისამართი სჭირდება, ამიტომ ისინი ჩვეულებრივ მხოლოდ მაშინ მუშაობს, როცა აპი გამოქვეყნებულია (Stripe-ის CLI დეველოპერებს მოვლენებს ლოკალურ მანქანაზე გადააგზავნის).

პრომპტი, რომელიც მთელ პროცესს ფარავს

დაამატე ერთჯერადი შესყიდვა Stripe Checkout-ით „Pro pack“-ისთვის (ფასის ID STRIPE_PRICE_ID-ში). Checkout Session შექმენი სერვერზე STRIPE_SECRET_KEY-ით საიდუმლოებებიდან და მასში ჩართე შესული მომხმარებლის ID. დაამატე POST /api/stripe/webhook endpoint, რომელიც ამოწმებს Stripe ხელმოწერას STRIPE_WEBHOOK_SECRET-ით ნედლი მოთხოვნის ტანზე, ამუშავებს checkout.session.completed-ს და ამ მომხმარებელს მონიშნავს, რომ აქვს Pro pack. გააკეთე ისე, რომ უსაფრთხო იყოს, თუ იგივე მოვლენა ორჯერ მოვა. წარმატებისა და გაუქმების გვერდები. საიდუმლო გასაღები არასდროს მიეცეს ბრაუზერს.

გამოწერისთვის დაამატე: „გამოიყენე გამოწერის რეჟიმი STRIPE_PRICE_ID-ით. დაამუშავე invoice.paid, invoice.payment_failed, customer.subscription.updated და customer.subscription.deleted. დაამატე ღილაკი „ანგარიშის მართვა“, რომელიც Stripe-ის customer portal-ს ხსნის.“

სატესტო რეჟიმი

Stripe-ს აქვს ცალკე sandbox (სატესტო) და live გარემოები, ცალკე გასაღებებით. სატესტო გასაღებები იწყება pk_test_, sk_test_ ან rk_test_-ით; live გასაღებები — pk_live_, sk_live_ ან rk_live_-ით. სატესტო ტრანზაქციები ფულს არ გადააადგილებს.

სასარგებლო სატესტო ბარათები Stripe-ის ტესტირების დოკუმენტაციიდან (ნებისმიერი მომავალი ვადა, ნებისმიერი სამნიშნა CVC):

მინიმუმ შეამოწმეთ:

• წარმატებული გადახდა სწორ მომხმარებელს სწორ რაღაცას უხსნის
• უარყოფილი ბარათი ნათელ შეტყობინებას აჩვენებს და არაფერს არ ხსნის
• ბრაუზერის ჩანართის დახურვა გადახდის მაშინვე შემდეგ მაინც იძლევა წვდომას (ეს ადასტურებს, რომ webhook მუშაობს და არა მხოლოდ წარმატების გვერდი)
• Stripe-ის გვერდზე გაუქმება მომხმარებელს აპში აბრუნებს და არაფერი ჩამოეჭრება
• გამოწერებისთვის: გააუქმეთ customer portal-ში და შეამოწმეთ, რომ წვდომა სწორ დროს წყდება

გაშვება

1. გააქტიურეთ თქვენი Stripe ანგარიში ბიზნესისა და საბანკო მონაცემებით.
2. ჩადეთ live გასაღებები აპის საიდუმლოებებში. Stripe გირჩევთ შეზღუდულ გასაღებებს, რომლებსაც მხოლოდ საჭირო უფლებები აქვთ, და არა შეუზღუდავ საიდუმლო გასაღებს.
3. შექმენით live webhook endpoint გამოქვეყნებულ აპზე. მას აქვს საკუთარი ხელმოწერის საიდუმლო, განსხვავებული სატესტოსგან — განაახლეთ იგი.
4. ხელახლა შექმენით პროდუქტები და ფასები live რეჟიმში; სატესტო ID-ები იქ არ არსებობს.
5. გააკეთეთ ერთი რეალური მცირე შესყიდვა და დააბრუნეთ თანხა.

ყველა გასაღები აპის საიდუმლოებებში შეინახეთ, არასდროს კოდში ან ჩატში. ჩვენი უსაფრთხოების ჩამონათვალი უფრო დეტალურად ფარავს გასაღებებსა და webhook-ის გადამოწმებას.

გადასახადები, დაბრუნებები და საბუთები

გადახდები ვალდებულებებს ქმნის, რომელსაც კოდი ვერ გადაჭრის. ეს საგადასახადო რჩევა არ არის; გაარკვიეთ ბუღალტერთან.

• გაყიდვების გადასახადი, დღგ და GST. იმის მიხედვით, სად ხართ თქვენ და თქვენი მომხმარებლები, შეიძლება დაგჭირდეთ რეგისტრაცია, გადასახადის დაკისრება და დეკლარირება. Stripe Tax-ს შეუძლია გადასახადის გამოთვლა და შემოკრება checkout-ზე, მონიტორინგი, სად შეიძლება წარმოიშვას ვალდებულება, და რეგისტრაციასა და დეკლარირებაში დახმარება — მაგრამ პასუხისმგებლობა თქვენზე რჩება. Merchant-of-record პროვაიდერები ალტერნატივაა, რომელიც ამ ტვირთის მეტს თავად იღებს.
• დაბრუნებები და დავები. დაბრუნების პოლიტიკა გაშვებამდე განსაზღვრეთ და საიტზე დადეთ. დავები (chargeback-ები) ხდება; შეინახეთ ჩანაწერები იმის შესახებ, რა შეიძინეს და რა მიაწოდეთ.
• ქვითრები და ინვოისები. Stripe შეუძლია ქვითრები ელფოსტით გაგზავნოს; ბიზნესს შეიძლება სჭირდებოდეს სრულყოფილი ინვოისები.
• საკომისიოები. ყველა პროვაიდერი ყოველ ტრანზაქციაზე იღებს საკომისიოს. შეამოწმეთ პროვაიდერის ამჟამინდელი ფასების გვერდი და არა სტატიებში მოყვანილი ციფრები.

რომელი დაყენება შეესაბამება თქვენს აპს

• შემოწირულობები ან რამდენიმე პროდუქტი: Payment Links. იხილეთ როგორ ავაშენოთ არასამთავრობო ორგანიზაციის შემოწირულობის ვებსაიტი.
• კალათით მაღაზია: Checkout პროდუქტის ხაზებით და webhook. იხილეთ როგორ ავაშენოთ ონლაინ მაღაზია.
• SaaS ან წევრობები: Checkout გამოწერის რეჟიმში, webhook-ები და customer portal. იხილეთ როგორ ავაშენოთ SaaS MVP და როგორ დავადგინოთ SaaS პროდუქტის ფასი.
• მარკეტფლეისი, რომელიც გამყიდველებს უხდის: სხვა, უფრო რეგულირებული დაყენება (Stripe Connect ან მსგავსი). დაგეგმეთ ცალკე.

გადახდების დამატება Mythex-ში

Mythex-ზე აგებული აპები გადახდებისთვის იყენებს თქვენს Stripe ანგარიშს და გასაღებებს; თქვენი აპისთვის ერთი დაწკაპუნებით „Stripe-ის დაკავშირება“ არ არსებობს. ჩვეულებრივი პროცესი:

1. მიიღეთ Stripe-ის სატესტო გასაღებები.
2. დაამატეთ STRIPE_SECRET_KEY (და webhook-ის საიდუმლო მოგვიანებით) პროექტის საიდუმლოებებში — /secrets-ით, პროექტის პარამეტრებით, ან იმ საიდუმლოებების ბარათით, რომელსაც აგენტი აჩვენებს, როცა გასაღები სჭირდება.
3. ითხოვეთ აგენტისგან Checkout ზემოთ მოცემულის მსგავსი პრომპტით.
4. შეამოწმეთ Preview-ში სატესტო ბარათებით. გამოაქვეყნეთ webhook-ის რეგისტრაციამდე, რადგან მას თქვენი საჯარო URL სჭირდება.
5. live გასაღებებზე გადასვლის შემდეგ კვლავ გამოაქვეყნეთ, რომ live აპმა ისინი აიღოს.

იხილეთ დოკუმენტაციაში გადახდების მიღება Stripe-ით და webhook-ების დამუშავება backend-ში.

კითხვები