Paddle Integration Guide

Paddle acts as a Merchant of Record, handling global taxes and compliance for SaaS businesses. We integrate with Paddle Billing (v2).

1. Creating a Paddle Webhook

1. Log in to your Paddle Dashboard.
2. Go to Developer Tools > Webhooks.
3. Click New Webhook.
4. Enter the Discover Mac Apps Webhook URL provided in your dashboard.

2. Selecting Events

We recommend subscribing to the following Paddle events to ensure accurate commission calculations:

• transaction.completed (Primary event for successful payments)
• subscription.created
• subscription.updated (Used to track recurring subscription renewals)

3. Webhook Secret Key

Once the webhook is created, Paddle will generate a Secret Key for that specific endpoint. Copy this secret key and paste it into your Discover Mac Apps dashboard. This is required; we will reject any webhooks that do not have a valid Paddle signature.

4. Passing Custom Data

To ensure the affiliate gets credited, you must pass the affiliate ID into Paddle's custom data. When you open Paddle Checkout (using Paddle.js), pass the value of the dma_aff_ref cookie in the customData object:

// Example using Paddle.js
Paddle.Checkout.open({
  items: [{ priceId: 'pri_123', quantity: 1 }],
  customData: {
    // This key must match exactly so we can read it
    ref: getCookie('dma_aff_ref') 
  }
});