--- name: integrating-stripe-payments description: 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. version: "1.0.0" dependencies: ["stripe", "convex", "next.js"] allowed-tools: ["stripe-mcp", "convex-mcp", "file_write", "bash"] --- # 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. 1. **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_...` 2. **Install dependencies**: `npm install stripe` 3. **Set initial environment variables**: - `STRIPE_SECRET_KEY` (from step 1) - `NEXT_PUBLIC_SITE_URL=http://localhost:3000` (default local development) 4. **Use Stripe MCP tool** to create product/price and get price ID 5. **Use Convex MCP tool** to set remaining environment variables 6. **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 1. Get Convex deployment URL (use `.convex.site` domain) 2. Create webhook in Stripe Dashboard: `https://your-deployment.convex.site/stripe/webhook` 3. Select events: `checkout.session.completed`, `customer.subscription.*`, `invoice.*` 4. Copy webhook secret to environment variables ### 7. Testing Follow `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. --- Source attribution: bountydotnew Original project: https://github.com/bountydotnew/bounty.new/blob/0ee5c0bde6c84ac3c83516893498618d6fcee6e4/.claude/skills/integrating-stripe-payments/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 Bounty.new Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: bountydotnew Original project: https://github.com/bountydotnew/bounty.new/blob/0ee5c0bde6c84ac3c83516893498618d6fcee6e4/.claude/skills/integrating-stripe-payments/SKILL.md Attribution basis: Recovered original package and original project license at a pinned revision Fields of work: Development & Engineering, Marketing, Sales Roles: Backend Developer, Customer Success Manager, Growth Marketer, Product Marketer, Sales Engineer Specialties: API, Backend Tools: Stripe Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: c45a131cf749ea78358514e60bd0d6269e334650a79a00fffa73408a43c3dd56 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.