> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/how-to-track-purchase-events/stripe.md).

# Stripe Revenue Attribution

Connect Stripe once, then choose how Humblytics links each payment to the visit that led to it.

Setup has two parts: connect your Stripe account, then tell Humblytics which visit each payment came from.

## Step 1: Connect Stripe

1. In Humblytics, go to **Agent & data → Connectors**.
2. Under **Payments**, click **Connect** next to **Stripe**.
3. Paste a Stripe API key (see the next section).
4. Click **Test Connection**, then **Save Changes**.

<figure><img src="https://1281224403-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqZMBn2D7F1lV2hgGTS2X%2Fuploads%2Fgit-blob-b141461e98168ddfc0b020646bdfd327dabe078f%2Fstripe%20connection.gif?alt=media" alt="Connecting Stripe in Humblytics Connectors"><figcaption></figcaption></figure>

### Create a restricted key (recommended)

A restricted key gives Humblytics read-only access to exactly what it needs, and nothing more.

1. In Stripe, go to [**Developers → API keys**](https://dashboard.stripe.com/apikeys) and click **Create restricted key**.
2. Name it something like `Humblytics`.
3. Set **Read** access for **Payment Intents**, **Invoices**, **Subscriptions**, **Customers**, **Charges**, and **Account**.
4. Click **Create key** and copy it into Humblytics.

Restricted keys start with `rk_`. A full secret key (`sk_`) also works, but it gives more access than Humblytics needs. Humblytics reads your charges to attribute revenue and never stores card data.

## Step 2: Link payments to visits

Pick the method that matches how you take payments:

| You take payments with…                                                                         | Use                                                                                                               | Code needed?                          |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Stripe Payment Links                                                                            | [Stripe Payment Links](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-payment-links.md)   | No. Change one redirect URL.          |
| Your own checkout that calls the Stripe API (Checkout Sessions, Payment Intents, Subscriptions) | [Stripe API](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-api.md)                       | Yes. Pass one ID to Stripe.           |
| Stripe Elements, a third-party tool built on Stripe, or anything else                           | [Stripe (Other Methods)](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-other-methods.md) | Yes. One line with the buyer's email. |

Not sure which one you use? If your buy button links to `buy.stripe.com`, you use Payment Links.

## Step 3: Check that it works

Make a test purchase in a private window, then check **Observe → Attribution → Recent Attributed Transactions**. Humblytics reads new payments from Stripe on a schedule rather than through webhooks, so a payment typically appears within 20 minutes (new payments are picked up every 15 minutes and matched to visits every 5; subscriptions are synced hourly).

{% hint style="info" %}
**Revenue shows but isn't attributed?** The connection works, but the payment wasn't linked to a visit. Recheck Step 2 for your method.
{% endhint %}

## How a payment is matched

For each payment, Humblytics tries these in order and stops at the first match:

1. **`humblytics_view_id` metadata** on the Payment Intent, Invoice, Subscription, or Customer ([Stripe API](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-api.md)).
2. **`stripe_session_id`** read from the URL of the page the buyer returned to ([Payment Links](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-payment-links.md)).
3. **A saved subscription mapping**, so renewals of an attributed subscription are credited to the original visit.
4. **The customer's email**, if you passed it with `trackCustomer` during the visit ([Other Methods](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-other-methods.md)).

Payments that match none of these still count as revenue, but show up as unattributed.
