Як додати оплату до застосунку: checkout, підписки та webhooks

Найпростіший спосіб додати оплату до застосунку — це 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 потребує бекенду.

Підписки

Підписки використовують Checkout у режимі підписки з періодичною ціною, яку ви налаштовуєте в Stripe. Перший платіж працює за описаним вище процесом. Після цього продовження, невдалі картки, оновлення тарифу та скасування відбуваються з часом — часто тоді, коли клієнта немає у вашому застосунку, — тож ваш застосунок дізнається про них лише через webhooks.

Щоб клієнти могли самостійно керувати підпискою, Stripe пропонує розміщений портал клієнта. За документацією Stripe, там клієнти можуть оновлювати способи оплати та платіжні реквізити, змінювати або скасовувати підписки, переглядати та завантажувати рахунки. Ви налаштовуєте його в Stripe Dashboard і додаєте кнопку «Керувати оплатою», яка надсилає клієнта туди. Це позбавляє вас від створення цих екранів самостійно.

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

Webhook — це HTTP-запит, який Stripe надсилає на ваш сервер, коли щось відбувається. (Загальне пояснення дивіться в що таке webhook.) Посібник Stripe з виконання замовлень прямо каже: не можна покладатися лише на сторінку успіху, щоб виконати замовлення, адже клієнт може заплатити, а потім втратити з'єднання до того, як ця сторінка завантажиться. Для підписок і відкладених способів оплати webhooks обов'язкові.

Події, які варто обробляти

Правила для правильного обробника webhook

Це взято безпосередньо з документації Stripe щодо webhooks, і обробники, згенеровані ШІ, інколи пропускають одне з них:

• Перевіряйте підпис. Кожна подія містить заголовок Stripe-Signature. Ваш обробник перевіряє його за секретом підпису кінцевої точки (він починається з whsec_). Без цього будь-хто міг би надіслати на ваш сервер фальшиве повідомлення «платіж успішний».
• Використовуйте сире тіло запиту. Перевірка підпису не спрацює, якщо фреймворк спершу розбирає або змінює тіло.
• Швидко повертайте відповідь 2xx, а повільнішу роботу виконуйте після цього. Тайм-аути рахуються як помилки.
• Обробляйте дублікати. Stripe може доставити ту саму подію більше ніж один раз. Зберігайте ID оброблених подій або зробіть виконання замовлення безпечним для повторного запуску.
• Не покладайтеся на порядок. Stripe не гарантує, що події надходять у тому порядку, в якому відбулися.
• Очікуйте повторів. У бойовому режимі Stripe повторює невдалі доставки протягом до трьох днів, тож коротка перерва не призведе до втрати платежів, але ваш обробник має справлятися із запізнілими подіями.

Webhooks потребують публічної адреси HTTPS, тож зазвичай вони працюють лише після публікації застосунку (CLI Stripe може переспрямовувати події на локальний комп'ютер для розробників).

Промпт, який охоплює весь процес

Додай разову покупку через Stripe Checkout для «Pro pack» (ID ціни в STRIPE_PRICE_ID). Створюй Checkout Session на сервері, використовуючи STRIPE_SECRET_KEY із секретів, і включай ID авторизованого користувача в сесію. Додай endpoint POST /api/stripe/webhook, який перевіряє підпис Stripe за допомогою STRIPE_WEBHOOK_SECRET, використовуючи сире тіло запиту, обробляє checkout.session.completed і позначає цього користувача як такого, що має Pro pack. Зроби його безпечним, якщо та сама подія прийде двічі. Сторінки успіху й скасування. Ніколи не передавай секретний ключ у браузер.

Для підписок додайте: «Використовуй режим підписки з STRIPE_PRICE_ID. Обробляй invoice.paid, invoice.payment_failed, customer.subscription.updated і customer.subscription.deleted. Додай кнопку Manage billing, яка відкриває портал клієнта Stripe.»

Тестовий режим

У Stripe є окремі середовища sandbox (тестове) і live (бойове) з окремими ключами. Тестові ключі починаються з pk_test_, sk_test_ або rk_test_; бойові — з pk_live_, sk_live_ або rk_live_. Тестові транзакції не переміщують гроші.

Корисні тестові картки з документації Stripe щодо тестування (будь-яка майбутня дата завершення, будь-який трицифровий CVC):

Принаймні перевірте:

• Успішний платіж відкриває потрібне для правильного користувача
• Відхилена картка показує зрозуміле повідомлення і нічого не відкриває
• Закриття вкладки браузера одразу після оплати все одно дає доступ (це доводить, що webhook працює, а не лише сторінка успіху)
• Скасування на сторінці Stripe повертає користувача до вашого застосунку без жодного списання
• Для підписок: скасуйте в порталі клієнта та переконайтеся, що доступ завершується вчасно

Запуск у роботу

1. Активуйте обліковий запис Stripe з даними вашого бізнесу та банку.
2. Замініть ключі на бойові в секретах вашого застосунку. Stripe рекомендує обмежені ключі лише з дозволами, потрібними вашій інтеграції, а не необмежений секретний ключ.
3. Створіть бойову кінцеву точку webhook, яка вказує на ваш опублікований застосунок. Вона має власний секрет підпису, відмінний від тестового, — оновіть його.
4. Створіть знову продукти й ціни в бойовому режимі; тестові ID там не існують.
5. Зробіть одну реальну невелику покупку і поверніть її.

Зберігайте кожен ключ у секретах проєкту, ніколи в коді чи чаті. Наш контрольний список безпеки докладніше розглядає ключі та перевірку webhook.

Податки, повернення та документи

Платежі несуть зобов'язання, які код не вирішує. Це не податкова порада; зверніться до бухгалтера.

• Податок з продажів, ПДВ і GST. Залежно від того, де знаходяться ви та ваші клієнти, може знадобитися реєстрація, стягнення та подання податкової звітності. Stripe Tax може розрахувати й стягнути податок під час оформлення замовлення, відстежити, де ваші продажі можуть створювати зобов'язання, і допомогти з реєстрацією та поданням звітності, але відповідальність залишається за вами. Провайдери типу merchant of record — це альтернатива, яка бере на себе більшу частину цього.
• Повернення та спори. Визначте політику повернень до запуску та розмістіть її на сайті. Спори (chargebacks) трапляються; зберігайте записи про те, що було куплено й доставлено.
• Квитанції та рахунки. Stripe може надсилати квитанції електронною поштою; бізнесу можуть знадобитися належні рахунки-фактури.
• Комісії. Кожен провайдер бере плату за транзакцію. Перевіряйте поточну сторінку тарифів провайдера, а не покладайтеся на цифри зі статей.

Яка схема підходить вашому застосунку

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

Додавання оплати на Mythex

Оплата в застосунках, які ви створюєте на Mythex, використовує ваш власний обліковий запис Stripe і ключі; для вашого застосунку немає кнопки «Підключити Stripe в один клік». Звичайний процес:

1. Отримайте тестові ключі Stripe.
2. Додайте STRIPE_SECRET_KEY (а секрет webhook пізніше) до секретів проєкту — через /secrets, налаштування проєкту або картку з секретами, яку агент показує, коли потрібен ключ.
3. Попросіть агента створити Checkout за промптом, подібним до наведеного вище.
4. Тестуйте в Preview з тестовими картками. Публікуйте до реєстрації webhook, бо для нього потрібна ваша публічна адреса.
5. Після переходу на бойові ключі опублікуйте знову, щоб бойовий застосунок їх підхопив.

Див. Прийом платежів через Stripe і Обробка webhooks у вашому бекенді в документації.

Запитання