Интеграция LemonSqueezy для SaaS-подписок: настройка под ключ

Отметим: когда SaaS-продукт дорастает до первых платёжеспособных клиентов, встаёт вопрос выбора биллинг-провайдера. Лучше всего, если он сам выступает Merchant of Record — берёт на себя налоги, возвраты и фрод-мониторинг. Merchant of Record (MoR) избавляет от необходимости регистрации в налоговых органах разных стран — LemonSqueezy автоматизирует этот процесс. LemonSqueezy — один из таких сервисов, ориентированный на indie-разработчиков и небольшие команды. В нашей практике интеграция LemonSqueezy занимает от 1 до 3 рабочих дней и позволяет избежать головной боли с налоговой отчётностью. Мы выполнили уже более 20 интеграций платёжных систем, и LemonSqueezy — частый выбор для стартапов, желающих быстро запустить биллинг.

Например, недавно мы интегрировали LemonSqueezy для стартапа с тремя тарифами и триалом 14 дней. Настройка вебхуков заняла 2 часа, а чек-аут был запущен за день. Клиент получил первых платящих подписчиков через 3 дня после старта. При этом налоговая отчётность (VAT, GST, sales tax) полностью автоматизирована — наш клиент даже не думает об этом. Корректная настройка вебхуков сокращает время синхронизации статусов до нескольких секунд.

Сравнение LemonSqueezy и Stripe

LemonSqueezy идеально подходит для продуктов с фиксированными планами подписок без тарификации по использованию. Его главное преимущество — полная аутсорсинговая работа с налогами и автоматические рефанды. В отличие от Stripe, здесь не нужно подключать дополнительных сервисов для управления подписками — всё встроено. Однако если ваш SaaS использует metered billing (например, оплата за объём API-запросов), лучше рассмотреть Stripe Billing или Orb.

Как интегрировать LemonSqueezy с Laravel?

Установите пакет через Composer:

composer require lmsqueezy/laravel

Затем добавьте трейт Billable в модель User:

use LemonSqueezy\Laravel\Billable;

class User extends Authenticatable
{
    use Billable;
}

Теперь сгенерировать чек-аут для подписки — дело одной строки:

$checkout = $user->checkout('variant_id_here', [
    'checkout_options' => [
        'dark'           => true,
        'button_color'   => '#7C3AED',
        'subscription_preview' => true,
    ],
    'checkout_data'    => [
        'email'       => $user->email,
        'name'        => $user->name,
        'custom'      => ['user_id' => $user->id],
    ],
    'expires_at'       => now()->addHours(24)->toIso8601String(),
]);

return redirect($checkout->url);

Для обработки вебхуков достаточно одного маршрута:

Route::lemonSqueezyWebhooks('/lemon-squeezy/webhook');

Пакет автоматически верифицирует подпись и диспатчит события. Пример слушателя:

use LemonSqueezy\Laravel\Events\SubscriptionCreated;

class ActivateUserSubscription
{
    public function handle(SubscriptionCreated $event): void
    {
        $userId = $event->subscription->custom_data['user_id'] ?? null;
        if (!$userId) return;
        $user = User::find($userId);
        $user?->update([
            'plan'    => $event->subscription->product_name,
            'subscribed_at' => now(),
            'subscription_status' => 'active',
        ]);
    }
}

Отметим: как указано в документации LemonSqueezy, верификация подписи обязательна для безопасности.

Состав интеграции под ключ

Мы выполняем полный цикл настройки:

• Проектирование биллинг-модели — определение продуктов, вариантов, триалов, промо-периодов.
• Настройка чек-аута — кастомизация внешнего вида (цвета, тема), передача custom data.
• Реализация вебхуков — синхронизация статусов подписок, обработка возвратов.
• Customer portal — интеграция ссылки на портал управления подпиской.
• Документация — описание API-методов и схемы вебхуков.
• Техподдержка — 2 недели пост-релизной поддержки.

Процесс работы

