文档
开发指南微信支付集成

微信支付集成

该功能暂未实现!

🚀 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. 微信商户平台配置

注册商户账号

  1. 访问 微信商户平台
  2. 使用企业资质注册商户账号
  3. 完成商户认证和签约

获取商户密钥

  1. 登录商户平台
  2. 进入 账户中心 > API安全
  3. 下载商户证书,获取证书序列号
  4. 生成并设置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 页面进行功能测试:

  1. 选择产品: 选择要测试的产品套餐
  2. 填写信息: 输入测试用户信息
  3. 创建订单: 点击创建微信支付订单
  4. 查看结果: 检查返回的支付链接和二维码

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密钥和证书配置是否正确

调试技巧

  1. 查看日志: 检查应用日志中的微信支付相关错误信息
  2. 测试环境: 先在沙盒环境测试,确认配置正确后再切换到生产环境
  3. API文档: 参考微信支付官方API文档进行问题排查

📚 相关资源

🚀 下一步

集成完微信支付后,你可以考虑:

  1. 多支付方式: 根据用户地区自动选择合适的支付方式
  2. 支付统计: 添加支付成功率、转化率等统计数据
  3. 用户体验: 优化支付流程,减少用户流失
  4. 合规处理: 确保符合中国地区的支付合规要求

微信支付集成完成后,你的产品就能更好地服务中国市场,提高用户转化率和支付成功率!