> ## Documentation Index
> Fetch the complete documentation index at: https://help.trfyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Stripe

> Step-by-step guide to connecting Stripe for revenue attribution in Trfyx.

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

**1. Create a restricted API key in Stripe**

Go to your [Stripe Dashboard → API Keys](https://dashboard.stripe.com/apikeys) 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**

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

**2. 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**.

**3. 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

**4. 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:

```javascript theme={"system"}
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

> [accordion] Payments aren't showing up
>
> 1. Check your Stripe webhook logs at **Developers → Webhooks** in the Stripe Dashboard
> 2. Confirm the endpoint URL matches your Trfyx app URL
> 3. Make sure the webhook isn't disabled
> 4. Verify your restricted key hasn't been revoked

> [accordion] 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](https://help.trfyx.com/proxy-guide.md) to avoid ad blockers

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.