(微服务实战)聚合支付系统商户线上聚合收银台接口设计

1 概述

聚合支付收款分为线上和线下业务场景，本文中的商户收银台接口设计主要是指线上业务场景，线下业务场景聚合收款方式后续会进行单独设计和分析。

主流的线上支付渠道有微信支付，支付宝支付，云闪付。这三种支付渠道都有各自的线上收款产品APP支付、H5支付、小程序支付、扫码支付、公众号支付 。dtpay聚合支付系统商户收银台接口产品主要整合支付渠道不同的线上收款场景，让线上商户快速接入各渠道支付场景。
在这里插入图片描述

2 线上聚合收银台技术架构

系统采用SpringCloud,SpringCloudAalibaba微服务架构，系统采用容器化(Docker,K8S)部署,以下是技术架构使用的技术栈
在这里插入图片描述

3 商户线上聚合收银台接口

商户聚合收银台接口采用接口对接或SDK方式给到商户自助对接，收银台接口系统各参与方有商户系统、dtpay商户线上聚合收银台接口系统、支付渠道方。商户不需要对接各支付渠道的支付产品，通过聚合收银台快速完成收款方式的对接。
在这里插入图片描述

4 收银台接口设计

收银台接口主要涵盖以下接口统一下单支付接口、支付通知接口、支付查询接口

4.1 统一支付下单支付接口设计

4.1.1 请求方式

POST/JSON

4.1.2 请求参数

字段	名称	类型	长度	必输	备注
mercOrderNo	商户订单号	String	32	是	商户自己生成的唯一的订单号，商户订单号+商户号唯一
subject	订单名称	String	100	是	订单名称、订单说明两者必填其一
body	订单说明	String	200	否	订单名称、订单说明两者必填其一
tradeType	交易类型	String	2	是	01-支付 02-代付 03-提现
tradeAmt	订单金额	String	12	是	交易金额(单位元，带两位小数，例:1.23,最大整数16位)
feeType	币种	String		否	默认是CNY：人民币，当前版本暂不支持其它币种。
tradeTime	提交支付时间	String	14	是	格式[yyyyMMddHHmmss] ;
orderPeriod	订单有效时间	String	14	是	订单有效期(单位分钟)
notifyUrl	后台通知地址	String	200	是	支付成功时，后台通知商户的地址，必须为http/https协议地址
returnUrl	前台通知地址	String	200	是	支付成功是，前台页面跳转的提示页面，为空不发前台通知，必须为http/https协议地址
refererUrl	客户端地址	String	200	否	重定向地址，可直接跳转到商户页面（不会附加参数返回）
termType	终端接入类型	String	8	是	固定值：wap，pc，app
paywayCode	支付方式	String	20	是	alipay-支付宝 wxpay-微信支付 unionpay-银联支付例如：当微信支付时传值 wxpay
sceneCode	场景编号	String	20	是	h5-H5支付app-APP支付scan-扫码支付jspay-公众号支付ebank-网银支付gateway-网关支付例如：当支付场景为H5支付时传值“h5”注：当支付方式选“ebank”即网银支付时，场景编号传送值为“ebank”；
ip	客户端IP（外网IP）	String	32	是
merchantId	商户编号	String	8	否
storeId	门店编号	String	8	否
payeeId	收银员编号	String	8	否
remark	备注	String	100	否
attach	附加信息	String	128	否
deviceInfo	应用类型	String	16	否	如果是应用于苹果app,应用里值为IOS_SDK;如果是应用于安卓app,应用里值为AND_SDK;如果是应用于手机网站，应用里值为WAP_SDK，微信h5必输
mchAppName	应用名	String	256	否	如果是用于苹果或安卓app应用中，传分别对应在AppStore和安卓分发市场中的应用名（如：王者荣耀）如果是用于手机网站，传对应的网站名（如：天猫官网）微信h5必输
mchAppId	应用标识	String	128	否	如是是用于苹果或安卓app应用中，苹果传IOS应用中唯一标识（如：com.tencent.wzryIOS）,安卓传包名（如：com.tencent.tmgp.sgame）如果是用于手机网站，传网站首页URL地址，必须保证公网能正常访问（如：www.itbeien.cn）>微信h5必输
bankCode	网银银行编码	String	20	否	网银支付必传，见银行代码
payType	支付卡类型	String	1	否	1 借记卡 2 贷记卡 3借/贷记卡均可使用。网银支付传此参数，不传默认为1，即借记卡
quickPayAttach	快捷支付参数	String		否	快捷支付直连时必输

