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

# Stripe

> Record Stripe payments, refunds, disputes, and subscriptions as revenue, with a restricted read-only key and a signed webhook.

The Stripe connection records your payments, refunds, disputes, and subscription changes as
[revenue](/features/revenue). Squasher reads the last 13 months of objects when you connect, then
records new events from a webhook. It uses a restricted key with read permissions only and does not
change anything in Stripe.

## Prerequisites

* A Stripe account, and permission to create restricted keys and webhook endpoints in it.
* Product analytics available for the project. See [Product analytics](/features/product-analytics).
* A Squasher API key with the `providers:write` permission, if you connect with the CLI or the API.
  See [API keys](/api-reference/api-keys).

## Create a restricted key

1. In the Stripe Dashboard, open **Developers**, then **API keys**, and create a restricted key.
2. Give the key **Read** access to these resources. Leave every other resource at **None**.

| Resource | What Squasher reads |
| - | - |
| Charges | Payments |
| Refunds | Refunds |
| Disputes | Dispute withdrawals and reversals |
| Invoices | The plan and subscription of a payment, renewals |
| Subscriptions | Subscription states for MRR |
| Customers | The user id in customer metadata |
| Checkout Sessions | The user id of a checkout (`client_reference_id`) |

3. Copy the key. It starts with `rk_live_` (or `rk_test_` in test mode). Squasher refuses secret
   keys (`sk_`), because it only reads.

## Connect Stripe

<Tabs>
  <Tab title="CLI">
    The CLI reads the key from the `STRIPE_RESTRICTED_KEY` environment variable or from stdin. It has
    no flag for the key, so the key does not stay in your shell history.

    ```bash theme={null}
    read -rs STRIPE_RESTRICTED_KEY && export STRIPE_RESTRICTED_KEY
    squasher integrations connect-stripe --project "$SQUASHER_PROJECT_ID"
    ```

    The command prints the webhook URL and the event types to select.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/provider-connections/stripe" \
      -H "x-squasher-key: $SQUASHER_ADMIN_KEY" \
      -H "Content-Type: application/json" \
      -d "{\"restricted_key\": \"$STRIPE_RESTRICTED_KEY\"}"
    ```

    The response has `webhook_url` and `webhook_events`.
  </Tab>
</Tabs>

Squasher checks the key against Stripe before it saves it, and then starts to read past objects.
A live key records only live events, and a test key records only test events.

## Add the webhook endpoint

1. In the Stripe Dashboard, open **Developers**, then **Webhooks**, and add an endpoint.
2. Paste the webhook URL from the connect step. Use API version `2024-06-20` or earlier for the
   endpoint, so invoice events include the paying charge.
3. Select these events:
   `charge.succeeded`, `charge.captured`, `charge.updated`, `charge.refunded`,
   `charge.refund.updated`, `refund.created`, `refund.updated`, `charge.dispute.funds_withdrawn`,
   `charge.dispute.funds_reinstated`, `invoice.paid`, `customer.subscription.created`,
   `customer.subscription.updated`, `customer.subscription.deleted`,
   `customer.subscription.paused`, `customer.subscription.resumed`,
   `checkout.session.completed`, `customer.created`, and `customer.updated`.
4. Copy the signing secret of the endpoint (it starts with `whsec_`) and save it in Squasher:

```bash theme={null}
squasher integrations stripe-webhook-secret --project "$SQUASHER_PROJECT_ID"
```

The command reads the secret from stdin. Squasher accepts only events signed with this secret and
less than 5 minutes old, and it records each Stripe event id once.

## Check the connection

```bash theme={null}
squasher revenue status --project "$SQUASHER_PROJECT_ID"
```

The check shows when the last webhook event arrived and whether Squasher has read the past
payments. Squasher also re-reads the last 3 days every 15 minutes, so a missed webhook delivery is
recorded later.

## Disconnect Stripe

```bash theme={null}
curl -X DELETE "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/provider-connections/stripe" \
  -H "x-squasher-key: $SQUASHER_ADMIN_KEY"
```

Squasher deletes the stored key and signing secret. Recorded revenue stays. Delete the webhook
endpoint and the restricted key in the Stripe Dashboard too.

## Next steps

<CardGroup cols={2}>
  <Card title="Revenue" icon="https://mintcdn.com/nextbigthingllc/Fg5aclMlZNSrg_Y3/icons/nav/billing.svg?fit=max&auto=format&n=Fg5aclMlZNSrg_Y3&q=85&s=3034807373e9c3cabf948c2bbd7a9021" href="/features/revenue" width="24" height="24" data-path="icons/nav/billing.svg">
    How Squasher counts revenue and MRR, and how revenue links to people.
  </Card>

  <Card title="Revenue API" icon="https://mintcdn.com/nextbigthingllc/Fg5aclMlZNSrg_Y3/icons/docs/api.svg?fit=max&auto=format&n=Fg5aclMlZNSrg_Y3&q=85&s=ad72f5da1d92bd1c152340d2b13ad254" href="/api-reference/revenue" width="24" height="24" data-path="icons/docs/api.svg">
    Read revenue and MRR from your own tools.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.