Connect Stripe
This article shows you how to send your Stripe sales, renewals, refunds and disputes 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 ("event destination") in your Stripe account. Stripe signs each event with a signing secret; PlayerMagick checks the signature, so nobody else can send you fake sales.
PlayerMagick adds client_reference_id=… to your buttons' Stripe Payment Links (buy.stripe.com). Stripe sends it back with the payment, so the match is exact. Refunds and disputes are matched to their payment.
PlayerMagick never asks for your Stripe secret key.
Step 1: Connect Stripe in PlayerMagick
- Go to Settings → Sales platforms and click Connect a platform.
- Next to Stripe, click Connect, then Connect again.
- The setup page shows your receiver address. Copy it now: PlayerMagick shows it only once.
Step 2: Create the webhook in Stripe
- In your Stripe Dashboard, open Workbench → Webhooks and click Create an event destination.
- Choose Your account, payload style Snapshot, and keep the newest API version.
- Select these events: checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid, charge.refunded, charge.dispute.created, charge.dispute.closed and customer.subscription.deleted.
- Choose Webhook endpoint and paste the receiver address as the endpoint URL.
- Create the destination, click Reveal under Signing secret, and copy it (it starts with
whsec_).
Step 3: Save the signing secret in PlayerMagick
- On the setup page, paste it into Signing secret and click Save.
- Optional: create a restricted key in Stripe with Read access to Checkout Sessions and Invoices only, and paste it into Restricted key. It starts with
rk_. With it, the log shows product names, and refunds and disputes of subscription payments find their sale. Never paste a secret key (sk_): PlayerMagick refuses it.
Step 4: Check it works
- Click Send a test sale. The result says what a real sale would be matched to. Test sales never count.
- Events from Stripe's test mode show as tests and never count.
Keep the code on your checkout links
Point the player's buttons at your Stripe Payment Links (https://buy.stripe.com/…). PlayerMagick adds client_reference_id=… when the viewer clicks. If your link already has its own client_reference_id, PlayerMagick leaves it alone and adds pm=… instead (then sales are matched by email).
If you create Checkout Sessions with your own code, pass the pm code your page receives as client_reference_id (or as metadata.pm).
If you also sell through a cart that charges your Stripe account (and you connect that cart too), keep Count sales from this connection on for one of them only, or let PlayerMagick skip payments another connection already counted.
Troubleshooting
- Refused: the signature didn't match the saved secret. Copy the signing secret again from the event destination's page. Test mode and live mode have different secrets.
- Refused: too old. Your server clock or a long retry delay: Stripe signs each retry again, so the next one is accepted.
- Ignored: waiting for the payment. Bank payments confirm later; the sale counts when Stripe sends checkout.session.async_payment_succeeded.
- Order not found (it may arrive later). A refund or dispute arrived before its sale. PlayerMagick looks again for up to a day.
- A subscription refund shows "Order not found". Newer Stripe API versions don't name the payment on the subscription's invoice, so PlayerMagick needs the restricted key (with Invoices read access) to connect the refund to its sale. Add it; payments made afterwards are matched.