playbooks

home / skills / phrazzld / claude-config / stripe-configure

stripe-configure skill

/skills/stripe-configure

This skill helps you configure Stripe dashboard and deployment environments by setting products, prices, webhooks, and environment variables.

npx playbooks add skill phrazzld/claude-config --skill stripe-configure

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.7 KB
---
name: stripe-configure
description: |
  Configure Stripe Dashboard and deployment environments.
  Sets up products, prices, webhooks, and environment variables.
effort: high
---

# Stripe Configure

Set up Stripe Dashboard and deployment environment variables.

## Objective

Configure everything outside the codebase: Stripe Dashboard settings, environment variables across all deployments, webhook endpoints.

## Process

**1. Stripe Dashboard Setup**

Guide the user through (or use Stripe CLI where possible):

**Products & Prices**
- Create product (name matches app)
- Create price(s): monthly, annual if applicable
- Note the price IDs for env vars

**Webhook Endpoint**
- Create endpoint pointing to production URL
- Use canonical domain (www if that's where app lives — Stripe doesn't follow redirects)
- Enable required events (from design)
- Copy webhook signing secret

**Customer Portal** (if using)
- Configure allowed actions
- Set branding

**2. Environment Variables**

Set variables on ALL deployment targets. This is where incidents happen.

**Local Development**
```bash
# .env.local
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_STRIPE_PRICE_ID=price_...
```

**Convex (both dev and prod)**
```bash
# Dev
npx convex env set STRIPE_SECRET_KEY "sk_test_..."
npx convex env set STRIPE_WEBHOOK_SECRET "whsec_..."

# Prod (DON'T FORGET THIS)
npx convex env set --prod STRIPE_SECRET_KEY "sk_live_..."
npx convex env set --prod STRIPE_WEBHOOK_SECRET "whsec_..."
```

**Vercel**
```bash
vercel env add STRIPE_SECRET_KEY production
vercel env add STRIPE_WEBHOOK_SECRET production
# ... etc
```

**3. Verify Parity**

Check that all deployments have matching configuration:
- Local has test keys
- Convex dev has test keys
- Convex prod has live keys
- Vercel prod has live keys

Use `verify-env-parity.sh` if available, or manually compare.

**4. Webhook URL Verification**

CRITICAL: Verify webhook URL doesn't redirect.

```bash
curl -s -o /dev/null -w "%{http_code}" -I -X POST "https://your-domain.com/api/stripe/webhook"
```

Must return 4xx or 5xx, NOT 3xx. If it redirects, fix the URL in Stripe Dashboard.

## Common Mistakes

- Setting env vars on dev but forgetting prod
- Using wrong domain (non-www when app is www)
- Trailing whitespace in secrets (use `printf '%s'` not `echo`)
- Test keys in production, live keys in development

## Output

Checklist of what was configured:
- [ ] Product created
- [ ] Price(s) created
- [ ] Webhook endpoint configured
- [ ] Env vars set on local
- [ ] Env vars set on Convex dev
- [ ] Env vars set on Convex prod
- [ ] Env vars set on Vercel
- [ ] Webhook URL verified (no redirect)

Overview

This skill configures Stripe Dashboard settings and deployment environment variables for a production-ready integration. It walks through creating products and prices, registering webhook endpoints, and setting secrets across local and hosted deployments. The goal is to eliminate common misconfigurations that break billing or webhooks.

How this skill works

The skill inspects and documents required Stripe resources (products, prices, webhook signing secret) and then instructs how to apply those values to each deployment target. It guides you through creating the webhook endpoint pointing at your canonical domain and verifies the endpoint does not redirect. Finally, it provides commands and checks to set and verify environment variables across local, Convex, and Vercel environments.

When to use it

  • Setting up Stripe for a new app or release
  • Migrating from test to live keys for production
  • Adding or rotating webhook signing secrets
  • Ensuring parity across multiple deployment targets

Best practices

  • Use the app canonical domain (include www if that’s the live domain) when creating webhook endpoints
  • Store live secrets only in production environments; keep test keys in local and dev
  • Set environment variables on every deployment target to avoid incident windows
  • Verify the webhook URL returns non-3xx responses and the signing secret matches Stripe’s value
  • Avoid trailing whitespace when copying secrets; prefer printf-style commands over echo

Example use cases

  • Initial Stripe setup: create product, monthly and annual prices, add price IDs to env vars
  • Deploying to production: set live STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in Convex and Vercel
  • Local development: populate .env.local with test keys and publishable key for frontend testing
  • Webhook troubleshooting: confirm Stripe can POST to /api/stripe/webhook without redirect and validate signature

FAQ

What should I do if Stripe webhook requests are failing with a redirect?

Update the webhook URL in the Stripe Dashboard to your canonical domain that serves the webhook directly (no redirects). Re-test with curl and re-register the signing secret.

How do I avoid putting test keys in production by mistake?

Maintain a clear mapping: local/dev = test keys; prod = live keys. Use separate environment settings and verify parity before deployment. Consider a checklist that requires live key confirmation before release.