菜单
Use when integrating Stripe — set up Checkout for subscriptions, verify webhooks with the signing secret, handle events idempotently, and keep your database in sync with Stripe as the source of truth for billing state.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | payments-stripe |
| description | Use when integrating Stripe — set up Checkout for subscriptions, verify webhooks with the signing secret, handle events idempotently, and keep your database in sync with Stripe as the source of truth for billing state. |
Stripe is the billing source of truth; your database is a synced read-model. The flow: send users to Checkout, then let webhooks drive every state change (subscription created/updated/cancelled, payment succeeded/failed). Never set a user to "paid" from the success-redirect — that's spoofable. Verify webhook signatures, process events idempotently, and reconcile to your DB.
// server action / route handler
import Stripe from "stripe";
import { env } from "@/env";
const stripe = new Stripe(env.STRIPE_SECRET_KEY);
export async function createCheckout(orgId: string, priceId: string) {
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: priceId, quantity: 1 }],
success_url: `${env.NEXT_PUBLIC_APP_URL}/billing?success=1`,
cancel_url: `${env.NEXT_PUBLIC_APP_URL}/billing`,
client_reference_id: orgId, // tie the session back to YOUR tenant
metadata: { orgId },
});
return session.url!;
}
// src/app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
import { env } from "@/env";
const stripe = new Stripe(env.STRIPE_SECRET_KEY);
export async function POST(req: Request) {
const body = await req.text(); // RAW body, not parsed JSON
const sig = req.headers.get("stripe-signature")!;
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(body, sig, env.STRIPE_WEBHOOK_SECRET);
} catch {
return new Response("Invalid signature", { status: 400 });
}
if (await alreadyProcessed(event.id)) return new Response("ok"); // idempotency
switch (event.type) {
case "checkout.session.completed":
case "customer.subscription.updated":
case "customer.subscription.deleted":
await syncSubscriptionToDb(event); // upsert plan/status/period
break;
}
await markProcessed(event.id);
return new Response("ok");
}
event.ids so retries don't double-apply.metadata you didn't set — only read metadata you wrote (e.g. orgId).Stripe events synced into your DB. subscription-billing turns that synced state into plan limits and entitlements; the customer portal handles upgrades/cancellations.
Use when building API endpoints or server actions — validate every input with zod, return consistent typed JSON errors, set correct status codes, and authenticate/authorize before touching data.
Use when adding sign-in/sign-up or session handling to a SaaS app — set up Auth.js (NextAuth) or a hosted provider with secure sessions, OAuth + email, and server-side session checks that protect routes and actions.
Use when controlling what a user may do — implement role-based access control with a central permission map, server-side checks on every mutation, and a typed `can()` helper instead of scattered role string comparisons.
Use when work shouldn't run in the request path — offload emails, webhooks, exports, and scheduled tasks to a queue or job runner with retries, idempotency, and dead-letter handling instead of blocking the user.
Use when querying or mutating the database from the app — wrap Drizzle in server-only, tenant-scoped functions instead of calling the ORM from components, so every read/write is typed, testable, and isolation-safe.
Use when designing the Postgres schema or setting up Drizzle ORM — model users, organizations, memberships, and tenant-scoped tables with the right keys, indexes, timestamps, and migrations from day one.