Connect PayPal
This article shows you how to send the payments, subscriptions, refunds and disputes of your PayPal checkout to PlayerMagick, so each sale is matched to the play that sold it.
Available on: Pro, Business and Agency plans.
How it works
You add PlayerMagick's address as a webhook of the PayPal app ("REST app") your checkout uses. For each notification, PlayerMagick asks PayPal whether it is genuine, using your app's Client ID and Secret. PayPal sends events only for payments made through that app.
PayPal's payment links and buttons have no place for PlayerMagick's code. So sales are matched like this:
- Exactly, when your own checkout code creates the PayPal order and passes PlayerMagick's code as
custom_id(see below). - By email otherwise: PlayerMagick reads the buyer's PayPal email from the order and matches it to a viewer who gave the same email and watched in the 7 days before buying.
If you sell through a cart (SamCart, ThriveCart, …) that uses its own PayPal connection, connect the cart instead: your PayPal app won't see those payments.
Before you start
- You need a PayPal business account and a REST app on developer.paypal.com (Live). If your checkout is built by a developer, ask them which app it uses.
Step 1: Copy the app's credentials
- On developer.paypal.com, sign in with your PayPal business account and open the REST app your checkout uses (Apps & Credentials, Live).
- Copy the app's Client ID and Secret.
Step 2: Connect PayPal in PlayerMagick
- Go to Settings → Sales platforms and click Connect a platform.
- Next to PayPal, click Connect, paste the Client ID and Secret, and click Connect.
- The setup page shows your receiver address. Copy it now: PlayerMagick shows it only once.
Step 3: Add the webhook in your PayPal app
- In the app's webhooks section, add a webhook with the receiver address.
- Select these events: PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, PAYMENT.SALE.COMPLETED, BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, CUSTOMER.DISPUTE.CREATED and CUSTOMER.DISPUTE.RESOLVED.
- Save it, copy its Webhook ID, paste it into Webhook ID on the setup page and click Save.
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.
- Payments made with a sandbox app show as tests and never count.
- PayPal's webhook simulator sends sample events PayPal itself can't confirm, so PlayerMagick refuses them. Use Send a test sale or a sandbox payment instead.
Pass PlayerMagick's code from your checkout code
The player adds pm=… to the link of your buy button. On the page that opens, read it and pass it to PayPal:
- Orders (Smart Buttons):
purchase_units: [{ custom_id: pm, amount: {…} }]when you create the order. - Subscriptions:
custom_id: pmwhen you create the subscription.
custom_id can also hold your own reference: add the code as pm=… inside it, for example order-77;pm=….
Troubleshooting
- Refused: the signature didn't match the saved secret. PayPal said the notification isn't genuine for these credentials. Check that the Client ID, Secret and Webhook ID all come from the same app, and that the app is the Live one (or the sandbox one for tests).
- Waiting for the first notification. PayPal sends events only for payments through this app. If your checkout uses another app, or a cart's PayPal connection, connect that instead.
- A sale shows as not matched. Your checkout code doesn't pass
custom_id, and the buyer's PayPal email isn't one of your viewers' emails. - A subscription's first payment also shows as a renewal. PayPal reports the sign-up and its first payment separately. Only the sign-up counts as a sale; renewals never count as new sales.
- Order not found (it may arrive later). A refund or dispute arrived before its payment. PlayerMagick looks again for up to a day.