# Stripe payments

> Let clients pay invoices by card with Stripe Checkout, and have payments recorded automatically.

Stripe is optional, and only used by Invoicing. Without it, online invoices have no **Pay** button and you record payments by hand.

With Stripe connected, each online invoice gets a **Pay** button. The client pays on a Stripe-hosted checkout page, Stripe notifies the app through a webhook, and the app records the payment and emails a receipt.

You need two values:

| Variable | Example | What it is |
|----------|---------|------------|
| `STRIPE_SECRET_KEY` | `sk_test_...` or `rk_test_...` | API key the app uses to create checkout pages |
| `STRIPE_WEBHOOK_SECRET` | `whsec_...` | Secret the app uses to check that payment notifications really come from Stripe |

A webhook is a message Stripe sends to your app's address when something happens, here "a checkout was paid". Set both variables: with only the API key, clients can pay but the invoice is never marked paid.

## Before you start

- A [Stripe account](https://dashboard.stripe.com/register).
- Invoicing deployed at a public HTTPS address (`APP_URL`). Stripe can't send webhooks to `localhost`.
- The currency of your invoices must be one Stripe supports for your account. Stripe also has a minimum charge per currency (around 0.50 in most major currencies).

## Start in a sandbox

Stripe sandboxes are test environments: same dashboard, fake money, test cards. Sandbox keys start with `sk_test_` or `rk_test_`; live keys start with `sk_live_` or `rk_live_`. Each has its own webhook endpoints and secrets. Set everything up in a sandbox first, then repeat in live mode.

## Step 1: Get an API key

1. In the Stripe Dashboard, make sure you're in your sandbox, and open the [API keys](https://dashboard.stripe.com/apikeys) page.
2. Pick one:
   - **Restricted key (recommended).** Create a restricted key and give it write access to Checkout Sessions, which is the only thing the app uses. Leave everything else at none. If payments fail with a permissions error, check this permission.
   - **Secret key.** Copy the standard secret key. It can do anything on your account, so treat it carefully.
3. Store the key in a password manager. In live mode, Stripe shows a key you create only once.

## Step 2: Create the webhook endpoint

1. Open the [Webhooks](https://dashboard.stripe.com/webhooks) tab in Workbench.
2. Click **Create an event destination**.
3. Select **Your account**.
4. For the payload format, choose **Snapshot**, not **Thin**. The app reads the full checkout details from the event, which only snapshot events include. Leave the API version as offered.
5. Select the event `checkout.session.completed`. You don't need any others.
6. Click **Continue**, select **Webhook endpoint**, and click **Continue**.
7. For **Endpoint URL**, enter your `APP_URL` followed by `/api/stripe/webhook`:

   ```text
   https://billing.example.com/api/stripe/webhook
   ```

8. Create the destination. On its page, click **Reveal secret** and copy the value starting with `whsec_`.

## Step 3: Configure the app

Set both variables on your deployment and restart or redeploy:

```sh
STRIPE_SECRET_KEY=rk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
```

## Test a payment

1. Create an invoice for a client whose email you can read (or yourself), and send it.
2. Open the invoice link from the email (`/i/...`). You should see a **Pay** button with the amount due.
3. Click it. On Stripe's checkout page, pay with the test card `4242 4242 4242 4242`, any future expiry date, any CVC and any postal code.
4. You're sent back to the invoice. Within a few seconds the payment appears on the invoice in the app, the status changes to paid (or partly paid), and the client gets a receipt email.
5. In Workbench, the webhook's **Event deliveries** tab should show the event as delivered.

## Go live

1. Switch the Dashboard from the sandbox to live mode (you may need to finish activating your Stripe account first).
2. Repeat steps 1 and 2 in live mode: a live key and a new webhook endpoint with the same URL and event. The live endpoint has its own `whsec_` secret.
3. Replace both variables with the live values and redeploy.

## Troubleshooting

- **No Pay button on the invoice:** `STRIPE_SECRET_KEY` isn't set on the running app, the invoice is void, or nothing is left to pay.
- **"Online payments aren't enabled":** same as above.
- **Clicking Pay shows a Stripe error:** the message comes from Stripe. Common causes: a restricted key without Checkout Sessions write access, a currency Stripe doesn't support for your account, or an amount below Stripe's minimum.
- **The client paid but the invoice isn't marked paid:** open the webhook in Workbench and check **Event deliveries**.
  - `404`: `STRIPE_WEBHOOK_SECRET` isn't set on the running app.
  - `400` (`Bad signature`): the secret doesn't match this endpoint (for example a sandbox secret with a live endpoint), or the server's clock is off by more than 5 minutes.
  - Delivered with `200` but still unpaid: the destination uses **Thin** payloads, or isn't subscribed to `checkout.session.completed`. Create a **Snapshot** destination for that event.
  - Connection errors: the URL is wrong or the app isn't reachable over HTTPS.

  After fixing it, resend the event from Stripe. The app ignores a payment it has already recorded, so resending is safe.

## Adding this to an existing deploy

You can add Stripe at any time. Do steps 1 and 2 above in the Stripe Dashboard, then set both variables on the running app:

```sh
STRIPE_SECRET_KEY=rk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
```

- **Railway:** open the app service's **Variables** tab, add the variables, and deploy the staged changes. Railway redeploys the service.
- **Render:** open the web service's environment settings, add the variables, and save. Render redeploys the service. If you deployed Invoicing from the repository's `render.yaml`, these two variables already exist (empty); fill them in.
- **Docker Compose:** add the variables to `apps/invoicing/.env`, then run `docker compose up -d` in `apps/invoicing`. This recreates the app container with the new values. `docker compose restart` is not enough, because it doesn't reload `.env`.

The new settings take effect only after this restart or redeploy.

To confirm it works, open any unpaid invoice's online link: it now shows a **Pay** button. Then run the [test payment](#test-a-payment). Existing unpaid invoices get the button too; you don't need to resend them.