Better WeChatPay

现代化的微信支付 Node.js SDK

ESM、TypeScript、全支付方式支持

在线文档

特性

• ✅ 纯 ESM（ES Modules）
• ✅ 完整的 TypeScript 类型支持
• ✅ 支持所有支付方式（Native/APP/JSAPI/小程序/H5）
• ✅ 双签名验证（新公钥 + 平台证书）
• ✅ 内置调试模式
• ✅ 最小依赖（@peculiar/x509、ofetch）
• ✅ 支持分单位直传（amount_cents），并兼容旧的元单位字段
• ✅ 完善的测试覆盖
• ✅ demo 服务 - 基于 hono 的轻量级 web 应用，用于本地测试和调试
• ✅ 框架集成 - 提供 Next.js 和 Nuxt.js 的使用示例

安装

npm install better-wechatpay

快速开始

import WeChatPay from 'better-wechatpay';

const wechat = new WeChatPay({
  config: {
    appId: process.env.WECHAT_PAY_APP_ID,
    mchId: process.env.WECHAT_PAY_MCH_ID,
    apiKey: process.env.WECHAT_PAY_API_KEY,
    privateKey: process.env.WECHAT_PAY_PRIVATE_KEY,
    publicKey: process.env.WECHAT_PAY_PUBLIC_KEY,
    // 可选但推荐：微信支付公钥验签（无有效期限制）
    paymentPublicKey: process.env.WECHAT_PAY_PAYMENT_PUBLIC_KEY,
    publicKeyId: process.env.WECHAT_PAY_PUBLIC_KEY_ID,
    // 如果配置了 paymentPublicKey + publicKeyId，会默认跳过拉取平台证书
    // 仅灰度兼容场景才需要强制拉取
    forceFetchPlatformCertificates: false,
    notifyUrl: 'https://your-domain.com/webhook/wechat'
  }
});

// 创建 Native 支付（扫码支付）
const payment = await wechat.native.create({
  out_trade_no: 'order-123',
  description: '会员订阅',
  amount_cents: 9900  // 推荐：直接使用分，避免浮点误差
});

console.log('二维码链接:', payment.code_url);

环境变量

必需的环境变量：

# 微信支付凭证
WECHAT_PAY_APP_ID="your_app_id"
WECHAT_PAY_MCH_ID="your_mch_id"
WECHAT_PAY_API_KEY="32_character_api_key"

# 证书（PEM 格式，多行/单行均可）
WECHAT_PAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkq...
-----END PRIVATE KEY-----"

WECHAT_PAY_PUBLIC_KEY="-----BEGIN CERTIFICATE-----
MIID8zCCAtugAwIB...
-----END CERTIFICATE-----"

# 可选但推荐：微信支付公钥（用于验签，无有效期限制）
# 获取位置：商户平台 → 账户中心 → API安全 → 微信支付公钥
WECHAT_PAY_PAYMENT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIIEvgIBADAN...
-----END PUBLIC KEY-----"

# 公钥 ID（下载公钥时显示，必须与公钥配对使用）
# 获取位置：商户平台 → 账户中心 → API安全 → 微信支付公钥
# 格式如：PUB_KEY_ID_0000000000000024101100397200000006
WECHAT_PAY_PUBLIC_KEY_ID="PUB_KEY_ID_xxxx"

初始化证书拉取行为

• 默认情况下，SDK 会在初始化时拉取平台证书。
• 当同时配置 paymentPublicKey 和 publicKeyId 时，SDK 会默认跳过拉取平台证书（适合新商户仅公钥模式）。
• 如需灰度兼容（同时可能收到平台证书序列号签名），可设置 forceFetchPlatformCertificates: true 强制拉取。

支付方式

Native 支付（扫码支付）

const payment = await wechat.native.create({
  out_trade_no: 'order-123',
  description: '会员订阅',
  amount: 99.00
});
// 返回: { code_url: 'weixin://...', out_trade_no: 'order-123' }

APP 支付

const payment = await wechat.app.create({
  out_trade_no: 'order-123',
  description: '会员订阅',
  amount: 99.00
});
// 返回: { prepay_id: '...', out_trade_no: 'order-123' }

JSAPI / 小程序支付

const payment = await wechat.jsapi.create({
  out_trade_no: 'order-123',
  description: '会员订阅',
  amount: 99.00,
  openid: 'user_openid'  // 必填
});
// 返回: { prepay_id: '...', out_trade_no: 'order-123' }

H5 支付

const payment = await wechat.h5.create({
  out_trade_no: 'order-123',
  description: '会员订阅',
  amount: 99.00,
  payer_client_ip: '1.2.3.4',
  h5_info: {
    type: 'Wap',
    app_name: '我的应用',
    app_url: 'https://example.com'
  }
});
// 返回: { h5_url: 'https://wx.tenpay.com/...', out_trade_no: 'order-123' }

文档

在线文档：https://better-wechatpay.vikingz.me

快速入门

• 快速开始
• API 参考
• 调试模式
• 安全指南
• 错误码

支付方式

• Native 支付（扫码支付）
• APP 支付
• JSAPI 支付
• H5 支付
• 合单支付

本地预览文档

npm run docs:dev    # 开发模式
npm run docs:build  # 构建
npm run docs:preview # 预览构建结果

示例服务器

想要测试完整的支付流程？查看 示例服务器 - 一个功能完整的测试服务器：

• ✅ 创建真实支付和二维码
• ✅ 使用微信扫码完成支付
• ✅ 处理真实的 Webhook
• ✅ 查询和管理订单
• ✅ 测试所有支付状态

快速启动：

# 1. 配置环境变量
cd examples/demo
cp .env.example .env
# 编辑 .env，填入你的微信支付凭证

# 2. 启动示例服务器
npm install
npm run dev

# 3. 打开 http://localhost:3000
# 创建支付，扫描二维码，完成支付！

详见 示例服务器文档。

框架集成

查看框架集成示例：

Next.js

现代 React 框架，支持 App Router

cd examples/nextjs
npm install
npm run dev

Nuxt

直观的 Vue 全栈开发框架

cd examples/nuxt
npm install
npm run dev

详见 所有示例。

开发

# 安装依赖
npm install

# 构建 TypeScript
npm run build

# 运行单元测试
npm test

# 运行示例服务器（需要微信支付凭证）
npm run dev

# 类型检查
npm run typecheck