Інтеграція Stripe Billing для SaaS-підписок

Уявіть: ви запускаєте SaaS, через місяць — 1000 користувачів, кожен з різним планом, частина на тріалі, частина скасовує. Без білінгової системи — хаос. Stripe Billing — готове рішення, яке покриває 95% сценаріїв: підписки, пробні періоди, апгрейди/даунгрейди, prorated billing, метеринг, автоматичний retry при невдачі. На відміну від самописної системи, Stripe Billing скорочує час розробки з 2–3 місяців до 1–2 тижнів — це в 5–10 разів швидше. І мінімізує помилки завдяки перевіреним алгоритмам. Економія на розробці — від $15 000, а на підтримці — $5 000 на рік. Ми інтегрували Stripe у 30+ проєктах, гарантуючи стабільну роботу білінгу під ключ. Наш досвід дозволяє передбачити та уникнути типових проблем: некоректна обробка trial, помилки prorating, збої у вебхуках.

Ключові сутності

Product → Price → Subscription → Invoice → PaymentIntent. Продукт — план (Basic, Pro, Enterprise). До нього прив'язуються ціни (місячна/річна). Підписка прив'язує customer до ціни. Invoice виставляється автоматично.

Як Stripe Billing вирішує проблему білінгу?

Stripe бере на себе всю рутину: створення інвойсів, спроби списання, prorating, trial. Вам потрібно лише налаштувати продукти та вебхуки для синхронізації статусів. Це скорочує час розробки з місяців до 1–2 тижнів.

Створення продуктів і цін

$product = \Stripe\Product::create([ 'name' => 'Pro Plan', 'metadata' => ['plan_id' => 'pro'], ]); $monthlyPrice = \Stripe\Price::create([ 'product' => $product->id, 'unit_amount' => 2900, 'currency' => 'usd', 'recurring' => ['interval' => 'month'], 'lookup_key' => 'pro_monthly', ]); $yearlyPrice = \Stripe\Price::create([ 'product' => $product->id, 'unit_amount' => 27900, 'currency' => 'usd', 'recurring' => ['interval' => 'year'], 'lookup_key' => 'pro_yearly', ]); 

Реєстрація користувача та створення підписки

Процес складається з чотирьох кроків: створення Stripe-клієнта, створення підписки з trial, передача client_secret на фронтенд, обробка вебхуків. Розглянемо кожен.

$stripeCustomer = \Stripe\Customer::create([ 'email' => $user->email, 'name' => $user->name, 'metadata' => ['user_id' => $user->id], ]); $subscription = \Stripe\Subscription::create([ 'customer' => $user->stripe_customer_id, 'items' => [['price' => 'pro_monthly']], 'trial_period_days' => 14, 'payment_behavior' => 'default_incomplete', 'payment_settings' => ['save_default_payment_method' => 'on_subscription'], 'expand' => ['latest_invoice.payment_intent'], ]); $clientSecret = $subscription->latest_invoice->payment_intent->client_secret; 

payment_behavior: default_incomplete — підписка активується лише після успішного першого платежу. Важливо для безкоштовних trial: картка прив'язується, але не списується.

Апгрейд/даунгрейд

public function changePlan(User $user, string $newPriceLookupKey): void { $prices = \Stripe\Price::all(['lookup_keys' => [$newPriceLookupKey]]); $newPrice = $prices->data[0]; $subscription = \Stripe\Subscription::retrieve($user->stripe_subscription_id); \Stripe\Subscription::update($subscription->id, [ 'items' => [[ 'id' => $subscription->items->data[0]->id, 'price' => $newPrice->id, ]], 'proration_behavior' => 'create_prorations', 'billing_cycle_anchor'=> 'unchanged', ]); } 

При апгрейді з proration Stripe автоматично кредитує невикористаний час і виставляє інвойс на різницю. Річна підписка — proration_behavior: none.

Чому варто використовувати Stripe Customer Portal?

Готовий UI для керування підпискою: зміна картки, скасування, історія інвойсів. Не потрібно писати з нуля. Достатньо створити сесію BillingPortal.Session і перенаправити користувача. Це економить до 40 годин розробки інтерфейсу.

Webhook: синхронізація статусів

Вся бізнес-логіка будується на вебхуках, а не на синхронних відповідях API. Основні події:

Також важливо обробляти customer.subscription.paused та resumed, якщо підтримуєте паузу.

protected array $handlers = [ 'customer.subscription.created' => 'onSubscriptionCreated', 'customer.subscription.updated' => 'onSubscriptionUpdated', 'customer.subscription.deleted' => 'onSubscriptionCancelled', 'invoice.payment_succeeded' => 'onInvoicePaid', 'invoice.payment_failed' => 'onInvoicePaymentFailed', 'customer.subscription.trial_will_end'=> 'onTrialEndingSoon', ]; public function onInvoicePaymentFailed(array $event): void { $subscription = $event['data']['object']['subscription']; $user = User::where('stripe_subscription_id', $subscription)->firstOrFail(); $nextRetry = $event['data']['object']['next_payment_attempt']; Notification::send($user, new PaymentFailedNotification($nextRetry)); } 

Як обробляти невдалі платежі?

Stripe автоматично робить до 3 спроб списання з інтервалами 2, 3 та 5 днів. Ваше завдання — повідомляти користувача та оновлювати статус підписки на past_due. Після третьої невдачі підписка переходить у canceled. Щоб уникнути втрати клієнтів, реалізуйте сценарій: при першій невдачі — лист, при другій — push-повідомлення, при третій — блокування доступу з можливістю продовження.

Metered billing

Для оплати за споживання (API виклики, сховище):

$price = \Stripe\Price::create([ 'product' => $product->id, 'currency' => 'usd', 'recurring' => [ 'interval' => 'month', 'usage_type' => 'metered', 'aggregate_usage'=> 'sum', ], 'billing_scheme' => 'per_unit', 'unit_amount' => 1, ]); \Stripe\SubscriptionItem::createUsageRecord( $subscriptionItemId, ['quantity' => $apiCallsThisPeriod, 'action' => 'set'] ); 

action: set — абсолютне значення, increment — додати до поточного. set безпечніше при retry.

Порівняння моделей білінгу

Що входить у роботу

• Налаштування продуктів і цін у Stripe Dashboard.
• Створення міграцій для синхронізації планів.
• Реалізація реєстрації та створення підписки з trial.
• Налаштування вебхуків та обробка ключових подій.
• Інтеграція Customer Portal.
• Документація по API та пост-релізна підтримка 1 місяць.

Як гарантувати 99.9% uptime білінгу?

Використовуйте failover-логіку: якщо Stripe API недоступний, кешуйте запити та повторюйте їх з експоненційною затримкою. Налаштуйте моніторинг вебхуків з оповіщенням у Telegram/Slack. Завжди обробляйте події invoice.payment_failed — це знижує churn на 20% при своєчасному повідомленні.

Зв'яжіться з нами для точної оцінки вашого проекту. Базова інтеграція — від 5 до 10 робочих днів. Складні сценарії (metered billing, кілька валют) — до 3 тижнів. Отримайте консультацію щодо інтеграції Stripe Billing — налаштуйте білінг під ваш SaaS без головного болю.