Notadd 支付插件
整合微信支付API、支付宝支付API,基于 Nest.js 框架构建的一个支付插件。
使用说明
使用前,请确保了解微信支付、支付宝支付的各类支付流程,且具备基本的 debug
能力。
安装
npm install @notadd/addon-pay
配置 PayAddon
import { Module } from '@nestjs/common';
import { PayAddon } from '@notadd/addon-pay';
@Module({
imports: [
PayAddon.forRoot({
wechatConfig: {
appid: 'appid',
mch_id: 'mch_id',
secretKey: 'secretKey',
sign_type: 'MD5',
pfx: fs.readFileSync('path_to_p12_file'),
sandbox: true
}
})
]
})
export class ApplicationModule {}
微信支付
接口使用前的必要声明:
- 所有的接口请求参数和接口返回结果中的属性名全部使用的是
snake_case
,其中属性名结尾带 ?
的代表这个属性是可选的(非必填)。 - 所有与金额相关的数据全部是
number
类型且单位为 分
,需自行转换。 - 所有接口参数中的
mch_id
、appid/wxappid
、nonce_str
、sign_type
、sign
数据均由插件自动填入,无需手动传入。 - 所有请求的返回结果若有
sign
,插件会自动验签。 - 支付通知结果插件会自动验签,退款通知结果插件会自动解密
req_info
数据。 - 微信
接口
调用的返回结果、回调通知
的返回结果中的 金额、数量 的类型会因 xml2js
工具解析后全部转换为字符串,需开发者手动转换类型。
使用 WeChatXXX
PayService 调用 API
WeChatXXX
PayService 类包含当前支付方式的支付、订单、退款相关 API,各支付类说明:
- WeChatAppPayService —— APP支付
- WeChatAppletPayService —— 小程序支付
- WeChatJSAPIPayService —— JSAPI支付(用户通过微信扫码、关注公众号等方式进入商家H5页面,并在微信内调用JSSDK完成支付)
- WeChatMicroPayService —— 付款码支付(用户打开微信钱包-付款码的界面,商户扫码后提交完成支付)
- WeChatNativePayService —— Native支付(扫码支付)
- WeChatWapPayService —— H5支付(用户在微信以外的手机浏览器请求微信支付的场景唤起微信支付)
- WeChatRedpackService —— 现金红包
- WeChatTransferService —— 企业付款
例子:Native支付(扫码支付)调用方式如下
import { Injectable, Inject } from '@nestjs/common';
import { WeChatNativePayService, WeChatTradeType } from '@notadd/addon-pay';
@Injectable()
export class TestPay {
constructor(@Inject(WeChatNativePayService) private readonly weChatNativePayService: WeChatNativePayService) { }
async nativePay() {
const ressult = await this.weChatNativePayService.pay({
body: '支付一下',
out_trade_no: '201811271512000001',
total_fee: 301,
spbill_create_ip: '127.0.0.1',
notify_url: 'your.domain.com/payment/wechat_order_notify',
trade_type: WeChatTradeType.JSAPI
});
}
}
使用 WeChatNotifyParserUtil 解析支付/退款通知
支付/退款完成后,微信会把相关支付/退款结果和用户信息发送给商户,商户需要接收处理,并返回应答。
对后台通知交互时,如果微信收到商户的应答不是成功或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为15/15/30/180/1800/1800/1800/1800/3600,单位:秒)
注意:同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是,当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回结果成功。在对业务数据进行状态检查和处 理前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。
import { Controller, Inject, Post, Req, Res } from '@nestjs/common';
import { WeChatNotifyParserUtil } from '@notadd/addon-pay';
@Controller('payment')
export class PaymentNotifyController {
constructor(
@Inject(WeChatNotifyParserUtil) private readonly weChatNotifyParserUtil: WeChatNotifyParserUtil
) { }
@Post('wechat_order_notify')
async weChatOrderNotify(@Req() req, @Res() res) {
const data = await this.weChatNotifyParserUtil.parsePayNotify(req);
if (!data) {
res.end(this.weChatNotifyParserUtil.generateFailMessage('验签失败'));
}
if(data.return_code === 'FAIL') {
}
if(data.result_code === 'FAIL') {
}
res.end(this.weChatNotifyParserUtil.generateSuccessMessage());
}
@Post('wechat_refund_notify')
async weChatRefundNotify(@Req() req) {
const data = await this.weChatNotifyParserUtil.parseRefundNotify(req);
if (!data) {
return this.weChatNotifyParserUtil.generateFailMessage('解密失败');
}
if(data.return_code === 'FAIL') {
}
return this.weChatNotifyParserUtil.generateSuccessMessage();
}
}
使用 WeChatSignUtil 计算签名
在个别支付方式中,需要服务端计算签名并返回给客户端时,使用插件提供的 WeChatSignUtil
工具类即可计算签名:
import { Injectable, Inject } from '@nestjs/common';
import { WeChatSignUtil } from '@notadd/addon-pay';
@Injectable()
export class TestSign {
constructor(@Inject(WeChatSignUtil) private readonly weChatSignUtil: WeChatSignUtil) { }
async testWechatSign() {
const params = { appid: 'xxxxx', openid: 'xxxxx' };
const sign = await this.weChatSignUtil.sign(params);
}
}
如何使用支付验收 case ?
两种方式,如下:
- 关注微信公众号:微信支付商户接入验收助手,并查阅相应支付验收 case 示例。
- 下载支付验收case示例 pdf 文档。地址:免充值产品测试验收用例 。
支付宝支付
TODO
随机字符生成工具
支付插件内使用了 nanoid 作为随机字符生成工具,开发者可以通过注入 RandomUtil
,即可使用该工具。
import { Injectable, Inject } from '@nestjs/common';
import { RandomUtil } from '@notadd/addon-pay';
@Injectable()
export class TestSign {
constructor(@Inject(RandomUtil) private readonly randomUtil: RandomUtil) { }
async testRandomStr() {
const randomStr = await this.randomUtil.genRandomStr();
}
}
贡献说明
我们欢迎 Nest.js 使用者来参与这个插件的开发,作为一个贡献者,请您遵循以下原则:
- 代码提交规范,参考 Git Commit Message Conventions
- 始终从 develop checkout 一个新分支,命名规范为 feature/xxx,xxx 必须具有可读性,如:微信-普通商户版-扫码支付 => feature/wechat-native-pay
- 在 checkout 新分支前,先在本地 develop 分支拉取远程 develop 分支的最新代码
- 文件命名规则请参考项目目前的命名规则,如:微信支付中,order.interface.ts 代表所有订单相关的请求参数和返回结果的定义,micro.pay.service.ts 代表付款码支付的业务逻辑
功能开发
请先查阅 Roadmap,确保你想贡献的功能没有正在被实现。然后在 issue 里提交一个贡献请求,注明想要贡献的功能。
发现 Bug ?
如果你在源码中发现bug,请你先在本仓库的 issue 提交一个bug问题。在你提交完bug问题后,我们很乐意接受你提交一个 PR 来帮助我们修复这个bug。
QQ 交流群
322247106,请注明加群目的!
Roadmap