Интеграция 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 остаётся для обратной совместимости, но мы помогаем с миграцией.
| Характеристика | Paddle Classic | Paddle Billing |
|---|---|---|
| Интерфейс | Overlay checkout | Checkout URL / inline iframe |
| Prorated billing | Через API | Встроено |
| Dynamic pricing | Ограниченно | Полноценно |
| API | Legacy | Modern REST |
| Рекомендация | Только legacy | Для новых проектов |
Более 80% наших проектов за последние годы мы запускаем на Paddle Billing — это стандарт для глобального SaaS.
Как мы интегрируем Paddle
Процесс занимает 3–5 рабочих дней — от sandbox до production. Включает 20+ протестированных сценариев.
| Этап | Что делаем | Результат |
|---|---|---|
| Аналитика | Изучаем модель подписок, валюты, налоги | Схема продуктов и цен в Paddle |
| Настройка | Создаём продукты, цены, триалы, webhook endpoints | Рабочая sandbox-конфигурация |
| Интеграция | Подключаем @paddle/paddle-js, backend для webhook |
Код в вашем репозитории |
| Тестирование | Проверяем весь цикл: триал → апгрейд → отмена → возврат | Чек-лист из 20+ сценариев |
| Деплой | Выходим в production, мониторинг через Paddle Dashboard | Uptime 99.9% |
Чтобы настроить Paddle:
- Создайте продукты в Dashboard с триалами и периодами.
- Настройте webhook endpoints для событий подписок.
- Интегрируйте
@paddle/paddle-jsна фронтенде. - Задокументируйте верификацию подписей.
- Протестируйте все сценарии в 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.