Connect Stripe - Trfyx Documentation

Stripe is the most popular payment provider for SaaS and online businesses. Connecting it to Trfyx takes about 2 minutes and gives you full revenue attribution, subscription tracking, and MRR metrics.

What you’ll need

A Stripe account with at least one product or price created
Admin or developer access to create API keys
The Trfyx tracker already installed on your website

Step-by-step setup

Create a restricted API key in Stripe

Go to your Stripe Dashboard → API Keys and click Create restricted key.Name it something like Trfyx so you can identify it later.Permissions needed: You only need read access. The pre-filled link in the Trfyx setup form selects the right permissions automatically. If you’re creating the key manually, enable:

Checkout Sessions: Read
Subscriptions: Read

Never use your Stripe secret key (sk_live_...). Always create a restricted key with minimal permissions. Trfyx only needs read access to verify webhooks.

Paste the key in Trfyx

In your Trfyx dashboard, open Integrations and select Stripe. Paste the restricted API key (it starts with rk_live_).Click Connect.

Trfyx creates the webhook automatically

You don’t need to set up the webhook manually. When you click Connect, Trfyx uses the Stripe API to create a webhook endpoint pointing to your site’s unique webhook URL.The webhook listens for these events:

checkout.session.completed — one-time purchases and initial subscription sign-ups
payment_intent.succeeded — direct payment intents
invoice.paid — subscription renewals
customer.subscription.created — new subscriptions
customer.subscription.updated — plan changes, trial endings
customer.subscription.deleted — cancellations
charge.refunded — refunds
charge.dispute.created — payment disputes opened
charge.dispute.closed — disputes resolved

Make a test purchase

If you have Stripe test mode enabled, create a test checkout. Within seconds, you should see the payment appear in Revenue → Overview.Check that:

The amount is correct
The match method shows (e.g., “explicit session” or “email fallback”)
The source attribution looks right (if you visited from a campaign link)

Improving Stripe attribution quality

For the best possible attribution, pass the Trfyx visitor ID when you create the Stripe Checkout session. The tracker stores it in the df_visitor_id cookie:

const visitorId = req.cookies.df_visitor_id; // set by the Trfyx tracker

const session = await stripe.checkout.sessions.create({
  // ... your normal checkout config
  client_reference_id: visitorId,
  metadata: { df_visitor_id: visitorId },
  // for subscriptions, so renewals carry it too:
  subscription_data: { metadata: { df_visitor_id: visitorId } },
});

This gives you Step 1 (explicit session) matching with high confidence, instead of relying on email fallback.

What Stripe data flows into Trfyx

Stripe event	What Trfyx records
Checkout completed	New payment + cascade attribution + customer identity
Invoice paid	Subscription renewal payment + MRR update
Subscription created/updated	Subscription state, plan name, billing interval, trial dates
Subscription deleted	Cancellation with reason, MRR drops to zero
Charge refunded	Refund recorded, original payment marked as refunded
Dispute created/closed	Dispute status tracked (open → won/lost)

Troubleshooting

Payments aren't showing up

Check your Stripe webhook logs at Developers → Webhooks in the Stripe Dashboard
Confirm the endpoint URL matches your Trfyx app URL
Make sure the webhook isn’t disabled
Verify your restricted key hasn’t been revoked

All payments show as 'unattributed'

This usually means the visitor ID isn’t reaching Stripe, or visitors are blocking the tracker. Try:

Passing the visitor ID when you create the checkout (see above)
Setting up a proxy to avoid ad blockers

Duplicate payments appearing

Trfyx deduplicates by Stripe event ID. If you’re seeing duplicates, you may have two webhook endpoints pointing to the same Trfyx site. Check Developers → Webhooks in Stripe and remove any extra endpoints.

Disconnecting Stripe

Open Integrations, select Stripe, and click Disconnect. This removes the webhook from Stripe and deletes the integration record. Historical revenue data is preserved.