Skip to content

Stripe payments

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

View as MarkdownCoding agents can read this page at /docs/stripe.md

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.
  • 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 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 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:

    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:

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:

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. Existing unpaid invoices get the button too; you don’t need to resend them.