Claude-skill-registry Integrating Stripe Payments

Complete workflow for integrating Stripe payments (subscriptions or one-time) with Convex + Next.js. Includes hosted checkout, webhooks, UI components, and testing. Use when adding payment functionality to a Convex + Next.js app.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/integrating-stripe-payments" ~/.claude/skills/majiayu000-claude-skill-registry-integrating-stripe-payments && rm -rf "$T"

manifest: skills/data/integrating-stripe-payments/SKILL.md

Integrating Stripe Payments

Core Workflow

When user requests Stripe payment integration for Convex + Next.js:

1. Requirements Gathering

Ask these questions first:

Payment type: Subscription or one-time payment?
Backend: Confirm this is Convex (required for this skill)
Checkout preference: Hosted Stripe Checkout (recommended) or embedded?
Pricing: Amount, currency, billing interval for subscriptions?
Product: What does user get after payment?

2. API Keys & Environment Setup

CRITICAL: Gather these FIRST before proceeding - MCP tools require credentials.

Get Stripe API keys from user:
- Ask for Stripe Secret Key (starts with
```
sk_test_
```
  or
```
sk_live_
```
  )
- Add to
```
.env.local
```
  :
```
STRIPE_SECRET_KEY=sk_test_...
```
Install dependencies:
```
npm install stripe
```
Set initial environment variables:
- ```
STRIPE_SECRET_KEY
```
  (from step 1)
- ```
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```
  (default local development)
Use Stripe MCP tool to create product/price and get price ID
Use Convex MCP tool to set remaining environment variables
Manual fallback: Follow
```
resources/environment-setup.md
```

Complete required env vars:

```
STRIPE_SECRET_KEY
```
✓ (set in step 1)
```
STRIPE_PRICE_ID
```
(from Stripe MCP tool)
```
STRIPE_WEBHOOK_SECRET
```
(set during webhook configuration)
```
NEXT_PUBLIC_SITE_URL
```
✓ (set in step 1)

3. Database Schema

Update

convex/schema.ts

with Stripe fields. See

resources/database-schema.ts

for complete schema.

4. Backend Implementation

Copy and customize these files:

convex/stripe.ts

← Use

resources/convex-stripe-actions.ts

convex/stripeDb.ts

← Use

resources/convex-stripe-db.ts

convex/http.ts

← Use

resources/convex-webhook-handler.ts

Key customizations:

Update membership tier names (
```
"pro"
```
vs
```
"premium"
```
)
Adjust auth field names (
```
clerkId
```
vs your auth system)
Set correct API version:
```
2025-08-27.basil
```
Enable coupon codes by setting
```
allow_promotion_codes: true
```
in checkout session creation

5. Frontend Components

Create UI components from

resources/ui-components.tsx

```
UpgradeButton
```
- Shows different states based on membership
```
ManageBillingButton
```
- Opens customer portal

UI Design Guidelines:

Match existing app design system
Use gradients and proper state management
Show loading states and error handling
Keep prices in sync with Stripe Dashboard

6. Webhook Configuration

Get Convex deployment URL (use
```
.convex.site
```
domain)

Create webhook in Stripe Dashboard:

https://your-deployment.convex.site/stripe/webhook

Select events:

checkout.session.completed

customer.subscription.*

invoice.*

Copy webhook secret to environment variables

7. Testing

resources/testing-checklist.md

Test successful payment flow
Test failed payments
Test customer portal
Verify webhook delivery
Use Stripe CLI for local testing

8. Production Deployment

Switch to live Stripe keys
Create production webhook endpoint
Configure Customer Portal and Smart Retries
Test with real payment (then refund)

Best Practices

Always:

Use hosted checkout for simplicity and security
Use
```
constructEventAsync
```
in webhooks (not
```
constructEvent
```
)
Include user metadata in checkout sessions
Handle missing
```
current_period_end
```
with fallbacks
Keep UI prices synchronized with Stripe prices
Use consistent Stripe API version across all files
Set
```
allow_promotion_codes: true
```
to enable coupon code input during checkout

Never:

Use
```
.convex.cloud
```
for webhooks (use
```
.convex.site
```
)
Skip webhook idempotency in production
Forget to configure Customer Portal
Deploy without testing webhook delivery

Common Issues

Webhook not working: Check domain (

.convex.site

) and webhook secret Membership not updating: Verify webhook events and metadata API errors: Ensure consistent API version usage

Documentation References

Use Stripe MCP tool for latest documentation when:

Checking API changes or new features
Troubleshooting integration issues
Verifying best practices

See

resources/

folder for complete code examples and detailed setup instructions.