Ինչպես ընդունել վճարումներ ձեր հավելվածում. checkout, բաժանորդագրություններ և webhook-ներ

Հավելվածում վճարումներ ընդունելու ամենապարզ եղանակը Stripe-ն է։ Օգտագործեք Payment Link, եթե պարզապես պետք է «Գնել» կոճակ և կարող եք պատվերները ձեռքով կատարել, Stripe Checkout՝ եթե հավելվածը պետք է իմանա, թե ով է վճարել և ինքնաբար արձագանքի, և Checkout բաժանորդագրության ռեժիմում գումարած Stripe-ի հաճախորդի պորտալը կրկնվող վճարումների համար։ Յուրաքանչյուր դեպքում, բացի ամենապարզից, պետք է նաև webhook՝ սերվերի endpoint, որին 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 Link-ները կարող են վաճառել ապրանք, բաժանորդագրություն կամ ընդունել նվիրատվություն, և դուք կարող եք թույլ տալ հաճախորդներին ընտրել, թե ինչ վճարեն, կամ սահմանափակել գնումների քանակը։

Բայց կա թակարդ․ ձեր հավելվածը ինքնաբար չի իմանում, որ որևէ մուտք գործած օգտատեր է վճարել։ Նվիրատվության էջի կամ փոքր խանութի համար, որտեղ պատվերները 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-ը առաջարկում է հոստինգ արված customer portal։ Ըստ Stripe-ի փաստաթղթերի՝ հաճախորդները այնտեղ կարող են թարմացնել վճարման եղանակները և հաշվարկման տվյալները, փոխել կամ չեղարկել բաժանորդագրությունները և դիտել ու ներբեռնել հաշիվները։ Այն կարգավորում եք Stripe Dashboard-ում և ավելացնում «Կառավարել վճարումները» կոճակ, որ հաճախորդին ուղարկում է այնտեղ։ Դա խնայում է ձեզ այդ էկրանների կառուցումից։

Webhook-ներ. մասը, որը չեք կարող բաց թողնել

Webhook-ը HTTP հարցում է, որ Stripe-ը ուղարկում է ձեր սերվերին, երբ ինչ-որ բան է տեղի ունենում։ (Տես ինչ է webhook-ը՝ ընդհանուր գաղափարի համար։) Stripe-ի կատարման ուղեցույցը հստակ է․ պատվերները կատարելու համար չեք կարող հենվել միայն հաջողության էջի վրա, քանի որ հաճախորդը կարող է վճարել և կապը կորցնել, մինչ այդ էջը կբեռնվի։ Բաժանորդագրությունների և հետաձգված վճարման եղանակների համար webhook-ները պարտադիր են։

Իրադարձություններ, որոնք արժե մշակել

Ճիշտ webhook մշակիչի կանոնները

Սրանք անմիջապես գալիս են Stripe-ի webhook փաստաթղթերից, և AI-ով գեներացված մշակիչները երբեմն բաց են թողնում դրանցից մեկը․

• Ստուգեք ստորագրությունը։ Յուրաքանչյուր իրադարձություն ներառում է Stripe-Signature վերնագիր։ Ձեր մշակիչը ստուգում է այն endpoint-ի ստորագրության գաղտնիքով (սկսվում է whsec_-ով)։ Առանց դրա, ցանկացած մեկը կարող էր ուղարկել կեղծ «վճարումը հաջող էր» ձեր սերվերին։
• Օգտագործեք հումքային հարցման մարմինը։ Ստորագրության ստուգումները ձախողվում են, եթե ձեր շրջանակը նախ վերլուծում կամ փոփոխում է մարմինը։
• Արագ վերադարձրեք 2xx պատասխան, իսկ հետո կատարեք դանդաղ աշխատանքը։ Ժամանակի սպառումը համարվում է ձախողում։
• Կարգավորեք կրկնօրինակները։ Stripe-ը կարող է նույն իրադարձությունը մի քանի անգամ առաքել։ Գրանցեք մշակված իրադարձությունների ID-ները կամ դարձրեք կատարումը անվտանգ երկու անգամ կատարելու համար։
• Մի ենթադրեք հերթականություն։ Stripe-ը չի երաշխավորում, որ իրադարձությունները կհասնեն այն հերթականությամբ, որով տեղի են ունեցել։
• Սպասեք կրկնություններին։ Արտադրության ռեժիմում Stripe-ը կրկնում է ձախողված առաքումները մինչև երեք օր, ուստի կարճ խափանումը չի կորցնում վճարումները, բայց ձեր մշակիչը պետք է գլուխ հանի ուշացած իրադարձություններից։

Webhook-ներին անհրաժեշտ է հանրային HTTPS հասցե, ուստի սովորաբար աշխատում են միայն երբ ձեր հավելվածը հրապարակված է (Stripe-ի CLI-ն կարող է իրադարձություններ փոխանցել տեղական մեքենային մշակողների համար)։

Հրաման, որ ծածկում է ամբողջ հոսքը

Ավելացրու միանգամյա գնում Stripe Checkout-ով «Pro pack»-ի համար (գնի ID-ն STRIPE_PRICE_ID-ում)։ Ստեղծիր Checkout Session սերվերի վրա՝ օգտագործելով STRIPE_SECRET_KEY-ը գաղտնիքներից, և ներառիր մուտք գործած օգտատիրոջ ID-ն session-ում։ Ավելացրու 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 (թեստային) և արտադրական միջավայրեր՝ առանձին բանալիներով։ Sandbox բանալիները սկսվում են pk_test_, sk_test_ կամ rk_test_-ով․ արտադրական բանալիները՝ pk_live_, sk_live_ կամ rk_live_-ով։ Թեստային գործարքները փող չեն տեղափոխում։

Օգտակար թեստային քարտեր Stripe-ի թեստավորման փաստաթղթերից (ցանկացած ապագա ժամկետ, ցանկացած երեք նիշանի CVC)․

Փորձարկեք առնվազն․

• Հաջող վճարումը ապակողպում է ճիշտ բանը ճիշտ օգտատիրոջ համար
• Մերժված քարտը ցույց է տալիս հստակ հաղորդագրություն և ոչինչ չի ապակողպում
• Վճարումից անմիջապես հետո փակելով բրաուզերի ներդիրը, մուտքը դեռ տրվում է (սա ապացուցում է, որ webhook-ն է աշխատում, ոչ թե միայն հաջողության էջը)
• Stripe էջում չեղարկումը վերադարձնում է օգտատիրոջը ձեր հավելված՝ առանց որևէ գանձման
• Բաժանորդագրությունների համար՝ չեղարկեք customer portal-ում և ստուգեք, որ մուտքը դադարում է, երբ պետք է

Արտադրական գործարկում

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-ներ և 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. Անցնելուց հետո դեպի իրական բանալիներ, նորից հրապարակեք, որ արտադրական հավելվածը դրանք ընդունի։

Տես Ընդունել վճարումներ Stripe-ով և Մշակել webhook-ներ ձեր backend-ում փաստաթղթերում։

Հարցեր