payment-security_skill

Overview

This skill implements secure subscription payments using Clerk Billing and Stripe while ensuring your servers never handle card data. It provides components, webhook handlers, and examples to set up Stripe Checkout, subscription gating, and server-side verification without exposing sensitive payment details. Use it to simplify PCI scope and reliably manage subscription lifecycle events.

How this skill works

The frontend uses Clerk's PricingTable to open Stripe Checkout; card entry and processing occur on Stripe's servers so your app never stores or transmits card data. Clerk receives Stripe events, verifies webhooks (Svix), and forwards subscription updates to your backend or Convex where you store subscription state and Stripe IDs only. Server-side checks read subscription metadata to gate premium features and respond to webhook events like created, updated, deleted, and payment_failed.

When to use it

• Adding subscription plans with Stripe Checkout via Clerk Billing
• Protecting premium pages or API routes behind paid plans
• Implementing webhook handling for subscription lifecycle events
• Ensuring your app remains out of PCI-DSS scope
• Testing payment flows safely with Stripe test cards

Best practices

• Never store cardholder data; store only Stripe customer/subscription IDs
• Always verify webhook signatures (Svix) before processing events
• Enforce server-side subscription checks for gated features
• Implement idempotency for webhook handling to avoid duplicate work
• Use Stripe test cards and CLI to validate webhook flows locally

Example use cases

• A Pricing page that opens Clerk-managed Stripe Checkout for upgrades
• A protected dashboard route that requires a paid plan via server auth
• Webhook receiver that updates internal DB when subscriptions change
• Automated emails and state changes on subscription.payment_failed events
• Convex HTTP endpoint that ingests Clerk webhooks and runs mutations