wx_pay_v3说明文档

前言

暂时对接了部分使用频率比较高的接口，如果在使用中发现问题，可📮wx.open@qq.com邮箱联系我

安装

1npm install @chenbz/wx_pay_v3

实例化

1const { WxPayV3 } = require('@chenbz/wx_pay_v3');
2
3const payConfig = {
4    appId: '', // 应用ID
5    mchId: '', // 商户ID
6    apiKeyV3: '', // API_v3密钥
7    serialNo: '', // API证书序列号
8    privateKey: '', // API证书私钥
9    publicKey: '', // API证书公钥
10    payNotifyUrl: '', // 支付回调地址
11    refundNotifyUrl: '', // 退款回调地址
12  };
13
14const pay = new WxPayV3(payConfig);

必填参数说明

属性	描述	指引
appId	应用ID	🌈 直达链接
mchId	商户号ID	🌈 直达链接
apiKeyV3	API_v3密钥	🌈 直达链接
serialNo	API证书序列号	🌈 官方教程
privateKey	API证书私钥	🌈 官方教程
publicKey	API证书公钥	🌈 官方教程
payNotifyUrl	支付回调地址	开发者自行开发
refundNotifyUrl	退款回调地址	开发者自行开发

函数列表

函数名称	描述
createSignature	生成签名
getAuthorization	请求头token
verifySignature	验证签名（用于验证回调消息签名）
decryptAES	解密AES（用于解密回调消息主体）
createOrderNo	生成订单号（使用uuid确保唯一性）
jsApi	jsApi
jsApiPay	jsApi支付
wmpPay	微信小程序支付
h5Pay	h5支付
nativePay	native支付
appPay	app支付
getOrderByTransactionId	根据微信支付订单号查询
getOrderByOutTradeNo	根据商户订单号查询
closeOrderByOutTradeNo	关闭订单
refundDomesticByTransactionId	根据"微信支付订单号"退款
refundDomesticByOutTradeNo	根据"商户订单号"退款
getRefundDomesticByOutRefundNo	查询单笔退款
getTradeBill	获取申请交易账单
getFundFlowBill	获取申请资金账单
downloadTradeBill	下载申请交易账单
downloadFundFlowBill	下载申请资金账单
transferBatches	发起商户转账
getCertificates	获取平台证书列表

感谢

如果可以，来瓶快乐水

函数说明

verifySignature(验证签名)

使用场景

用于验证支付回调和退款回调是否来自官方，强烈建议！！回调均验证

参数

参数	描述	说明
signature	签名	http请求头['wechatpay-signature']
timestamp	时间戳	http请求头['wechatpay-timestamp']
nonce	随机字符串	http请求头['wechatpay-nonce']
data	回调数据	应答主体

使用示例

1// 不同框架获取请求头的方式不同，示例使用的框架是egg
2
3const signature = ctx.request.header['wechatpay-signature'];
4const timestamp = ctx.request.header['wechatpay-timestamp'];
5const nonce = ctx.request.header['wechatpay-nonce'];
6const data = ctx.request.body;
7
8pay.verifySignature(signature, timestamp, nonce, data);  // true

decryptAES(解密AES)

使用场景

用于解密支付回调和退款回调

示例：支付成功结果通知

1{
2    "id": "EV-2018022511223320873",
3    "create_time": "2015-05-20T13:29:35+08:00",
4    "resource_type": "encrypt-resource",
5    "event_type": "TRANSACTION.SUCCESS",
6    "summary": "支付成功",
7    "resource": {
8        "original_type": "transaction",
9        "algorithm": "AEAD_AES_256_GCM",
10        "ciphertext": "",
11        "associated_data": "",
12        "nonce": ""
13    }
14}

参数

参数	描述	说明
cipherText	密文	resource.ciphertext
add	associated_data字符串	resource.associated_data
iv	nonce字符串	resource.nonce

使用示例

1// 示例使用的框架是egg
2
3const data = ctx.request.body;
4
5const { ciphertext: cipherText, associated_data: add, nonce: iv } = data.resource;
6
7pay.decryptAES(cipherText, add, iv);

createOrderNo(生成订单号[使用uuid确保唯一性])

使用场景

生成订单号

参数

null

使用示例

1pay.createOrderNo();  // s3r6a23m8d124dcaa12f2c862c82117e

jsApiPay(jsApi支付)

使用场景

JsSDk支付

参数

参数	描述	说明
outTradeNo	商户订单号	可调用"createOrderNo()"方法生成
payerOpenId	用户在直连商户appId下的唯一标识	openid
amountTotal	订单总金额(单位:分)
description	商品描述
options	可覆盖已有参数	🔍可选

使用示例

1const outTradeNo = pay.createOrderNo();
2const payerOpenId = '';
3const amountTotal = 1;
4const description = '测试商品';
5
6pay.jsApiPay(outTradeNo, payerOpenId, amountTotal, description)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

