Інтеграція 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.