微信支付 for nodejs
中间件
- 支付结果通知, 退款结果通知获取前端支付参数
- 支持JSSDK, WeixinJSBridge, 小程序, APP微信支付
扫码支付
微信红包
企业付款
微信对帐单下载
- 支持数据格式化
使用前必读
版本要求
nodejs >= 8.3.0
关于传入值和微信返回值的数据类型
因涉及金额等敏感问题, API和中间件并没有对数据字段做类型转换
微信返回值XML做JSON转换之后的字段均为字符串类型, 请自行转换后再进行数据运算
重点关注问题
- 字符串与数字运算结果问题
'1' + 0 = '10'
- 金额单位问题
微信支付中传入的金额单位为分
关于错误
API和中间件均对所有错误进行了处理, 统一通过error返回, 包括:
网络类错误
- 网络中断, 连接超时等微信返回值检验错误
- 微信返回值非法(伪造请求等, 可能性非常低)业务逻辑错误
- 订单重复, 退款金额大于支付金额等其它错误
- 应传参数未传入等
关于返回值
未出错时正常返回为JSON格式数据
- 特殊情况:
downloadBill
下载对帐单, 返回值为字符串文本
安装
npm i tenpay # 如已安装旧版, 重新安装最新版npm i tenpay@latest
实例化
const tenpay = ;const config = appid: '公众号ID' mchid: '微信商户号' partnerKey: '微信支付安全密钥' pfx: notify_url: '支付回调网址' spbill_create_ip: 'IP地址';const api = config; // init调用: 用于多帐号省略new关键字, tenpay.init(config)返回一个新的实例对象await tenpay;
config说明:
appid
- 公众号ID(必填)mchid
- 微信商户号(必填)partnerKey
- 微信支付安全密钥(必填, 在微信商户管理界面获取)pfx
- 证书文件(选填, 在微信商户管理界面获取)- 当不需要调用依赖证书的API时可不填此参数
- 若业务流程中使用了依赖证书的API则需要在初始化时传入此参数
notify_url
- 支付结果通知回调地址(选填)- 可以在初始化的时候传入设为默认值, 不传则需在调用相关API时传入
- 调用相关API时传入新值则使用新值
spbill_create_ip
- IP地址(选填)- 可以在初始化的时候传入设为默认值, 不传则默认值为
127.0.0.1
- 调用相关API时传入新值则使用新值
- 可以在初始化的时候传入设为默认值, 不传则默认值为
关于可选参数的最佳实践:
- 如业务流程中用到含证书请求的API, 则必须在初始时传入pfx参数
- 如回调地址不需要按业务变化, 建议在初始化时传入统一的回调地址
- 如IP地址不需要按业务变化, 建议在初始化时传入统一的IP地址
中间件・微信通知(支付结果/退款结果)
- middleware参数:
pay<支付结果通知, 默认>
refund<退款结果通知>
- 需自行添加bodyParser接收post data
- reply()会自动封装SUCCESS消息, reply('some error_msg')会自动封装FAIL消息
Express中使用
app; router;
Koa中使用
app; router;
API 列表
- 某些API预设了某些必传字段的默认值, 调用时不传参数则使用默认值
- 初始化时已传入的参数无需调用时重复传入, 如
appid
mchid
- 签名(sign)会在调用API时自动处理, 无需手动传入
- 随机字符串(nonce_str)会在调用API时自动处理, 无需手动传入
getPayParams: 获取微信JSSDK支付参数(自动下单, 兼容小程序)
let result = await api;
相关默认值:
trade_type
- JSAPI
getPayParamsByPrepay: 获取微信JSSDK支付参数(通过预支付会话标识, 兼容小程序)
// 该方法需先调用api.unifiedOrder统一下单, 获取prepay_id;let result = await api;
getAppParams: 获取APP支付参数(自动下单)
let result = await api;
相关默认值:
trade_type
- APP
getAppParamsByPrepay: 获取APP支付参数(通过预支付会话标识)
// 该方法需先调用api.unifiedOrder统一下单<注意传入trade_type: 'APP'>, 获取prepay_id;let result = await api;
micropay: 扫码支付
let result = await api;
unifiedOrder: 微信统一下单
let result = await api;
相关默认值:
trade_type
- JSAPInotify_url
- 默认为初始化时传入的值或空spbill_create_ip
- 默认为初始化时传入的值或127.0.0.1
orderQuery: 查询订单
let result = await api;
reverse: 撤消订单
let result = await api;
closeOrder: 关闭订单
let result = await api;
refund: 申请退款
let result = await api;
相关默认值:
op_user_id
- 默认为商户号(此字段在小程序支付文档中出现)
refundQuery: 查询退款
let result = await api;
downloadBill: 下载对帐单
/** * 新增一个format参数(默认: false), 用于自动转化帐单为json格式 * json.total_title: 统计数据的标题数组 - ["总交易单数","总交易额","总退款金额", ...], * json.total_data: 统计数据的数组 - ["3", "88.00", "0.00", ...], * json.list_title: 详细数据的标题数组 - ["交易时间","公众账号ID","商户号", ...], * json.list_data: 详细数据的二维数据 - [["2017-12-26 19:20:39","wx12345", "12345", ...], ...] */let result = await api;
相关默认值:
bill_type
- ALLformat
- false
transfers: 企业付款
let result = await api;
相关默认值:
check_name
- OPTION_CHECKspbill_create_ip
- 默认为初始化时传入的值或127.0.0.1
transfersQuery: 查询企业付款
let result = await api;
sendRedpack: 发放普通红包
let result = await api;
相关默认值和其它说明:
mch_billno
- 商户内部订单号(传入则mch_autono失效)mch_autono
- 当日10位唯一数字, 用于自动处理商户内部订单号逻辑total_num
- 1client_ip
- 默认为初始化时的spbill_create_ip参数值或127.0.0.1
scene_id
- 空, 当红包金额大于200元
时必传
sendGroupRedpack: 发放裂变红包
let result = await api;
相关默认值和其它说明:
mch_billno
- 商户内部订单号(传入则mch_autono失效)mch_autono
- 当日10位唯一数字, 用于自动处理商户内部订单号逻辑total_num
- 3, 分裂红包要求值为3~20之间amt_type
- ALL_RANDscene_id
- 空, 当红包金额大于200元
时必传(文档中未说明)
redpackQuery: 查询红包记录
api;
相关默认值:
bill_type
- MCHT