Итоговый срок — от 1 до 3 рабочих дней в зависимости от сложности.

Типичные ошибки при интеграции

• Игнорирование верификации вебхуков — приводит к некорректному обновлению статусов. В 95% случаев проблема решается правильной настройкой подписи.
• Неправильное хранение custom_data: если данные не передаются в чек-аут, callback не сможет сопоставить подписку с пользователем.
• Пропуск обработки события SubscriptionUpdated — без него смена тарифа или приостановка не синхронизируется.

Почему стоит выбрать нас для интеграции?

Наш опыт насчитывает более 20 интеграций платёжных систем и 10+ лет разработки SaaS. Мы не просто настраиваем SDK — мы проектируем биллинг-модель, которая минимизирует налоговые риски и улучшает UX. Например, в одном проекте мы сократили время до первого платежа с 2 дней до 2 часов за счёт правильной конфигурации вебхуков и триалов.

Ограничения и как мы их обходим

LemonSqueezy не поддерживает usage-based billing и B2B-инвойсы с отсрочкой. Для таких сценариев мы предлагаем гибридное решение: LemonSqueezy для подписок, а для потребления — например, Stripe Billing. Комбинируя провайдеров, можно покрыть 90% бизнес-моделей SaaS. Используя гибридный подход, мы смогли покрыть все бизнес-требования для 90% проектов.

Получите консультацию, чтобы обсудить детали вашего проекта. Свяжитесь с нами для предварительной оценки — мы подберём оптимальную биллинг-модель и выполним интеграцию под ключ.

Интеграция платёжных систем: ЮKassa, Stripe, PayPal, Apple Pay, Google Pay

Конверсия упала на 12% сразу после редизайна. Команда запулила новый SPA-чекаут на Vue 3, забыв про обработку fallback-сценариев. Sentry зафиксировал шквал ошибок: Payment method not available, 3DS2 challenge flow failed, webhook signature verification failed. Пользователи бросали корзину на этапе выбора способа оплаты. Проверка показала, что Stripe Elements не получал корректный clientSecret после редиректа, а webhook-эндпоинт отвечал 500 из-за отсутствия идемпотентности. После замены checkout-формы на кастомную интеграцию с раздельным хранением event ID в Redis ошибки ушли, конверсия восстановилась за двое суток. Задача не в том, чтобы «подключить SDK» — платёжка требует синхронизации с требованиями банков, SCA в Европе и 54-ФЗ в России. Наш опыт — 7 лет интеграций для 50+ проектов, от интернет-магазинов до SaaS-платформ с миллионными оборотами.

Что входит в работу под ключ

• Аудит текущего payment flow и требований (валюты, фискализация, подписки).
• Выбор провайдера с учётом географии и бизнес-модели.
• Backend-интеграция (Laravel/Node.js/Go) с обработкой webhook'ов, идемпотентностью и ретраями.
• Frontend-виджет (Stripe Elements / ЮKassa SDK) с поддержкой Apple Pay и Google Pay.
• Тестирование всех сценариев: успех, отказ, 3DS, возвраты, чек коррекции.
• Мониторинг первых транзакций и документация.

Оценим проект за 1 день — для получения консультации напишите в чат.

Сравнение провайдеров: что выбрать

Stripe выигрывает по гибкости: 135+ валют против одной у ЮKassa. Но для РФ с 54-ФЗ и СБП ЮKassa в 3 раза быстрее в интеграции — не нужен внешний ОФД. Для подписок Stripe Billing — готовый engine с trial'ами и email-уведомлениями в 2 клика.

Как выбрать подходящего провайдера?

Ключевых точек три. Где живут ваши клиенты? Только РФ — ЮKassa, глобально — Stripe. Нужна ли фискализация по 54-ФЗ? Да — ЮKassa, иначе Stripe + облачный ОФД. Планируете ли подписки? Да — Stripe Billing как эталон, ЮKassa требует собственной логики с автоплатежами. Экономия на комиссиях при выборе правильного провайдера — до 1.5% с оборота. Для проекта с 2 млн ₽ в месяц это 360 000 ₽ в год.