wmpPay(微信小程序支付)

使用场景

微信小程序支付

参数

参数	描述	说明
outTradeNo	商户订单号	可调用"createOrderNo()"方法生成
payerOpenId	用户在直连商户appId下的唯一标识	openid
amountTotal	订单总金额(单位:分)
description	商品描述
options	可覆盖已有参数	🔍可选

使用示例

1const outTradeNo = pay.createOrderNo();
2const payerOpenId = '';
3const amountTotal = 1;
4const description = '测试商品';
5
6pay.wmpPay(outTradeNo, payerOpenId, amountTotal, description)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

h5Pay(h5支付)

使用场景

h5支付

参数

参数	描述	说明
outTradeNo	商户订单号	可调用"createOrderNo()"方法生成
amountTotal	订单总金额(单位:分)
description	商品描述
payerClientIp	用户的客户端IP,支持IPv4和IPv6两种格式的IP地址
options	可覆盖已有参数	🔍可选

使用示例

1const outTradeNo = pay.createOrderNo();
2const amountTotal = 1;
3const description = '测试商品';
4const payerClientIp = '127.0.0.1';
5
6pay.h5Pay(outTradeNo, amountTotal, description, payerClientIp)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

nativePay(native支付)

使用场景

native支付

参数

参数	描述	说明
outTradeNo	商户订单号	可调用"createOrderNo()"方法生成
amountTotal	订单总金额(单位:分)
description	商品描述
options	可覆盖已有参数	🔍可选

使用示例

1const outTradeNo = pay.createOrderNo();
2const amountTotal = 1;
3const description = '测试商品';
4
5pay.nativePay(outTradeNo, amountTotal, description)
6  .then((res) => {
7    console.log(res);
8  })
9  .catch((err) => {
10    console.log(err);
11  });

appPay(app支付)

使用场景

appPay

参数

参数	描述	说明
outTradeNo	商户订单号	可调用"createOrderNo()"方法生成
amountTotal	订单总金额(单位:分)
description	商品描述
options	可覆盖已有参数	🔍可选

使用示例

1const outTradeNo = pay.createOrderNo();
2const amountTotal = 1;
3const description = '测试商品';
4
5pay.appPay(outTradeNo, amountTotal, description)
6  .then((res) => {
7    console.log(res);
8  })
9  .catch((err) => {
10    console.log(err);
11  });

getOrderByTransactionId(根据微信支付订单号查询)

使用场景

订单查询

参数

参数	描述	说明
transactionId	微信支付订单号	支付成功后由微信支付生成返回

使用示例

1const transactionId = '';
2
3pay.getOrderByTransactionId(transactionId)
4  .then((res) => {
5    console.log(res);
6  })
7  .catch((err) => {
8    console.log(err);
9  });

getOrderByOutTradeNo(根据商户订单号查询)

使用场景

订单查询

参数

参数	描述	说明
outTradeNo	下单的时候由商户号生成	前面使用pay.createOrderNo()生成的订单号

使用示例

1const outTradeNo = '';
2
3pay.getOrderByOutTradeNo(outTradeNo)
4  .then((res) => {
5    console.log(res);
6  })
7  .catch((err) => {
8    console.log(err);
9  });

closeOrderByOutTradeNo(关闭订单)

使用场景

关闭订单

参数

参数	描述	说明
outTradeNo	下单的时候由商户号生成	前面使用pay.createOrderNo()生成的订单号

使用示例

1const outTradeNo = '';
2
3pay.closeOrderByOutTradeNo(outTradeNo)
4  .then((res) => {
5    console.log(res);
6  })
7  .catch((err) => {
8    console.log(err);
9  });

refundDomesticByTransactionId(根据"微信支付订单号"退款)

使用场景

退款

参数

参数	描述	说明
transactionId	微信支付订单号	支付成功后由微信支付生成返回
outRefundNo	商户退款单号	可调用"createOrderNo()"方法生成
amountTotal	原订单金额	原支付交易的订单总金额
amountRefund	退款金额	不能超过原订单支付金额
options	可覆盖已有参数	🔍可选

使用示例

1const transactionId = '';
2const outRefundNo = pay.createOrderNo();
3const amountTotal = 1;
4const amountRefund = 1;
5
6pay.refundDomesticByTransactionId(transactionId, outRefundNo, amountTotal, amountRefund)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

refundDomesticByOutTradeNo(根据"商户订单号"退款)

使用场景

退款

参数

参数	描述	说明
outTradeNo	商户订单号	前面使用pay.createOrderNo()生成的订单号
outRefundNo	商户退款单号	可调用"createOrderNo()"方法生成
amountTotal	原订单金额	原支付交易的订单总金额
amountRefund	退款金额	不能超过原订单支付金额
options	可覆盖已有参数	🔍可选

