开发指南微信支付集成
微信支付集成
该功能暂未实现!
🚀 Cheatsheet (快速执行)
目标: 30分钟内集成微信支付,让中国用户可以使用微信支付为你的产品付费
最快上手方式:
# 1. 注册微信商户平台账号
# 访问 https://pay.weixin.qq.com 注册商户
# 2. 获取商户证书和密钥
# 商户平台 > 账户中心 > API安全 > API证书
# 3. 配置环境变量
echo 'WECHAT_PAY_MCH_ID=你的商户号' >> .env.local
echo 'WECHAT_PAY_CERT_SERIAL_NO=证书序列号' >> .env.local
echo 'WECHAT_PAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----你的私钥-----END PRIVATE KEY-----"' >> .env.local
echo 'WECHAT_PAY_API_V3_KEY=你的APIv3密钥' >> .env.local
echo 'WECHAT_PAY_APP_ID=你的微信应用ID' >> .env.local
echo 'PREFERRED_PAYMENT_PROVIDER=wechatpay' >> .env.local
# 4. 安装依赖 (已预装)
# bun add wechatpay-node-v3
# 5. 测试支付
# 重启应用,访问 /zh/wechatpay-test 页面测试支付
立即生效: 用户可以通过微信扫码支付或H5支付,订单状态自动更新
❓ 为什么要集成微信支付
对中国市场的关键价值:
- 用户习惯: 微信支付是中国用户最常用的支付方式之一
- 转化率高: 中国用户对微信支付信任度更高,支付成功率更高
- 人民币结算: 避免汇率波动,用户看到的就是实际支付的价格
- 合规要求: 在中国运营需要支持本地支付方式
真实场景举例: 中国用户发现你的工具很有用,想要升级到Pro版本 → 选择微信支付 → 扫描二维码 → 微信确认支付 → 立即获得Pro功能,整个过程1分钟完成。
🤔 为什么选择微信支付
我们的实战经验:
- 市场覆盖: 在中国有超过12亿用户,覆盖率极高
- 支付便捷: 扫码支付、H5支付、小程序支付多种方式
- 费率合理: 相比国际支付网关,微信支付费率更低
- 技术成熟: V3 API设计先进,支持webhook实时通知
🛠️ 实现原理
架构设计
我们的微信支付集成基于模块化设计,与现有的Stripe支付系统并存:
src/lib/payments/
├── types.ts # 通用支付接口定义
├── provider/
│ ├── stripe/ # Stripe支付提供商
│ ├── wechatpay/ # 微信支付提供商
│ │ └── index.ts # 微信支付核心实现
│ └── index.ts # 提供商导出
└── index.ts # 支付管理器和提供商选择
核心组件
1. 支付提供商接口 (PaymentProvider
)
interface PaymentProvider {
createCheckoutLink: CreateCheckoutLink;
createCustomerPortalLink: CreateCustomerPortalLink;
webhookHandler: WebhookHandler;
}
2. 微信支付实现
- 订单创建: 使用微信支付V3 API创建JSAPI支付订单
- 支付确认: 通过webhook接收微信支付结果通知
- 订单管理: 自动处理支付成功、失败、退款等状态
3. 提供商切换
通过环境变量 PREFERRED_PAYMENT_PROVIDER
控制使用哪个支付提供商:
# 使用微信支付
PREFERRED_PAYMENT_PROVIDER=wechatpay
# 使用Stripe(默认)
PREFERRED_PAYMENT_PROVIDER=stripe
🔧 配置步骤
1. 微信商户平台配置
注册商户账号
- 访问 微信商户平台
- 使用企业资质注册商户账号
- 完成商户认证和签约
获取商户密钥
- 登录商户平台
- 进入 账户中心 > API安全
- 下载商户证书,获取证书序列号
- 生成并设置APIv3密钥
配置回调地址
在商户平台配置支付回调地址:
- 支付通知地址:
https://yourdomain.com/api/webhooks/wechatpay
- 退款通知地址:
https://yourdomain.com/api/webhooks/wechatpay
2. 环境变量配置
在 .env.local
中配置以下变量:
# 微信支付配置
WECHAT_PAY_MCH_ID=你的商户号
WECHAT_PAY_CERT_SERIAL_NO=证书序列号
WECHAT_PAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
你的商户私钥内容
-----END PRIVATE KEY-----"
WECHAT_PAY_API_V3_KEY=你的APIv3密钥
WECHAT_PAY_APP_ID=你的微信应用ID
# 设置微信支付为默认提供商
PREFERRED_PAYMENT_PROVIDER=wechatpay
3. 产品配置
在 src/config/index.ts
中已经配置了微信支付的产品价格:
pro: {
prices: [
// 微信支付选项 (CNY)
{
type: "recurring",
productId: "wechat_pro_monthly",
interval: "month",
amount: 199,
currency: "CNY",
seatBased: true,
},
{
type: "recurring",
productId: "wechat_pro_yearly",
interval: "year",
amount: 1990,
currency: "CNY",
seatBased: true,
},
],
},
📝 API 接口
创建支付订单
// POST /api/payments/create-checkout-link
const response = await fetch('/api/payments/create-checkout-link', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
type: 'subscription', // 或 'one-time'
productId: 'wechat_pro_monthly',
email: 'user@example.com',
name: '用户姓名',
redirectUrl: 'https://yourdomain.com/success'
})
});
const { checkoutLink } = await response.json();
// checkoutLink 可以用于生成二维码或直接跳转
Webhook 处理
微信支付的webhook通知会自动处理以下事件:
- TRANSACTION.SUCCESS: 支付成功,创建购买记录
- TRANSACTION.CLOSED: 订单关闭,清理相关数据
- TRANSACTION.REVOKED: 订单撤销,删除购买记录
🚨 重要注意事项
1. 微信支付限制
- 试用期: 微信支付不支持试用期概念,如果产品设置了试用期,会自动跳过微信支付
- 订阅: 微信支付没有原生订阅功能,需要自己实现定期扣费逻辑
- OpenID: 需要获取用户的OpenID才能发起支付,测试时使用默认值
2. 安全要求
- 私钥保护: 商户私钥必须妥善保管,不要提交到代码仓库
- 签名验证: 所有webhook通知都需要验证签名
- HTTPS: 生产环境必须使用HTTPS
3. 测试环境
微信支付提供沙盒环境用于测试:
- 沙盒商户号: 使用测试商户号进行开发测试
- 测试金额: 建议使用小额测试,如0.01元
- 测试工具: 使用微信开发者工具进行测试
🧪 测试指南
1. 使用测试页面
访问 /zh/wechatpay-test
页面进行功能测试:
- 选择产品: 选择要测试的产品套餐
- 填写信息: 输入测试用户信息
- 创建订单: 点击创建微信支付订单
- 查看结果: 检查返回的支付链接和二维码
2. 测试流程
# 1. 启动开发服务器
bun dev
# 2. 访问测试页面
open http://localhost:3000/zh/wechatpay-test
# 3. 创建测试订单
# 选择产品 → 填写信息 → 创建订单
# 4. 验证结果
# 检查订单是否创建成功
# 确认支付链接可以访问
# 验证二维码可以扫描
3. Webhook 测试
使用 ngrok 进行本地webhook测试:
# 安装 ngrok
npm install -g ngrok
# 暴露本地端口
ngrok http 3000
# 在微信商户平台配置 ngrok 提供的 HTTPS 地址
# https://xxxxx.ngrok.io/api/webhooks/wechatpay
🔍 故障排除
常见错误
1. "Missing WeChat Pay environment variables"
原因: 环境变量配置不完整 解决: 检查所有必需的环境变量是否正确设置
2. "Product not found"
原因: 产品ID在配置中不存在
解决: 确认 getProductInfo
函数中包含该产品ID
3. "Invalid signature"
原因: webhook签名验证失败 解决: 检查APIv3密钥和证书配置是否正确
调试技巧
- 查看日志: 检查应用日志中的微信支付相关错误信息
- 测试环境: 先在沙盒环境测试,确认配置正确后再切换到生产环境
- API文档: 参考微信支付官方API文档进行问题排查
📚 相关资源
🚀 下一步
集成完微信支付后,你可以考虑:
- 多支付方式: 根据用户地区自动选择合适的支付方式
- 支付统计: 添加支付成功率、转化率等统计数据
- 用户体验: 优化支付流程,减少用户流失
- 合规处理: 确保符合中国地区的支付合规要求
微信支付集成完成后,你的产品就能更好地服务中国市场,提高用户转化率和支付成功率!