Common Stripe setup issues

Work through these in order when Stripe setup fails in Settings → Invoice Payment Method.

1. Key format

Keys must look like rk_test_…, rk_live_…, sk_test_…, or sk_live_…. Other prefixes are rejected.

2. Restricted key permissions

The key needs Write on:

• Checkout Sessions
• Payment Intents
• Webhook Endpoints

Missing Checkout/Payment Intent write fails validation. Missing Webhook Endpoints write may save the key but fail webhook setup (webhookSetup: failed).

3. Webhook creation

On save, Docora creates an endpoint pointing at your public app URL + /api/webhooks/stripe/{userId} for checkout.session.completed. Production requires a public HTTPS NEXT_PUBLIC_APP_URL (or equivalent). Localhost alone cannot receive Stripe webhooks.

4. Local development

Either:

• Set NGROK_URL to your ngrok HTTPS URL (no trailing slash), then re-save the key so the webhook targets ngrok, or
• Run stripe listen --forward-to http://localhost:3001/api/webhooks/stripe/{userId}, put the CLI whsec_… in STRIPE_CLI_WEBHOOK_SECRET, and restart the dev server (env is read at process start). In development the CLI secret overrides the stored per-user secret.

Never set NGROK_URL to localhost.

5. Encryption

Saving keys requires ENCRYPTION_KEY on the server. Without it, persistence fails.

6. Still stuck?

See Why isn’t my payment showing as paid and contact support@docora.io with whether key save, webhook setup, or checkout is failing.