Cursor rule

1---
2description: "Stripe payment integration: webhooks, checkout sessions, subscriptions, idempotency, test mode safety."
3globs: "core/**/billing/**,core/**/payments/**,core/**/stripe/**,**/webhook*stripe*"
4alwaysApply: false
5---
6 
7# Stripe Payment Rules
8 
9These rules apply when working on Stripe payment integration, webhooks, checkout flows, or subscription management.
10 
11## Test Mode Safety (CHECK FIRST)
12 
13Before ANY payment work:
14 
15- [ ] Verify `STRIPE_SECRET_KEY` starts with `sk_test_`
16- [ ] Confirm test webhook secret (`whsec_...` from Stripe CLI)
17- [ ] Use test card numbers only (4242 4242 4242 4242)
18- [ ] Never use production keys in development
19 
20## Webhook Handler Pattern
21 
22**ALWAYS** verify webhook signatures and handle idempotency:
23 
24```python
25import stripe
26from fastapi import Request, HTTPException
27 
28async def handle_stripe_webhook(request: Request):
29    payload = await request.body()
30    signature = request.headers.get("stripe-signature")
31 
32    try:
33        event = stripe.Webhook.construct_event(
34            payload, signature, settings.STRIPE_WEBHOOK_SECRET
35        )
36    except stripe.error.SignatureVerificationError:
37        raise HTTPException(status_code=400, detail="Invalid signature")
38 
39    # Idempotency: check if event already processed
40    existing = await get_webhook_event(event.id)
41    if existing:
42        return {"status": "already_processed"}
43 
44    # Process event and record
45    await process_event(event)
46    await record_webhook_event(event.id, event.type)
47    return {"status": "processed"}
48```
49 
50## Idempotency Checklist
51 
52For ALL webhook handlers:
53 
54- [ ] Store event ID before processing
55- [ ] Check for duplicate events before processing
56- [ ] Use database transactions for atomicity
57- [ ] Return 200 OK even on idempotency skip (Stripe retries on non-200)
58 
59## Common Webhook Events
60 
61```python
62SUBSCRIPTION_EVENTS = [
63    "customer.subscription.created",
64    "customer.subscription.updated",
65    "customer.subscription.deleted",
66    "invoice.payment_succeeded",
67    "invoice.payment_failed",
68]
69```
70 
71## Local Webhook Testing
72 
73Use the Stripe CLI to forward events locally:
74 
75```bash
76# Start webhook forwarding
77stripe listen --forward-to localhost:8000/api/v1/webhooks/stripe
78 
79# Trigger test events
80stripe trigger checkout.session.completed
81stripe trigger invoice.payment_succeeded
82stripe trigger customer.subscription.deleted
83```
84 
85## FORBIDDEN
86 
87- Hardcoding API keys (use environment variables)
88- Skipping webhook signature verification
89- Processing webhooks without idempotency checks
90- Using production Stripe keys in development or CI
91- Ignoring failed payment events (always handle `invoice.payment_failed`)
92 
93## Evidence Template for Linear
94 
95Attach this after completing payment work:
96 
97```markdown
98**Payment Testing Evidence**
99 
100- [ ] Test mode verified (`sk_test_` key)
101- [ ] Webhook signature verification tested
102- [ ] Idempotency tested (duplicate event handling)
103- [ ] Success flow tested (card 4242...)
104- [ ] Failure flow tested (card 4000 0000 0000 0002)
105- [ ] Subscription lifecycle tested (create/update/cancel)
106 
107**Test Results:**
108- Webhook events processed: {count}
109- All flows: PASSED
110```
111 
112## Key References
113 
114- **Stripe Docs**: https://stripe.com/docs
115- **Webhook best practices**: https://stripe.com/docs/webhooks/best-practices
116- **Payment patterns**: `patterns_library/` (search for payment/billing patterns)
117- **Full skill docs**: `.claude/skills/stripe-patterns/SKILL.md`
118