使用示例

1const outTradeNo = '';
2const outRefundNo = pay.createOrderNo();
3const amountTotal = 1;
4const amountRefund = 1;
5
6pay.refundDomesticByOutTradeNo(outTradeNo, outRefundNo, amountTotal, amountRefund)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

getRefundDomesticByOutRefundNo(查询单笔退款)

使用场景

查询单笔退款

参数

参数	描述	说明
outRefundNo	商户退款单号

使用示例

1const outRefundNo = '';
2
3pay.getRefundDomesticByOutRefundNo(outRefundNo)
4  .then((res) => {
5    console.log(res);
6  })
7  .catch((err) => {
8    console.log(err);
9  });

getTradeBill(获取申请交易账单)

使用场景

获取申请交易账单

参数

参数	描述	说明
billDate	账单日期	示例：2022-09-29
billType	账单类型	ALL || SUCCESS || FUND
tarType	压缩类型	GZIP

使用示例

1const billDate = '2022-09-29';
2// [ALL：返回当日所有订单信息（不含充值退款订单）] [SUCCESS：返回当日成功支付的订单（不含充值退款订单）] [REFUND：返回当日退款订单（不含充值退款订单）]
3const billType = 'ALL';
4const tarType = 'GZIP';
5
6pay.getTradeBill(billDate, billType, tarType)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

getTradeBill(获取申请资金账单)

使用场景

获取申请交易账单

参数

参数	描述	说明
billDate	账单日期	示例：2022-09-29
accountType	资金账户类型	BASIC || OPERATION || FEES
tarType	压缩类型	GZIP

使用示例

1const billDate = '2022-09-29';
2// [BASIC：基本账户] [OPERATION：运营账户] [FEES：手续费账户]
3const accountType = 'BASIC';
4const tarType = 'GZIP';
5
6pay.getFundFlowBill(billDate, accountType, tarType)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

downloadTradeBill(下载申请交易账单)

使用场景

下载申请交易账单

参数

参数	描述	说明
billDate	账单日期	示例：2022-09-29
billType	账单类型	ALL || SUCCESS || FUND
tarType	压缩类型	GZIP

使用示例

1const billDate = '2022-09-29';
2// [ALL：返回当日所有订单信息（不含充值退款订单）] [SUCCESS：返回当日成功支付的订单（不含充值退款订单）] [REFUND：返回当日退款订单（不含充值退款订单）]
3const billType = 'ALL';
4const tarType = 'GZIP';
5
6pay.downloadTradeBill(billDate, billType, tarType)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

downloadFundFlowBill(下载申请资金账单)

使用场景

下载申请资金账单

参数

参数	描述	说明
billDate	账单日期	示例：2022-09-29
accountType	资金账户类型	BASIC || OPERATION || FEES
tarType	压缩类型	GZIP

使用示例

1const billDate = '2022-09-29';
2// [BASIC：基本账户] [OPERATION：运营账户] [FEES：手续费账户]
3const accountType = 'BASIC';
4const tarType = 'GZIP';
5
6pay.downloadFundFlowBill(billDate, accountType, tarType)
7  .then((res) => {
8    console.log(res);
9  })
10  .catch((err) => {
11    console.log(err);
12  });

transferBatches(发起商户转账)

使用场景

发起商户转账

参数

参数	描述	说明
outBatchNo	商户批次单号	可调用"createOrderNo()"方法生成
batchName	批次名称	openid
batchRemark	批次备注
transferDetailList	转账明细列表	数组
options	可覆盖已有参数	🔍可选

transferDetailList属性说明

属性	描述	说明
out_detail_no	商家明细单号	可调用"createOrderNo()"方法生成
transfer_amount	转账金额(单位:分)
transfer_remark	转账备注
openid	openid是微信用户在公众号appid下的唯一用户标识	openid
user_name	收款用户姓名	明细转账金额 >= 2,000元，收款用户姓名必填

使用示例

1const outBatchNo = pay.createOrderNo();
2const batchName = '活动1';
3const batchRemark = '测试活动1转账';
4const transferDetailList = [
5  {
6    out_detail_no: pay.createOrderNo(),
7    transfer_amount: 1,
8    transfer_remark: '中奖用户1',
9    openid: ''
10  }
11]
12
13pay.transferBatches(outBatchNo, batchName, batchRemark, transferDetailList)
14  .then((res) => {
15    console.log(res);
16  })
17  .catch((err) => {
18    console.log(err);
19  });

getCertificates(获取平台证书列表)

使用场景

定期检查证书 => 提前更换证书

参数

null

使用示例

1pay.getCertificates()
2  .then((res) => {
3    console.log(res);
4  })
5  .catch((err) => {
6    console.log(err);
7  });