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

Интеграция Paddle для SaaS-подписок

Один наш клиент потерял $12,000 за квартал из-за неправильного расчёта VAT в трёх странах. После интеграции Paddle как Merchant of Record налоговые ошибки исчезли, а конверсия выросла на 18% за счёт динамического ценообразования. Paddle берёт на себя юридическую ответственность за налоги и комплаенс в более чем 200 странах, но интеграция требует глубокого понимания API и бизнес-логики. Мы настраиваем Paddle под ваш продукт — от создания схемы цен до синхронизации подписок в вашей базе.

Paddle Billing vs Classic: что выбрать для нового проекта?

Paddle Classic использует overlay checkout — JavaScript-виджет, который встраивается на страницу. Paddle Billing предлагает собственный checkout URL или inline iframe, а также поддерживает prorated billing «из коробки» — при смене плана сумма пересчитывается автоматически. Для новых проектов мы рекомендуем Billing: он активнее развивается, имеет современное REST API и динамическое ценообразование. Classic остаётся для обратной совместимости, но мы помогаем с миграцией.

Более 80% наших проектов за последние годы мы запускаем на Paddle Billing — это стандарт для глобального SaaS.

Как мы интегрируем Paddle

Процесс занимает 3–5 рабочих дней — от sandbox до production. Включает 20+ протестированных сценариев.

Чтобы настроить Paddle:

1. Создайте продукты в Dashboard с триалами и периодами.
2. Настройте webhook endpoints для событий подписок.
3. Интегрируйте @paddle/paddle-js на фронтенде.
4. Задокументируйте верификацию подписей.
5. Протестируйте все сценарии в sandbox.

Почему Paddle Billing лучше Classic для новых проектов?

Billing даёт prorated billing «из коробки» — при апгрейде плана сумма пересчитывается автоматически. Classic требует ручного расчёта через API. Также Billing поддерживает динамическое ценообразование: один продукт отображается в разных валютах, что критично для глобального SaaS. По нашим данным, конверсия растёт на 15–20% при показе цен в местной валюте. Кроме того, Paddle Billing предоставляет более гибкие webhook-события и поддерживает transaction.completed для фиксации оплаты.

Customer Portal: кастомная реализация

В отличие от Stripe, Paddle не предоставляет готового портала управления подпиской. Мы реализуем его через API: смена плана, отмена, обновление способа оплаты — всё из вашего интерфейса. Для редиректа на обновление карты используем метод getPaymentMethodUpdateTransaction. Отмена выполняется с параметром effective_from: 'next_billing_period'.

Как Paddle обрабатывает возвраты и chargebacks?

Paddle полностью управляет процессом возврата средств и оспаривания платежей. Они берут на себя общение с платёжными системами и банками, а вы получаете уведомление через webhook transaction.updated с типом refund. Этот подход экономит время вашей поддержки.

Технические детали: webhook и синхронизация

Для верификации webhook используем библиотеку paddle/webhooks для PHP (доступна также для Node.js, Python). Каждое событие проверяется через ECDSA-подпись — это обязательное условие безопасности. Мы передаём custom_data с user_id, чтобы однозначно связать подписку с пользователем в вашей системе.

use Paddle\Webhooks\Verify; public function handleWebhook(Request $request): Response { $verified = Verify::signature( $request->getContent(), $request->header('Paddle-Signature'), config('services.paddle.webhook_secret') ); if (!$verified) { return response('Forbidden', 403); } $payload = $request->json()->all(); match ($payload['event_type']) { 'subscription.created' => $this->onSubscriptionCreated($payload['data']), 'subscription.updated' => $this->onSubscriptionUpdated($payload['data']), 'subscription.cancelled' => $this->onSubscriptionCancelled($payload['data']), 'transaction.completed' => $this->onTransactionCompleted($payload['data']), 'transaction.payment_failed' => $this->onPaymentFailed($payload['data']), default => null, }; return response('OK', 200); } private function onSubscriptionCreated(array $data): void { $userId = $data['custom_data']['user_id']; $user = User::findOrFail($userId); $user->update([ 'paddle_subscription_id' => $data['id'], 'paddle_customer_id' => $data['customer_id'], 'subscription_status' => $data['status'], 'plan' => $data['items'][0]['price']['id'], 'trial_ends_at' => $data['current_billing_period']['starts_at'] ?? null, 'renews_at' => $data['next_billed_at'], ]); } 

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

• Создание структуры продуктов и цен (с триалами, периодами, налогами)
• Интеграция @paddle/paddle-js на фронтенде с обработкой callback
• Backend-обработка webhook-событий: subscription.created, updated, cancelled, transaction.completed
• Реализация апгрейда/даунгрейда с prorated billing через Paddle API
• Кастомный Customer Portal: смена плана, отмена, обновление способа оплаты
• Документация по верификации подписей (ECDSA) и синхронизации с вашей БД
• Тестирование всех сценариев в sandbox и production
• Обучение вашей команды работе с Paddle Dashboard

Опыт и гарантии

Мы работаем с Paddle более 5 лет и успешно запустили более 80 SaaS-проектов на этой платформе. Гарантируем корректную обработку налогов и синхронизацию подписок с uptime 99.9%. После интеграции предоставляем две недели бесплатной поддержки.

Получите консультацию — оценим ваш проект за один день без обязательств. Закажите интеграцию Paddle для вашего SaaS.