Connect Paddle
This article shows you how to send your Paddle transactions, renewals, refunds and chargebacks to PlayerMagick, so each sale is matched to the play that sold it.
Available on: Pro, Business and Agency plans.
How it works
Paddle sends PlayerMagick a notification for each completed transaction, refund, chargeback and cancellation, signed with your notification destination's secret key. PlayerMagick checks the signature and its time, so nobody else can send you fake or replayed sales. Refunds count once Paddle approves them.
Paddle's checkout links have no place for PlayerMagick's code, and Paddle's notifications don't include the buyer's email. So sales are matched like this:
- Exactly, when your page opens Paddle Checkout with Paddle.js and passes PlayerMagick's code as
customData(see below). - By email otherwise, if you add a Paddle API key: PlayerMagick reads the buyer's email from Paddle and matches it to a viewer who gave the same email and watched in the 7 days before buying.
Paddle sells software. Check that your offer is allowed on Paddle before you build a funnel on it.
Step 1: Connect Paddle in PlayerMagick
- Go to Settings → Sales platforms and click Connect a platform.
- Next to Paddle, click Connect, then Connect again.
- The setup page shows your receiver address. Copy it now: PlayerMagick shows it only once.
Step 2: Create the notification destination in Paddle
- In your Paddle dashboard, open Events → Notifications and click New destination.
- Choose a webhook destination and paste the receiver address as its URL.
- Select transaction.completed, adjustment.created, adjustment.updated and subscription.canceled, then save.
Step 3: Save the secret key in PlayerMagick
- In Paddle, edit the destination again and copy its secret key (it starts with
pdl_ntfset_). - On the setup page, paste it into Secret key and click Save.
- Optional: create a Paddle API key that can read transactions and customers, and paste it into API key. Without it, sales without PlayerMagick's code can't be matched by email.
Step 4: Check it works
- Click Send a test sale on the setup page. The result says what a real sale would be matched to. Test sales never count.
- To try a purchase in Paddle's sandbox, connect it as a second Paddle connection with the sandbox destination's secret key and a sandbox API key (
pdl_sdbx_…): its sales show as tests and never count. A sandbox destination on your live connection would count its sales.
Pass PlayerMagick's code to Paddle.js
The player adds pm=… to the link of your buy button. On the page that opens, pass it to Paddle Checkout:
const pm = new URLSearchParams(location.search).get('pm');
Paddle.Checkout.open({ items: [{ priceId: 'pri_…', quantity: 1 }], customData: pm ? { pm } : undefined });
With Paddle's button attributes, set data-custom-data='{"pm":"…"}' on the button from the same value. Paddle copies the code to the subscription's renewals.
Troubleshooting
- Refused: the signature didn't match the saved secret. Copy the secret key again from the destination. Sandbox and live destinations have different keys.
- Refused: too old. Your notification arrived more than a minute late, usually a clock problem. Paddle retries, and each retry is signed again.
- Ignored: refund pending_approval. Paddle hasn't approved the refund yet. It counts when Paddle approves it.
- A sale shows as not matched. Your page doesn't pass
customData, and no API key is saved (or the buyer's email isn't one of your viewers').