Situation Detection
| Context |
Load |
| Choosing Stripe vs Paddle vs LemonSqueezy |
providers.md |
| Implementing checkout, webhooks, refunds |
integration.md |
| Subscription billing, trials, upgrades |
subscriptions.md |
| PCI compliance, fraud prevention |
security.md |
Universal Rules
Never store card data. Use provider-hosted checkout or tokenization. PCI compliance burden explodes the moment raw card numbers touch your server.
Webhooks are truth. Client-side success callbacks lie. A payment succeeded only when your webhook confirms it. Design for webhook-first verification.
Test mode exists for a reason. Use test cards, simulate failures, verify webhook handling. Production surprises cost real money and real customers.
Pricing psychology: $9.99/mo feels cheaper than $120/year, but annual retention is 2-3x higher. Default to annual with monthly option, not the reverse.
Provider Quick Compare
| Need |
Recommendation |
| US/global B2C |
Stripe (best docs, widest coverage) |
| SaaS selling to EU (VAT headache) |
Paddle, LemonSqueezy (merchant of record) |
| Simple product, no dev resources |
Gumroad, Lemonsqueezy hosted |
| Marketplace with splits |
Stripe Connect |
| High-risk or adult |
Specialized processors (CCBill, Epoch) |
See providers.md for detailed comparison.
Integration Checklist
Before going live:
Red Flags
- Storing CVV anywhere, ever → Instant PCI violation
- Trusting client-side payment confirmation → Fraud vector
- No retry logic for failed webhooks → Lost transactions
- Hardcoding prices in frontend → Easy manipulation
- Missing
cancel_at_period_end handling → Angry customers
When to Load More
| Situation |
Reference |
| Evaluating payment processors |
providers.md |
| Building checkout, handling webhooks |
integration.md |
| Recurring billing, metering, trials |
subscriptions.md |
| Fraud, PCI, chargebacks |
security.md |
1---2name: payments3description: Integrate payments with provider selection, checkout flows, subscription billing, and security best practices.4---5
6## Situation Detection
7
8| Context | Load |
9|---------|------|
10| Choosing Stripe vs Paddle vs LemonSqueezy | `providers.md` |
11| Implementing checkout, webhooks, refunds | `integration.md` |
12| Subscription billing, trials, upgrades | `subscriptions.md` |
13| PCI compliance, fraud prevention | `security.md` |
14
15---
16
17## Universal Rules
18
19**Never store card data.** Use provider-hosted checkout or tokenization. PCI compliance burden explodes the moment raw card numbers touch your server.
20
21**Webhooks are truth.** Client-side success callbacks lie. A payment succeeded only when your webhook confirms it. Design for webhook-first verification.
22
23**Test mode exists for a reason.** Use test cards, simulate failures, verify webhook handling. Production surprises cost real money and real customers.
24
25**Pricing psychology:** $9.99/mo feels cheaper than $120/year, but annual retention is 2-3x higher. Default to annual with monthly option, not the reverse.
26
27---
28
29## Provider Quick Compare
30
31| Need | Recommendation |
32|------|----------------|
33| US/global B2C | Stripe (best docs, widest coverage) |
34| SaaS selling to EU (VAT headache) | Paddle, LemonSqueezy (merchant of record) |
35| Simple product, no dev resources | Gumroad, Lemonsqueezy hosted |
36| Marketplace with splits | Stripe Connect |
37| High-risk or adult | Specialized processors (CCBill, Epoch) |
38
39See `providers.md` for detailed comparison.
40
41---
42
43## Integration Checklist
44
45Before going live:
46- [ ] Webhook endpoint secured and verified
47- [ ] Idempotency keys on all charges
48- [ ] Failure states handled (declined, expired, insufficient)
49- [ ] Receipts and invoices configured
50- [ ] Refund flow tested
51- [ ] Subscription lifecycle events handled (upgrade, downgrade, cancel)
52- [ ] Currency handling explicit (store in cents/smallest unit)
53
54---
55
56## Red Flags
57
58- Storing CVV anywhere, ever → Instant PCI violation
59- Trusting client-side payment confirmation → Fraud vector
60- No retry logic for failed webhooks → Lost transactions
61- Hardcoding prices in frontend → Easy manipulation
62- Missing `cancel_at_period_end` handling → Angry customers
63
64---
65
66## When to Load More
67
68| Situation | Reference |
69|-----------|-----------|
70| Evaluating payment processors | `providers.md` |
71| Building checkout, handling webhooks | `integration.md` |
72| Recurring billing, metering, trials | `subscriptions.md` |
73| Fraud, PCI, chargebacks | `security.md` |