# Connecting Stripe

Stripe gives Scout the revenue side of your funnel: payments, subscriptions,
checkouts, refunds, and disputes. Together with web tracking it shows which
visitors actually became paying customers.

## What it unlocks

- Counts of successful and failed payments, checkout sessions and checkout
  failures, refunds, and disputes.
- Subscription lifecycle: new, updated, paused, resumed, and canceled
  subscriptions, trials ending, and active subscribers.
- Privacy-safe snapshots of customers, subscriptions, products, prices, and
  invoices for pricing and commerce analysis.
- Optional recurring revenue KPIs (MRR, ARR, invoice revenue) and optional
  exact per-transaction amounts, both off by default.

By default TractionScout stores counts, allowlisted resource state,
project-scoped pseudonyms, and coarse value tiers. It does not store names,
email addresses, payment methods, addresses, or raw metadata.

## What access is requested

Stripe uses an API key, not OAuth. Create a **restricted key** in the Stripe
Dashboard with read access to the resources TractionScout reads: events,
customers, subscriptions, invoices, refunds, disputes, products, prices, and
your account details. No write permission is needed; Scout never charges,
refunds, or edits anything in Stripe.

Optionally create a **webhook endpoint** in Stripe and store its signing
secret (`whsec_...`) so TractionScout can accept signed events between syncs.

## Prerequisites

- Access to the Stripe account you want to analyze, with permission to
  create restricted keys and webhook endpoints.
- Permission to manage credentials in the TractionScout project.

Stripe is a non-OAuth source and is available during the alpha.

## Steps

1. In the Stripe Dashboard create a restricted API key with read access
   to the resources listed above and copy it.
2. In TractionScout open **Configure → Data Sources**, choose **Stripe**,
   and select the **Restricted key** connect option.
3. Paste the key into **Restricted key**. It is stored by reference and is
   never shown again.
4. Review the collection switches. Payment, subscription, checkout, value
   tier, resource snapshot, customer snapshot, and product catalog
   collection are on by default; **Collect MRR, ARR, and revenue KPIs** and
   **Collect exact payment, refund, and dispute amounts** are separate
   opt-ins. Set the revenue currency if you enable them.
5. Save the connection and run the first sync.
6. Optional: in Stripe create a webhook endpoint pointing at
   `/api/v4/tractionscout/projects/{project_id}/integrations/{integration_id}/stripe/events`
   on your TractionScout host, using the project and integration IDs of
   this connection, then paste the endpoint's signing secret into
   **Webhook signing secret**.

## After the first sync

The first sync backfills events and resource snapshots through the Stripe
API and reports how many metric snapshots were written. Later syncs run on
the configured interval (default 60 minutes) and resume from the last
cursor. Signed webhook events arrive between syncs when you configured the
endpoint.

Scout can then relate payment and subscription activity to the same period
as your web traffic and experiments, and flag failed payments, rising
refunds, or open disputes.

## Common questions

**Can I use a standard secret key?** Use a restricted read-only key. A full
secret key grants far more than TractionScout needs.

**Will exact revenue appear?** Only if you enable the revenue KPI or exact
amount opt-ins. Otherwise you see counts and coarse tiers. Unsupported
discounts, tax-inclusive prices, trial offers, or usage pricing make the
revenue KPIs report as unavailable rather than guessing.

**Does test mode work?** Use a key from the mode whose data you want to
analyze; a test-mode key returns test data.

**The connection shows "Needs attention".** The last sync step failed,
for example because the key was revoked or lost a permission. Read the
error shown on the connection, fix the key in Stripe, and sync again.

## Disconnecting

Open the connection in **Data Sources** and select **Remove connection**.
The stored key and signing secret are deleted with the integration and syncs
stop; imported evidence stays in the project. Also delete the restricted key
and the webhook endpoint in the Stripe Dashboard so nothing can use them.

Related: [Connecting your data sources](/docs/integrations.html) and
[Installing web tracking](/docs/install-tracking.html).