# Payment

> 当用户想加支付、收款、集成 Stripe、做订阅付费时使用 — 集成支付系统，支持一次性和订阅

- Skill: `lightpointventures/payment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lightpointventures/payment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lightpointventures/payment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: lightpointventures (https://skillmd.com/u/lightpointventures)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lightpointventures/payment

---


# 添加支付功能

帮用户集成在线支付，实现收款。

## 步骤

### 1. 了解需求

**问题 1：支付类型**
> 你需要什么类型的支付？
> - 一次性付款（买商品、买服务）
> - 订阅/会员（按月/按年收费）
> - 两者都要

**问题 2：定价**
> 价格是多少？如果是订阅，月费和年费分别是多少？

**问题 3：目标客户地区**
> 客户主要在哪里？这决定了支付方式的选择。

### 2. 选择支付服务商

根据需求推荐：

| 服务商 | 适用场景 | 特点 |
|--------|----------|------|
| **Stripe** | 国际客户，需要灵活定制 | 功能最全，开发者体验好，需自行处理税务 |
| **LemonSqueezy** | SaaS/数字产品 | 自动处理全球销售税，API 更简单，适合独立开发者 |
| **Paddle** | SaaS 订阅为主 | 作为 Merchant of Record 处理税务+发票，合规省心 |

> 注意：如果客户在中国大陆，Stripe 对国内用户支付支持有限。建议额外集成支付宝/微信支付（可通过 Stripe 的 Alipay/WeChat Pay 支付方式，或直接对接支付宝开放平台）。

不确定就用 Stripe（生态最大，文档最全）。

### 3. 配置支付服务

- **安装 SDK** — 按所选服务商安装对应的官方库
- **配置环境变量** — Secret Key 和 Publishable Key，添加到 .env.example
- 提示用户去服务商官网注册账号，获取**测试模式**的 API Key

### 4. 生成支付代码

**后端：**
- 创建 Checkout Session 接口
- Webhook 处理（支付成功、订阅变更、退款）
- 验证 Webhook 签名（见下方安全要求）

**前端：**
- 定价页面（价格卡片 + 购买按钮）
- 跳转到 Checkout 页面
- 支付成功/取消回调页面

**订阅（如果需要）：**
- 创建 Product 和 Price 对象
- 订阅管理（升级、降级、取消）
- 用户订阅状态查询和权限控制

### 5. Webhook 安全（必做）

Webhook 是支付系统的核心通信通道，必须做好安全防护：
- **始终验证签名** — 用服务商提供的 Webhook Secret 验证每个请求的签名，拒绝签名不匹配的请求
- **使用 HTTPS 端点** — Webhook URL 必须是 HTTPS
- **实现幂等处理** — 同一事件可能被重复投递，用事件 ID 去重，避免重复发货或重复计费
- **返回 200 状态码** — 即使业务处理失败也先返回 200，把失败的事件放入重试队列。否则服务商会不断重试

### 6. 测试

使用测试卡号完成端到端验证（Stripe 测试卡：4242 4242 4242 4242，任意未来日期，任意 CVC）：
- 完成一次成功支付
- 用 Stripe CLI 或服务商工具触发 Webhook 事件，确认处理正确
- 测试支付失败场景（卡号 4000 0000 0000 0002）

> 支付功能已集成，测试模式验证正常。
> 上线前：切换到生产模式 API Key，配置生产 Webhook 端点。

## 遇到问题

- **Webhook 收不到事件** — 本地开发时需要用 Stripe CLI (`stripe listen --forward-to localhost:端口/webhook`) 转发事件。部署后确认 Webhook URL 在服务商后台已正确配置且状态为 Active
- **测试模式和生产模式混淆** — 测试 Key 以 `sk_test_` 开头，生产 Key 以 `sk_live_` 开头。两套 Key 的数据完全隔离。常见错误：用生产 Key 查测试订单，或反过来
- **货币问题** — Stripe 金额单位是"分"（cents），100 = 1 美元。如果显示金额异常，检查是否漏乘或多乘了 100。多币种场景下，确保创建 Checkout Session 时明确指定 currency
- **支付成功但数据库未更新** — 不要依赖前端回调来确认支付状态，必须以 Webhook 事件为准。前端回调仅用于页面跳转，实际的订单确认和权限开通必须在 Webhook 处理中完成