4.1.3 同步响应参数

字段	名称	类型	长度	必输	备注
mercOrderNo	商户订单号	String		是	商户自己生成的唯一的订单号
tradeType	交易类型	String		是	01-支付 11-充值 02-代付 03-提现
tradeAmt	交易金额	String		是	交易金额
tradeTime	支付提交时间	String		是	订单提交时间，格式[yyyyMMddHHmmss] ;
feeType	币种	String		是	默认是CNY：人民币，当前版本暂不支持其它币种。
termType	终端接入类型	String		是	固定值：wap，pc，app
orderId	平台订单号	String	32	是	平台订单号，可以理解成支付平台返回号
codeUrl	二维码链接	String	128	否	二维码链接扫码必输
imgUrl	二维码图片	String	128	否	二维码图片
payInfo	公众号支付信息	String	128	否	公众号支付信息
mwebUrl	H5支付地址	String	128	否	H5支付地址
bankType	付款银行	String	16	否	银行类型
resultHtml	支付form	String		否	网银支付返回必输，格式为form表单

4.1.4 响应报文实例

{"orderId":"2024061812582900001378","signature":"5974FF8536CC614F6C2XXXXXXXXXXXX","termType":"wap","mercOrderNo":"D20180315125826","tradeType":"01","codeUrl":"https://www.itbeien.cn/qr/5519dddb","respDesc":"处理成功","feeType":"CNY","mercNo":"ORG1520825458796","tradeTime":"20240618125826","interfaceCode":"pay","respCode":"000000"
}

4.2 支付通知接口

商户回调接口使用HTTPS协议可以保证数据传输的安全性，所以建议商户提供的回调接口采用HTTPS协议。商户交易完成后，由聚合收银台异步推送至商户。商户接受处理成功后，需返回给平台success。

4.2.1 通知结果参数列表

字段	名称	类型	长度	必输	备注
mercOrderNo	商户订单号	String		是	商户自己生成的唯一的订单号
tradeType	交易类型	String		是	01-支付 11-充值 02-代付 03-提现
tradeAmt	交易金额	String		是	交易金额
tradeTime	支付提交时间	String		是	订单提交时间，格式[yyyyMMddHHmmss] ;
feeType	币种	String		是	默认是CNY：人民币，当前版本暂不支持其它币种。
termType	终端接入类型	String		是	固定值：wap，pc，app
orderId	平台订单号	String	32	是	平台订单号，可以理解成支付平台返回号
tradeEndTime	交易完成时间	String		是	支付平台保证精确的支付交易完成时间。
payStatus	支付状态	String		是	p0001 :提交订单 p0002：支付中 p0000 :支付成功 p0004:支付失败 p0005:已取消 p0006:过期已作废
bankType	付款银行	String	16	否	银行类型

4.2.2 支付异步通知参数示例

{"tradeAmt":"0.01","charset":"UTF-8","orderId":"2024061812582900001378","signature":"0B5E5BAD0C447582A99618EEB0A35567","termType":"wap","mercOrderNo":"D20180315125826","feeType":"CNY","locale":"CN","tradeEndTime":"20240618125846","version":"1.0","mercNo":"ORG1520825458796","tradeTime":"20240618125828","signType":"MD5","payStatus":"p0000","tradeType":"01"
}

4.2.3 通知结果反馈

聚合收银台通过 notifyUrl 通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：

返回结果	结果说明
success	处理成功
fail	处理不成功

4.2.4 补单机制

注意：聚合收银台通知交互模式，如果聚合收银台收到商户的应答不是纯字符串success或超过5秒后返回时，聚合收银台认为通知失败，聚合收银台会通过一定的策略（通知频率为10/10/10/10/10，单位：秒）间接性重新发起通知，尽可能提高通知的成功率，但平台不保证通知最终能成功。由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。聚合收银台推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回纯字符串success。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重复插入数据造成的数据混乱。