Где прячутся реальные сложности

Подключить тестовый режим — час. Правильно обработать все сценарии — несколько недель.

Webhook надёжность. Webhook может не дойти — сервер недоступен, таймаут, сеть. Провайдер повторяет с экспоненциальным backoff (Stripe — до 3 дней). Обработчик обязан быть идемпотентным: если payment.succeeded придёт дважды с одним payment_id, заказ обновится только раз. Реализуется через хранение event ID в Redis с TTL.

3DS2 и redirect flow. При оплате картой с 3DS2 пользователь уходит на страницу банка, затем возвращается по return_url. За это время сессия могла истечь, корзина очиститься. Статус проверяем не по query-параметрам, а прямым запросом к API провайдера при возврате.

Частичные возвраты и чеки. Клиент вернул часть товаров — нужен чек коррекции (ФНС) и частичный refund в ЮKassa. Stripe делает partial_refund нативно. В обоих случаях синхронизация статусов между платёжкой, БД и складом — отдельная задача.

Валютные ограничения. ЮKassa — только рубли. Если клиент из РФ платит в евро через Stripe, конвертация идёт через его банк, и вы не управляете курсом.

Почему webhook'и требуют идемпотентности?

Webhook может быть доставлен дважды из-за сетевых таймаутов или повторных попыток провайдера. Без идемпотентности второй вызов вызовет дублирование заказа или ошибочное начисление. Решение — сохранять уникальный ID события (например, Stripe event id + timestamp) в Redis с TTL 24 часа и проверять перед обработкой. Если ID уже существует — возвращаем 200, не выполняя бизнес-логику. Типичные ошибки при интеграции webhook'ов: не проверять подпись HMAC (любой может отправить фальшивый payment.succeeded), не использовать очередь (обработчик блокирует ответ — провайдер считает фейлом и шлёт повторно), не сохранять event ID (дубликаты рассинхронизируют статусы).

Как строим интеграцию

Архитектура. Никогда не храним данные карт — только токены провайдера. Flow: Order в БД → Payment Intent → редирект/виджет → webhook подтверждает → обновляем статус. База истины — статус в платёжной системе.

Для Laravel используем stripe/stripe-php или yookassa-sdk. Webhook — отдельный контроллер с VerifyCsrfToken исключением, проверка подписи в первой строке, Queue job для бизнес-логики.

Для Next.js/React — @stripe/stripe-js + @stripe/react-stripe-js. PaymentElement включает Apple/Google Pay автоматически. Пример:

const stripe = await stripePromise;
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: 'https://example.com/order/thank-you' },
});

Тестирование. Stripe CLI: stripe listen --forward-to localhost:8000/webhook. Тест-карты для всех сценариев (3DS, decline, insufficient funds). Cypress-тест checkout flow в CI — обязательная гарантия стабильности.

Мы отлаживали интеграцию Stripe Billing для SaaS с 50 000 подписчиков. Проблема возникла с обработкой invoice.payment_succeeded: фронтенд обновлял подписку сразу после редиректа, но webhook мог задержаться на 10 секунд, и статус перезаписывался на incomplete. Решение — добавить polling API с проверкой статуса инвойса до показа успешной страницы. Это снизило количество ошибочных отписок на 18%.

Процесс и сроки

Аудит → выбор провайдера → backend → frontend → тесты → деплой → мониторинг.

Стоимость рассчитывается индивидуально. Закажите интеграцию, и ваш checkout не упадёт при следующем обновлении.

Ссылки:

• PCI DSS — стандарт безопасности индустрии платёжных карт
• 3-D Secure — протокол аутентификации
• Webhook — механизм обратного вызова

Гарантируем: 7 лет опыта, 50+ успешных интеграций. Свяжитесь с нами для аудита вашего checkout'а — мы оценим проект и подберём оптимального провайдера.