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

# Connect Stripe

> Pull your Stripe charges with a read-only restricted key and attribute every sale to the channel that earned it.

Connecting Stripe is what turns clicks into attributed revenue. TrackRev uses a **read-only
restricted API key** — no OAuth, no Stripe Connect, no access to move money. It pulls your
succeeded charges on a schedule and joins each one to the visitor who bought.

<Info>
  **TrackRev can never touch your money.** The key it asks for grants read access to charges,
  checkout sessions, customers and payment intents only. You can revoke it any time from your
  Stripe dashboard.
</Info>

## Connect it

<Steps>
  <Step title="Open Integrations → Connect your revenue provider">
    Go to **Configuration → Integrations** (`/settings/integrations`) and find section
    **"2 · Connect your revenue provider"**. Choose **Stripe**.
  </Step>

  <Step title="Create the restricted key">
    Click the **Quick connect** link. It opens Stripe's *Create restricted key* screen with the
    right read scopes pre-selected:

    * `rak_charge_read`
    * `rak_checkout_session_read`
    * `rak_customer_read`
    * `rak_payment_intent_read`
    * `rak_webhook_write` *(optional — enables instant sync, see below)*

    Name it (e.g. *TrackRev*), create it, and copy the key. It starts with `rk_live_` (or
    `rk_test_` for test mode — both work).
  </Step>

  <Step title="Paste and save">
    Paste the `rk_…` key into TrackRev and save. TrackRev validates it with a single read call
    before storing it. Done — the first sync begins shortly.
  </Step>
</Steps>

## What gets pulled, and when

* TrackRev pulls **succeeded charges** — up to the last **30 days** on the first sync, then only
  new charges after that using a cursor.
* The scheduled sync runs **hourly** by default. You can also click **Sync now** on the
  connected provider at any time.
* Subscription **renewals** are ingested too and inherit the original sale's channel, so
  lifetime value reflects true retained revenue.

## Instant sync (recommended)

If you include the `rak_webhook_write` scope on the key, TrackRev automatically registers a
read-only webhook on your Stripe account (for `charge.succeeded`, `charge.refunded` and
`checkout.session.completed`). New sales then attribute within seconds instead of waiting for
the hourly pull. Without that scope, everything still works — you're just on the hourly cron.

## How a charge joins back to the click

TrackRev resolves the visitor for each charge in this order:

<Steps>
  <Step title="Charge metadata">
    `charge.metadata.vid`, if you set it on the PaymentIntent.
  </Step>

  <Step title="Checkout session reference">
    The Checkout Session's `client_reference_id`.
  </Step>

  <Step title="Checkout session metadata">
    The Checkout Session's `metadata.vid`.
  </Step>

  <Step title="Email fallback">
    If none of the above are present, TrackRev matches on the customer's **email** (attached to a
    visitor via [`identify()`](/getting-started/install-pixel#the-window-trk-api)).
  </Step>
</Steps>

<Warning>
  Email matching is a safety net, not a substitute. For exact click-to-purchase attribution,
  always pass the visitor id at checkout — it's one line. See
  [Pass the visitor id to checkout](/revenue-attribution/pass-vid-to-checkout).
</Warning>

## Verify your setup

On the Integrations page, use **Verify your checkout setup → Check attribution setup**. TrackRev
inspects your recent checkouts and reports one of:

| Result            | Meaning                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------- |
| **OK**            | A visitor id is present and matches a tracked visitor.                                  |
| **vid unmatched** | A `vid` is present but unknown — is the pixel running on the page checkout starts from? |
| **no vid**        | Checkouts exist but none carry a `vid`. Add it at checkout.                             |
| **no charges**    | Nothing recent — make a test purchase.                                                  |
| **error**         | Stripe rejected the key (revoked or missing a scope).                                   |

<Card title="Next: pass the visitor id" icon="arrow-right" href="/revenue-attribution/pass-vid-to-checkout">
  The one line that makes attribution exact.
</Card>