adding-stripe

添加 Stripe 支付

当用户要求添加支付、账单、订阅或 Stripe 集成时，请使用此技能。

步骤

1. 安装 SDK

   npm install stripe @stripe/stripe-js
   

2. 添加环境变量

   STRIPE_SECRET_KEY=sk_test_...
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
   STRIPE_WEBHOOK_SECRET=whsec_...
   

3. 创建 Stripe 客户端模块 — 创建 lib/stripe.ts：

   import Stripe from "stripe";
   
   export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
     apiVersion: "2024-12-18.acacia",
   });
   

4. 创建结账 API 路由 — 创建一个用于创建 Stripe Checkout 会话的端点：

   const session = await stripe.checkout.sessions.create({
     mode: "subscription", // or "payment" for one-time
     payment_method_types: ["card"],
     line_items: [{ price: priceId, quantity: 1 }],
     success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
     cancel_url: `${origin}/pricing`,
     customer_email: userEmail,
   });
   return redirect(session.url!);
   

5. 创建 Webhook 处理程序 — 在 /api/webhooks/stripe 创建一个 POST 端点：

   • 使用 stripe.webhooks.constructEvent 验证 Webhook 签名。
   • 处理关键事件：checkout.session.completed、customer.subscription.updated、customer.subscription.deleted、invoice.payment_failed。
   • 使用订阅状态更新数据库。

6. 添加客户门户（可选） — 创建一个重定向到 stripe.billingPortal.sessions.create 的端点，让用户管理自己的订阅。

7. 添加定价页面 UI — 创建包含套餐卡片的定价页面，并让卡片调用结账 API 路由。

注意事项

• 始终验证 Webhook 签名，切勿信任未经验证的负载。
• 使用 Stripe CLI（stripe listen --forward-to localhost:3000/api/webhooks/stripe）在本地测试 Webhook。
• 将 Stripe 客户 ID 存储在用户数据库中，以避免创建重复客户。
• 使用 stripe.prices.list 动态获取价格，而不要将价格硬编码。