$npx -y skills add lightpointventures/claude-code-starter --skill payment当用户想加支付、收款、集成 Stripe、做订阅付费时使用 — 集成支付系统,支持一次性和订阅
| 1 | # 添加支付功能 |
| 2 | |
| 3 | 帮用户集成在线支付,实现收款。 |
| 4 | |
| 5 | ## 步骤 |
| 6 | |
| 7 | ### 1. 了解需求 |
| 8 | |
| 9 | **问题 1:支付类型** |
| 10 | > 你需要什么类型的支付? |
| 11 | > - 一次性付款(买商品、买服务) |
| 12 | > - 订阅/会员(按月/按年收费) |
| 13 | > - 两者都要 |
| 14 | |
| 15 | **问题 2:定价** |
| 16 | > 价格是多少?如果是订阅,月费和年费分别是多少? |
| 17 | |
| 18 | **问题 3:目标客户地区** |
| 19 | > 客户主要在哪里?这决定了支付方式的选择。 |
| 20 | |
| 21 | ### 2. 选择支付服务商 |
| 22 | |
| 23 | 根据需求推荐: |
| 24 | |
| 25 | | 服务商 | 适用场景 | 特点 | |
| 26 | |--------|----------|------| |
| 27 | | **Stripe** | 国际客户,需要灵活定制 | 功能最全,开发者体验好,需自行处理税务 | |
| 28 | | **LemonSqueezy** | SaaS/数字产品 | 自动处理全球销售税,API 更简单,适合独立开发者 | |
| 29 | | **Paddle** | SaaS 订阅为主 | 作为 Merchant of Record 处理税务+发票,合规省心 | |
| 30 | |
| 31 | > 注意:如果客户在中国大陆,Stripe 对国内用户支付支持有限。建议额外集成支付宝/微信支付(可通过 Stripe 的 Alipay/WeChat Pay 支付方式,或直接对接支付宝开放平台)。 |
| 32 | |
| 33 | 不确定就用 Stripe(生态最大,文档最全)。 |
| 34 | |
| 35 | ### 3. 配置支付服务 |
| 36 | |
| 37 | - **安装 SDK** — 按所选服务商安装对应的官方库 |
| 38 | - **配置环境变量** — Secret Key 和 Publishable Key,添加到 .env.example |
| 39 | - 提示用户去服务商官网注册账号,获取**测试模式**的 API Key |
| 40 | |
| 41 | ### 4. 生成支付代码 |
| 42 | |
| 43 | **后端:** |
| 44 | - 创建 Checkout Session 接口 |
| 45 | - Webhook 处理(支付成功、订阅变更、退款) |
| 46 | - 验证 Webhook 签名(见下方安全要求) |
| 47 | |
| 48 | **前端:** |
| 49 | - 定价页面(价格卡片 + 购买按钮) |
| 50 | - 跳转到 Checkout 页面 |
| 51 | - 支付成功/取消回调页面 |
| 52 | |
| 53 | **订阅(如果需要):** |
| 54 | - 创建 Product 和 Price 对象 |
| 55 | - 订阅管理(升级、降级、取消) |
| 56 | - 用户订阅状态查询和权限控制 |
| 57 | |
| 58 | ### 5. Webhook 安全(必做) |
| 59 | |
| 60 | Webhook 是支付系统的核心通信通道,必须做好安全防护: |
| 61 | - **始终验证签名** — 用服务商提供的 Webhook Secret 验证每个请求的签名,拒绝签名不匹配的请求 |
| 62 | - **使用 HTTPS 端点** — Webhook URL 必须是 HTTPS |
| 63 | - **实现幂等处理** — 同一事件可能被重复投递,用事件 ID 去重,避免重复发货或重复计费 |
| 64 | - **返回 200 状态码** — 即使业务处理失败也先返回 200,把失败的事件放入重试队列。否则服务商会不断重试 |
| 65 | |
| 66 | ### 6. 测试 |
| 67 | |
| 68 | 使用测试卡号完成端到端验证(Stripe 测试卡:4242 4242 4242 4242,任意未来日期,任意 CVC): |
| 69 | - 完成一次成功支付 |
| 70 | - 用 Stripe CLI 或服务商工具触发 Webhook 事件,确认处理正确 |
| 71 | - 测试支付失败场景(卡号 4000 0000 0000 0002) |
| 72 | |
| 73 | > 支付功能已集成,测试模式验证正常。 |
| 74 | > 上线前:切换到生产模式 API Key,配置生产 Webhook 端点。 |
| 75 | |
| 76 | ## 遇到问题 |
| 77 | |
| 78 | - **Webhook 收不到事件** — 本地开发时需要用 Stripe CLI (`stripe listen --forward-to localhost:端口/webhook`) 转发事件。部署后确认 Webhook URL 在服务商后台已正确配置且状态为 Active |
| 79 | - **测试模式和生产模式混淆** — 测试 Key 以 `sk_test_` 开头,生产 Key 以 `sk_live_` 开头。两套 Key 的数据完全隔离。常见错误:用生产 Key 查测试订单,或反过来 |
| 80 | - **货币问题** — Stripe 金额单位是"分"(cents),100 = 1 美元。如果显示金额异常,检查是否漏乘或多乘了 100。多币种场景下,确保创建 Checkout Session 时明确指定 currency |
| 81 | - **支付成功但数据库未更新** — 不要依赖前端回调来确认支付状态,必须以 Webhook 事件为准。前端回调仅用于页面跳转,实际的订单确认和权限开通必须在 Webhook 处理中完成 |