Connect Stripe
Connect Stripe to FounderHQ.
Connect Stripe so FounderHQ records every payment, refund, dispute, and subscription change. Two of the three ways need nothing configured in Stripe. About 2 minutes.
Before you start
You need a FounderHQ brand with the Events SDK installed on your site, and a Stripe account you can open the dashboard for.
Which should I choose?
| Mode | Choose it when | Your revenue appears |
|---|---|---|
| Connect with Stripe | It is offered. This is the fastest way. | In seconds |
| Paste a read-only key | You prefer not to authorize FounderHQ | Within a few minutes |
| Webhook | You want to configure every event yourself | In seconds |
FounderHQ marks one mode Recommended: Connect with Stripe when it is offered, and the read-only key when it is not.
FounderHQ tracks live payments only. It refuses test keys and test events.
Connect with Stripe (one click)
- In FounderHQ, open Settings → Revenue and choose the brand.
- Choose Stripe, then Connect with Stripe.
- Approve access on Stripe's page.
You come back to FounderHQ with Stripe connected. You can revoke FounderHQ from your Stripe dashboard anytime.
Paste a read-only key
- In FounderHQ, open Settings → Revenue and choose the brand.
- Choose Stripe, then Paste a read-only key.
- Open Stripe API keys in live mode. Create a restricted key with Read access to Account and Events. Leave every other permission at None.
- Paste the key, which starts with
rk_live_, into Stripe read-only key and press Connect Stripe.
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)
Create the connection in FounderHQ
In FounderHQ, open Settings → Revenue and choose the brand. Choose Stripe, then Webhook.
Enter your Stripe account ID. It starts with acct_ and Stripe shows it
in your dashboard. FounderHQ rejects events from any other account.
Press Get webhook address. FounderHQ gives you a webhook URL:
https://app.getfounderhq.com/api/hooks/payments/stripe/CONNECTION_IDAdd 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.
Create the endpoint in live mode. FounderHQ refuses test events.
Select the events FounderHQ reads
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.succeededFounderHQ ignores any other event type. charge.succeeded matters only if you
still create legacy Charges.
Paste the signing secret back
Copy the endpoint's signing secret from Stripe. It starts with whsec_. Paste
it into Signing secret and press Save signing secret. The connection
then shows Waiting for test.
Send a test event
Send one of the selected events from Stripe. FounderHQ verifies the signature, the API version, and the account ID. An event you did not select does not count.
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 |
| Checkout Sessions you create on your server | Stripe Checkout API |
| Your own payment form on PaymentIntents | Stripe PaymentIntent 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."
The endpoint is in Stripe's test mode. FounderHQ tracks live payments only. Create the endpoint in live mode.
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.