# Connect Stripe (https://www.getfounderhq.com/docs/analytics/revenue/connect-stripe)

Connect Stripe so FounderHQ records every payment, refund, dispute, and
subscription change. The recommended path is a read-only key — there is
nothing to configure in Stripe.

<Callout title="Before you start">
  You need a [FounderHQ brand](/analytics/getting-started) with the Events SDK
  installed on your site, and a Stripe account you can open the dashboard for.
</Callout>

## Which should I choose?

| Mode                      | Choose it when                             | Your revenue appears |
| ------------------------- | ------------------------------------------ | -------------------- |
| **Paste a read-only key** | You want the simplest setup                | Within a few minutes |
| **Webhook**               | You want to configure every event yourself | In seconds           |
| **Connect with Stripe**   | Shown when one-click connect is available  | In seconds           |

## Paste a read-only key (recommended)

1. In FounderHQ, open **Settings → Integrations → Revenue**.
2. Choose Stripe and the brand. Select **Paste a read-only
   key**.
3. Open [Stripe API keys](https://dashboard.stripe.com/apikeys). Create a
   restricted key with **Read** access to **Account** and **Events**. Leave
   every other permission at **None**.
4. Copy the `rk_` value into FounderHQ and connect.

There is no webhook to configure in Stripe. Your revenue appears within a few
minutes. When you first connect, FounderHQ can see about the last 30 days.

FounderHQ encrypts the key. You can revoke it from Stripe anytime. FounderHQ
refuses unrestricted `sk_` keys.

## Webhook (manual)

### 1. Create the connection in FounderHQ

In FounderHQ, open **Settings → Integrations → Revenue**. Choose Stripe, the
brand. Select **Webhook**.

Enter your Stripe account ID. It starts with `acct_` and Stripe shows it in
your dashboard. FounderHQ rejects events from any other account.

FounderHQ then gives you a webhook URL:

```text
https://app.getfounderhq.com/api/hooks/payments/stripe/CONNECTION_ID
```

### 2. Add the endpoint in Stripe

In Stripe, open Developers and add a webhook endpoint with that URL.

Set the endpoint API version to `2025-05-28.basil` or later. FounderHQ refuses
older versions, because the `invoice_payment.paid` event does not exist before
that version.

Keep the environment matched. A live endpoint must belong to a live FounderHQ
connection, and a test endpoint to a test connection.

### 3. Select the events FounderHQ reads

```text
checkout.session.completed
payment_intent.succeeded
invoice.created
invoice.sent
invoice.upcoming
invoice.updated
invoice.finalized
invoice.finalization_failed
invoice.paid
invoice.payment_succeeded
invoice.payment_failed
invoice.payment_action_required
invoice.overdue
invoice.overpaid
invoice.marked_uncollectible
invoice.voided
invoice.will_be_due
invoice.deleted
invoice_payment.paid
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
refund.created
refund.updated
refund.failed
charge.refunded
charge.dispute.created
charge.dispute.closed
credit_note.created
credit_note.updated
credit_note.voided
charge.succeeded
```

FounderHQ ignores any other event type. `charge.succeeded` matters only if you
still create legacy Charges.

### 4. Paste the signing secret back

Copy the endpoint's signing secret from Stripe. It starts with `whsec_`. Paste
it into the FounderHQ connection.

### 5. Send a test event

Send any selected event from Stripe. FounderHQ verifies the signature, the API
version, the environment, and the account ID.

### 6. Attach attribution to your checkout

A connected webhook tells FounderHQ that money moved. It does not tell
FounderHQ who to thank. Pick the one page that matches how you charge:

| How you charge                                | Page                                                                             |
| --------------------------------------------- | -------------------------------------------------------------------------------- |
| Stripe-hosted Payment Links or Pricing Tables | [Stripe Payment Links](/analytics/revenue/connect-stripe/payment-links)          |
| Checkout Sessions you create on your server   | [Stripe Checkout API](/analytics/revenue/connect-stripe/checkout-api)            |
| Your own payment form on PaymentIntents       | [Stripe PaymentIntent API](/analytics/revenue/connect-stripe/payment-intent-api) |

### Verify

After the first verified event, the connection shows **Connected** in
FounderHQ. Stripe shows a `200` response for the delivery.

### Troubleshoot

#### Stripe shows "This Stripe endpoint uses an older API version."

The endpoint sends an API version before `2025-05-28.basil`. Edit the endpoint
in Stripe and raise the version.

#### Stripe shows "Invalid signature"

The pasted secret is wrong, or you rolled the secret in Stripe. Copy the
current signing secret and paste it again.

#### Stripe shows "This endpoint only accepts live events."

A test endpoint points at a live connection, or the reverse. Create the
connection in the environment that matches the endpoint.

#### Stripe shows "This event belongs to another Stripe account."

The account ID on the connection does not match the account that sent the
event. Fix the `acct_` value.

## Connect with Stripe (one click)

When your Payments settings show a **Connect with Stripe** option, it is the
fastest path: click it, approve access on Stripe's page, and your revenue
appears in seconds. You can revoke FounderHQ from your Stripe dashboard
anytime. If you don't see this option, use a read-only key above — the data
FounderHQ records is identical.