该技能用于给 Web 应用接入 Stripe Checkout 支付,核心原则是:只有来自经过验证的 Stripe 事件时才授予访问权限,先测试模式,用户确认测试流程可用后再切换到生产模式。
一、测试模式
- 向用户索取测试密钥(Stripe Dashboard 沙箱,Developers > API keys):pk_test_... 与 sk_test_...。密钥只存服务端(Convex 环境变量、Cloudflare secret、.env.local),不放在 VITE_/NEXT_PUBLIC_ 变量中,也不提交到 git。
- 通过 Stripe API 或 CLI 创建产品与价格(每个产品可一个价格),价格 ID 保存在配置中,不信任浏览器传来的价格。
- 服务端端点创建 Checkout Session(mode 为 "payment" 或 "subscription"),设置 client_reference_id / metadata 为用户 ID 与产品 ID,已知时传 customer_email,success_url 带 {CHECKOUT_SESSION_ID},并设置 cancel_url。
- Webhook 端点(checkout.session.completed,必要时加 charge.refunded / customer.subscription.deleted):读取原始请求体并用 webhook 密钥(whsec_...)校验签名;保证幂等(保存事件或 session ID,忽略重复);从已验证的 session 授予访问权限,绝不从成功页授予;在邮件工具中 upsert 买家(标记已订阅、产品标签)。
- 本地或开发环境 Webhook:运行 stripe listen --forward-to <url>/api/stripe/webhook,使用打印出的密钥。
- 成功页在服务端读取 session,显示“访问已解锁”或“支付处理中”。
二、端到端测试 以登出状态、新邮箱,用 4242 4242 4242 4242、任意未来日期、任意 CVC 支付。检查:成功页、收到登录验证码邮件、会员区产品已解锁、数据库有订单记录、Stripe 中一次 Webhook 投递标记为 200。另测拒付卡(4000 0000 0000 0002)与同一事件的二次投递。
三、生产模式 用户提供正式密钥(pk_live_...、sk_live_...),只设置在生产环境。创建正式产品与价格,在生产 URL 上创建相同事件的正式 Webhook 端点,并把其 whsec_ 密钥存入生产环境。部署后请用户做一次真实购买(或使用 100% 优惠券)并按同一清单核验;若为测试则退款。
四、规则 绝不打印、记录或提交密钥;开发环境绝不用正式密钥;绝不从 URL 参数或客户端调用授予访问权限;上线前对 checkout 与 webhook 运行 audit-safety 技能。
适用场景:需要在 Web 应用中销售商品或订阅、接入 Stripe 支付与访问控制。限制:资料未说明支持的具体技术栈范围、费用或价格信息,相关事实暂未提供。