Paddle Integration for SaaS Subscriptions: Full Setup

Paddle Integration for SaaS Subscriptions

One of our clients lost $12,000 in a quarter due to incorrect VAT calculation across three countries. After integrating Paddle as Merchant of Record, tax errors disappeared and conversion increased by 18% thanks to dynamic pricing. Paddle takes legal responsibility for taxes and compliance in over 200 countries, but integration requires deep understanding of the API and business logic. We configure Paddle for your product — from creating a pricing scheme to syncing subscriptions in your database.

Paddle Billing vs Classic: Which to Choose for a New Project?

Paddle Classic uses an overlay checkout — a JavaScript widget embedded on the page. Paddle Billing offers its own checkout URL or inline iframe, and supports prorated billing out of the box — when changing a plan, the amount recalculates automatically. For new projects, we recommend Billing: it is actively developed, has a modern REST API, and dynamic pricing. Classic remains for backward compatibility, but we can help with migration.

Over 80% of our projects in recent years we launch on Paddle Billing — it's the standard for global SaaS.

How We Integrate Paddle

The process takes 3–5 business days — from sandbox to production. Includes testing of 20+ scenarios.

To set up Paddle:

1. Create products in Dashboard with trials and billing periods.
2. Configure webhook endpoints for subscription events.
3. Integrate @paddle/paddle-js on the frontend.
4. Document signature verification.
5. Test all scenarios in sandbox.

Why Paddle Billing Is Better Than Classic for New Projects?

Billing provides prorated billing out of the box — when upgrading a plan, the amount recalculates automatically. Classic requires manual calculation via API. Billing also supports dynamic pricing: one product displays in different currencies, which is critical for global SaaS. According to our data, conversion increases by 15–20% when showing prices in local currency. Additionally, Paddle Billing offers more flexible webhook events and supports transaction.completed for payment confirmation.

Customer Portal: Custom Implementation

Unlike Stripe, Paddle does not provide a ready-made portal for subscription management. We implement it via API: plan changes, cancellation, payment method updates — all from your interface. For redirecting to update a card, we use the getPaymentMethodUpdateTransaction method. Cancellation is performed with the parameter effective_from: 'next_billing_period'.

How Does Paddle Handle Refunds and Chargebacks?

Paddle fully manages the refund and dispute process. They handle communication with payment systems and banks, while you receive a notification via the transaction.updated webhook with type refund. This approach saves your support team's time.

Technical Details: Webhooks and Synchronization

For webhook verification, we use the paddle/webhooks library for PHP (also available for Node.js, Python). Each event is verified via ECDSA signature — this is a mandatory security requirement. We pass custom_data with user_id to uniquely link the subscription to a user in your system.

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'], ]); } 

What Is Included in Turnkey Work

• Creation of product and price structure (with trials, billing periods, taxes)
• Integration of @paddle/paddle-js on the frontend with callback handling
• Backend processing of webhook events: subscription.created, updated, cancelled, transaction.completed
• Implementation of upgrade/downgrade with prorated billing via Paddle API
• Custom Customer Portal: plan change, cancellation, payment method update
• Documentation on signature verification (ECDSA) and synchronization with your database
• Testing all scenarios in sandbox and production
• Training your team on Paddle Dashboard

Experience and Guarantees

We have been working with Paddle for over 5 years and have successfully launched 80+ SaaS projects on this platform. We guarantee correct tax handling and subscription synchronization with 99.9% uptime. After integration, we provide two weeks of free support.

Get a consultation – we'll evaluate your project in one day with no obligation. Order Paddle integration for your SaaS.