快速开始

安装

$ npm install wechatpay-axios-plugin

下载平台公钥

NOTE

2024年Q3，微信支付官方开启了「平台公钥」平替「平台证书」方案，初始化所需的参数仅需配置上 微信支付公钥ID 及 微信支付公钥 即完全兼容支持，CLI/API下载 微信支付平台证书 已不是一个必要步骤，可略过。 微信支付公钥ID 及 微信支付公钥 均可在 微信支付商户平台 -> 账户中心 -> API安全 查看及/或下载。

下载平台证书

下载命令行需额外安装依赖 $ npm install --no-save yargs，然后执行如下命令：

$ ./node_modules/.bin/wxpay crt \
-m merchantId \
-s merchantCertificateSerial \
-f /path/to/merchant/apiclient_key.pem \
-k APIv3KeyString \
-o .

提供正确的商户号、商户API证书序列号、商户API私钥文件地址、APIv3密钥，执行后，屏幕输出样例：

The WeChatPay Platform Certificate#0
  serial=7132d72a03e93cddf8c03bbd1f37eedf********
  notBefore=Wed, 22 Apr 2020 01:43:19 GMT
  notAfter=Mon, 21 Apr 2025 01:43:19 GMT
  Saved to: ./wechatpay_7132d72a03e93cddf8c03bbd1f37eedf********.pem
You may confirm the above infos again even if this library already did(by Rsa.verify):
	openssl x509 -in ./wechatpay_7132d72a03e93cddf8c03bbd1f37eedf********.pem -noout -serial -dates

./wechatpay_7132d72a03e93cddf8c03bbd1f37eedf********.pem 即为 微信支付平台证书 文件。

重要提示

当下载证书后，屏显有几条证书信息，就在应用中配置certs几条，尤其是在新旧平台证书交替灰度时，需要把新旧证书都配上，应用才不会出现事故。

应用代码

初始化

const { Wechatpay } = require('wechatpay-axios-plugin');
const { readFileSync } = require('fs');

// 商户号，支持「普通商户/特约商户」或「服务商商户」
const merchantId = '190000****';

// 「商户API证书」的「证书序列号」
const merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';

// 从本地文件中加载「商户API私钥」，用于生成请求的签名
const merchantPrivateKeyFilePath = '/path/to/merchant/apiclient_key.pem';
const merchantPrivateKeyInstance = readFileSync(merchantPrivateKeyFilePath);

// 「微信支付平台证书」的「平台证书序列号」
// 可以从「微信支付平台证书」文件解析，也可以在 商户平台 -> 账户中心 -> API安全 查询到
const platformCertificateSerial = '7132D72A03E93CDDF8C03BBD1F37EEDF********';

// 从本地文件中加载「微信支付平台证书」，可由内置的CLI工具下载到，用来验证微信支付应答的签名
const platformCertificateFilePath  = '/path/to/wechatpay/certificate.pem';
const onePlatformPublicKeyInstance = readFileSync(platformCertificateFilePath);

// 从本地文件中加载「微信支付平台公钥」，用来验证微信支付应答的签名
const platformPublicKeyFilePath    = '/path/to/wechatpay/publickey.pem';
const twoPlatformPublicKeyInstance = readFileSync(platformPublicKeyFilePath);

// 「微信支付平台公钥」的「平台公钥ID」
// 需要在 商户平台 -> 账户中心 -> API安全 查询
const platformPublicKeyId = 'PUB_KEY_ID_01142321349124100000000000********';

// 构造一个 APIv2 & APIv3 客户端实例
const wxpay = new Wechatpay({
  mchid: merchantId,
  serial: merchantCertificateSerial,
  privateKey: merchantPrivateKeyInstance,
  certs: {
    [platformCertificateSerial]: onePlatformPublicKeyInstance,
    [platformPublicKeyId]: twoPlatformPublicKeyInstance,
  },
  // 使用APIv2(密钥32字节)时，需要至少设置 `secret`字段
  secret: 'your_merchant_secret_key_string',
  // // 接口不要求证书情形，例如仅收款merchant对象参数可选
  merchant: {
    cert: readFileSync('/path/to/merchant/apiclient_cert.pem'),
    key: merchantPrivateKeyInstance,
    // 或者配置如下配置项
    // passphrase: 'your_merchant_id',
    // pfx: readFileSync('/your/merchant/cert/apiclient_cert.p12'),
  },
});

Native下单

wxpay.v3.pay.transactions.native.post({})

详细见这里

查询订单

// _placeholder_ 语法糖会转换成 '{placeholder}' 格式
wxpay.v3.pay.transactions.id._transaction_id_.get({ transaction_id })

详细见这里

关闭订单

// $placeholder$ 语法糖会转换成 '{placeholder}' 格式
wxpay.v3.pay.transactions.outTradeNo.$out_trade_no$.close.post({}, { out_trade_no })

详细见这里

申请退款

wxpay.v3.refund.domestic.refunds.post({})

详细见这里

查询单笔退款

// _placeholder_ 语法糖会转换成 '{placeholder}' 格式
wxpay.v3.refund.domestic.refunds._out_refund_no_.get({ out_refund_no })

详细见这里