# Connect Stripe

Paste your Stripe keys into BuildBase, let it create the webhook endpoint Stripe sends payments to, and turn on Stripe Tax if you collect tax.

BuildBase takes payments through your own Stripe account. You give it two keys from Stripe, and Stripe sends BuildBase what happens to each payment through a webhook endpoint, which BuildBase can create for you. Until the keys are saved, nothing else in billing is offered: plans, products and pricing groups appear once Stripe is connected.

> **Note:**

- A Stripe account. Use **test mode** while you set up: checkouts take Stripe's test cards and no money moves.
- A console role that can create and update the Stripe credentials.
- Inside a non-production environment, test keys only: a live key is refused there.

## What goes where

| Value                  | Where you get it                                 | Where it goes                                                        |
| ---------------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| Publishable key        | Stripe, **Developers > API keys**, `pk_test_...` | BuildBase, **Public key (publishable key)**                          |
| Secret key             | Stripe, the same page, `sk_test_...`             | BuildBase, **Private key (secret key)**                              |
| Webhook URL            | BuildBase, card **Webhook configuration**        | Stripe, the endpoint's URL (only when you make the endpoint by hand) |
| Webhook signing secret | Stripe, the endpoint you made, `whsec_...`       | BuildBase, **Webhook signing secret** (only by hand)                 |

## 1. Copy your keys from Stripe

In Stripe, switch on **test mode** and open **Developers > API keys** ([the API keys page](https://dashboard.stripe.com/test/apikeys)). Copy the **Publishable key**, then reveal and copy the **Secret key**. The secret key lets anyone act on your Stripe account: keep it out of code, chats and screenshots.

## 2. Open Billing in the console

[Open Billing in the console](https://console.buildbase.app/dashboard/admin/payment/credentials)

In the console's left rail, press **Billing**. Until a secret key is saved, it opens straight onto **Stripe payment setup**, with no menu beside it: there is nothing else to show yet.

![The console with Billing, ringed in the left rail, open on Stripe payment setup: what Stripe is, How to get your Stripe keys in five steps, the Public key (publishable key) and Private key (secret key) boxes, and Save credentials](/images/billing-setup/connect-stripe/console-billing-menu-before.webp)

## 3. Paste both keys and save

Paste the publishable key into **Public key (publishable key)** and the secret key into **Private key (secret key)**, then press **Save credentials**.

![Stripe payment setup with an example publishable key and a secret key hidden as dots, both boxes ringed, and Save credentials ringed](/images/billing-setup/connect-stripe/console-credentials-form.webp)

## 4. The Billing menu

Once the keys are saved, **Billing** has its menu: **Subscriptions**, **Revenue**, **Billing health**, **Plans**, **Pricing groups**, **Products**, **Product categories**, **Coupons**, **Add-ons** and **Grants**, then **Credit packages** and **Credit ledger** under **Credits**, and **Payment webhooks** and **Credentials** under **Configuration**.

![The Billing menu after the keys are saved, with Plans ringed among Subscriptions, Revenue, Billing health, Pricing groups, Products, Product categories, Coupons, Add-ons and Grants, then Credits and Configuration](/images/billing-setup/connect-stripe/console-billing-menu-after.webp)

## The webhook endpoint

Stripe tells BuildBase about every checkout, renewal, failed payment and cancellation by sending it events. For that, your Stripe account needs a webhook endpoint pointing at BuildBase, subscribed to every event BuildBase acts on.

5. On **Credentials**, press **Check Stripe setup** at the top right. **Stripe setup check** reads your Stripe account and changes nothing. It checks your **API keys**, the **Webhook endpoint**, recent **Deliveries**, **Stripe Tax**, and **Retries and recovery emails**, and says what to fix. Right after you save the keys, it reports **No webhook endpoint for this URL**.

![Stripe setup check: 2 things to fix before payments work reliably, the account and Test mode, We can fix this in your Stripe account, the API keys rows marked OK and Info, and under Webhook endpoint the ringed row Problem, No webhook endpoint for this URL, with Check again and Create the endpoint for me](/images/billing-setup/connect-stripe/console-setup-check.webp)

6. Press **Create the endpoint for me**. **Create the webhook endpoint in Stripe?** says exactly what will be made: one endpoint for your BuildBase URL with all 26 events, and its signing secret saved in BuildBase. Only webhook endpoints change: no charge, customer or subscription is touched, and nothing is deleted. Press **Create the endpoint for me** again to do it, or **Back**.

![Create the webhook endpoint in Stripe?, with what it will do and the Create the endpoint for me button ringed beside Back](/images/billing-setup/connect-stripe/console-setup-check-create.webp)

7. Press **Check again**. **Webhook endpoint** now reads **OK**.
8. In Stripe, the webhooks page of your dashboard lists the new endpoint with its events.

### By hand instead

9. To make the endpoint yourself, use the card **Webhook configuration** on **Credentials**. Copy the **Webhook URL**. Under **Required webhook events**, press **Copy** to copy all 26 event names. In Stripe, add an endpoint with that URL and tick every one of them, or **Select all events**. A missing event fails without a word: the dashboard looks healthy while that part of billing never happens.

![Webhook configuration: the Setup instructions, the Webhook URL with its copy button, and Required webhook events, with the Copy button for all 26 event names ringed](/images/billing-setup/connect-stripe/console-webhook-card.webp)

10. Stripe shows the endpoint's signing secret, `whsec_...`. Paste it into **Webhook signing secret** at the bottom of the same card and press **Save webhook secret**. Then press **Check Stripe setup** to confirm.

## Tax (optional)

11. To collect tax, first activate Stripe Tax in your Stripe account, under **Settings > Tax**, with a registration for each place you collect. Then switch on **Collect tax on checkouts, credit packs and plan changes** on the card **Stripe Tax**. [Tax](/billing/tax) explains what changes for your customers.

![The Stripe Tax card with the Collect tax on checkouts, credit packs and plan changes switch ringed](/images/billing-setup/connect-stripe/console-stripe-tax.webp)

## Check it works

- **Check Stripe setup** reports **OK** for **API keys** and **Webhook endpoint**.
- After your first test checkout, **Billing > Payment webhooks** lists the events Stripe sent.

## Things to watch out for

- The **Billing** menu stays empty until a secret key is saved.
- Keys from the wrong mode are reported by the check: keep both keys from the same mode, test or live.
- **Select all events** is safe. Leaving out one of the 26 events is not.
- **Check Stripe setup** counts the other endpoints in your Stripe account. When more than one points at your BuildBase URL, it offers **Replace with one new endpoint**.
- The Stripe Tax switch is refused while Stripe Tax is not active in your Stripe account.

## If something goes wrong

| What you see                                                         | Why                                                            | Fix                                                                     |
| -------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| A live key is refused inside an environment (`ENVIRONMENT_KEY_MODE`) | Non-production environments take test keys only                | Use the test keys there                                                 |
| **Restricted key - account details are not readable**                | A restricted key (`rk_...`) without read access to the account | Give the key read access to the account, or use the secret key          |
| The Stripe Tax switch is refused (`STRIPE_TAX_NOT_ACTIVE`)           | Stripe Tax is not active in your Stripe account                | Activate it in Stripe under **Settings > Tax**, then switch it on again |
| **The check could not run. Your settings were not changed.**         | Stripe could not be reached just then                          | Press **Check again**                                                   |

## Next steps

- [Billing overview](/billing/overview) - currencies, products, plans and pricing groups
- [Tax](/billing/tax) - what collecting tax changes
- [Failed payments](/billing/failed-payments) - retries and recovery emails