Paddle Integration

Paddle is a merchant of record platform that handles payments, tax, and compliance for SaaS and digital product businesses. Because Paddle acts as the reseller, the integration model differs from traditional payment processors: LostChurn receives subscription lifecycle events from Paddle rather than raw charge-level events.

Prerequisites

• An active Paddle account (Classic or Paddle Billing)
• Access to the Paddle Dashboard with admin or developer permissions
• A Paddle API key generated from the Developer Tools section
• A LostChurn account with at least one workspace created

Connection Steps

1. In the Paddle Dashboard, navigate to Developer Tools > Authentication.
2. Click Generate API Key. Name the key LostChurn and grant it Read and Write permissions for subscriptions and transactions.
3. Copy the API key immediately (it is shown only once).
4. In your LostChurn dashboard, go to Settings > Integrations and click Connect Paddle.
5. Select your Paddle environment: Sandbox or Production.
6. Paste the API key and click Save and Verify. LostChurn will make a test API call to confirm the key is valid.

Webhook Configuration

1. In the Paddle Dashboard, go to Developer Tools > Notifications.
2. Click New Destination.
3. Set the URL to:

   https://webhooks.lostchurn.com/v1/paddle

4. Set the Type to Webhook (HTTP POST).
5. Select the following event types:
   • transaction.payment_failed
   • transaction.completed
   • transaction.updated
   • subscription.canceled
   • subscription.updated
   • subscription.past_due
   • subscription.paused
   • subscription.resumed
   • subscription.activated
6. Click Save Destination.
7. Copy the Secret Key shown on the notification destination detail page.
8. In your LostChurn dashboard, paste the secret key into the Webhook Secret field on the Paddle integration page.

Webhook Signature Verification

Paddle signs every webhook payload with HMAC-SHA256. The signature is sent in the Paddle-Signature header using the format:

ts=1234567890;h1=hex_encoded_hmac_signature

LostChurn verifies authenticity by:

1. Parsing the ts (timestamp) and h1 (signature) values from the header.
2. Checking that the timestamp is within a 5-minute tolerance window (replay protection).
3. Computing HMAC-SHA256 of ${ts}:${raw_body} using the webhook secret.
4. Comparing the result against h1 using a timing-safe comparison.

Requests with missing, expired, or invalid signatures are rejected with a 401 response.

Verify Connection

1. In the Paddle Dashboard, go to Developer Tools > Notifications and select the LostChurn destination.
2. Click Send Test Notification and choose transaction.payment_failed.
3. In your LostChurn dashboard, navigate to Events and confirm that the test event appears.
4. Alternatively, create a test subscription in Paddle Sandbox using one of Paddle's test payment methods and simulate a failed payment.

A successful connection shows a green Connected badge on the Paddle card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Merchant of Record Model

Because Paddle is the merchant of record, retry behavior works differently than with direct processors. Paddle handles the initial retry logic itself. LostChurn complements this by:

• Monitoring Paddle's retry outcomes and triggering dunning emails when Paddle's built-in retries are exhausted.
• Providing a customer-facing payment update page when Paddle's payment method update flow is insufficient.
• Tracking recovery attribution so you can see which recoveries came from Paddle's native retries versus LostChurn's dunning.

Paddle Classic vs. Paddle Billing

LostChurn supports both Paddle Classic (legacy) and Paddle Billing (the current platform). Event formats differ between the two:

• Paddle Billing: Uses the event types listed above. This is the recommended integration.
• Paddle Classic: Uses older webhook formats such as subscription_payment_failed and subscription_cancelled. LostChurn auto-detects the format based on your account type.

If you are migrating from Paddle Classic to Paddle Billing, you can connect both simultaneously during the transition period. LostChurn deduplicates events that appear in both systems.

Sandbox Environment

Paddle provides a fully isolated sandbox environment at sandbox-vendors.paddle.com. Use sandbox credentials to test the integration without affecting live subscriptions. LostChurn labels all sandbox events with a sandbox badge in the Events feed.

Tax and Compliance

Since Paddle handles tax collection and compliance as the merchant of record, LostChurn's recovery metrics exclude tax amounts by default. You can toggle this in Settings > Integrations > Paddle > Revenue Display to include or exclude tax in your recovery dashboards.

Rate Limits

Paddle enforces rate limits of 20 requests per second for most API endpoints. LostChurn distributes retry-related API calls across time windows to stay within this limit. If you experience rate limiting, LostChurn automatically backs off and retries with exponential delay.