Stripe
Card payments, subscriptions and billing for web checkout.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Trust boundary
- Never take an amount, price or currency from the client. Look the price up server-side from an id you control. A forged request body is trivial.
- The secret key is server-side only. The publishable key is the only one that may reach a browser.
- Landing on the success page is not proof of payment.
Webhooks are the source of truth
- Verify every webhook signature against the raw body. A parsed body breaks the check; an unverified endpoint accepts forged "payment succeeded" events from anyone.
- Idempotency is required, not optional. Stripe retries and delivers at-least-once: record the event id and ignore duplicates, or a retry grants access twice.
- Handle the subscription lifecycle —
updatedanddeleted— not only checkout completion.
Money
- Amounts are integers in the smallest currency unit. Never use floats.
- Store the Stripe customer and subscription ids against your own user.
Never
- Never log a full card number, secret key or webhook payload containing personal data.
- Never use Stripe for digital goods inside a mobile app — the stores reject it.
- Never grant access from client state alone; re-check server-side.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Stripe conventions
globs: ["server/**", "api/**", "app/api/**", "src/services/payments/**"]
alwaysApply: false
---
# Stripe
## Trust boundary
- **Never take an amount, price or currency from the client.** Look the price up
server-side from an id you control. A forged request body is trivial.
- The secret key is server-side only. The publishable key is the only one that
may reach a browser.
- Landing on the success page is not proof of payment.
## Webhooks are the source of truth
- Verify every webhook signature against the **raw** body. A parsed body breaks
the check; an unverified endpoint accepts forged "payment succeeded" events
from anyone.
- **Idempotency is required**, not optional. Stripe retries and delivers
at-least-once: record the event id and ignore duplicates, or a retry grants
access twice.
- Handle the subscription lifecycle — `updated` and `deleted` — not only
checkout completion.
## Money
- Amounts are integers in the smallest currency unit. Never use floats.
- Store the Stripe customer and subscription ids against your own user.
## Never
- Never log a full card number, secret key or webhook payload containing
personal data.
- Never use Stripe for digital goods inside a mobile app — the stores reject it.
- Never grant access from client state alone; re-check server-side.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting Stripe contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
STRIPE_SECRET_KEYrequiredServer-side API key. Never ship in a client bundle.STRIPE_WEBHOOK_SECRETrequiredVerifies webhook signatures. The endpoint is public without it.{{envPrefix}}STRIPE_PUBLISHABLE_KEYoptionalBrowser-side key for Stripe.js. Safe to expose.Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Rules people add alongside this one
The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.