支付接口

1. 协议规则

传输方式：采用HTTP传输(生产环境建议HTTPS)
提交方式：采用POST/GET方式提交
字符编码：UTF-8
签名算法：MD5

1.1 参数规范

交易金额：默认为人民币交易，单位为分，参数值不能带小数。

1.2 安全规范

签名算法

签名生成的通用步骤如下

第一步： 设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。
特别注意以下重要规则：
◆ 参数名ASCII码从小到大排序（字典序）；
◆ 如果参数的值为空不参与签名；
◆ 参数名区分大小写；
◆ 验证调用返回或支付中心主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验。
◆ 支付中心接口可能增加字段，验证签名时必须支持增加的扩展字段

第二步： 在stringA最后拼接上key[即 StringA + "&key=" + 私钥 ] 得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

如请求支付系统参数如下：

1. Map signMap = new HashMap<>();
2. signMap.put("userId", "test01");
3. signMap.put("type", "wechat");
4. signMap.put("money", Double.valueOf(2));
5. signMap.put("remark", "");
6. signMap.put("outTradeNo", "P12312321123");

待签名值：money=2.0&outTradeNo=P12312321123&type=wechat&userId=test01&key=EWEFD123RGSRETYDFNGFGFGSHDFGH
签名结果：5E0AA05DD4BB4FE5AB65608123EBA591
最终请求支付系统参数：money=2.0&outTradeNo=P12312321123&type=wechat&userId=test01&sign=5E0AA05DD4BB4FE5AB65608123EBA591

商户登录商户系统后，通过商户信息查看或修改私钥key。

2. 统一下单

接口描述

业务通过统一下单接口可以发起任意三方支付渠道的支付订单。业务系统不必关心该如何调用三方支付，统一下单接口会根据业务系统选择的支付渠道ID，选择对应支付渠道的支付产品，发起下单请求，然后响应给业务系统支付请求所需参数。

接口链接

URL地址：{payUrl}/api/pay/create_order

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	20001222	支付中心分配的商户号
应用ID	appId	否	String(30)	wx390ee383939c4fb2	当支付产品为微信支付(公众号支付、小程序支付、H5支付、APP支付)时，如果传了该参数则微信服务商下单时subAppId使用该参数，如果支付产品为微信APP支付则该参数必传
支付产品ID	productId	是	String(24)	8001	8004微信公众号支付，8020微信条码支付，8023微信小程序支付、8008支付宝服务窗支付、8021支付宝条码支付
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	int	100	支付金额,单位分
币种	currency	是	String(3)	cny	三位货币代码,人民币:cny
客户端IP	clientIp	否	String(32)	210.73.10.148	客户端IP地址,当为微信公众号支付或微信小程序支付时该参数必传
设备	device	否	String(64)	ios10.3.1	客户端设备
异步回调通知地址	notifyUrl	否	String(128)	http://shop.xx.com/api/notice	异步回调通知地址
支付结果同步请求URL	returnUrl	否	String(128)	http://shop.xx.com/api/notice	支付结果同步请求URL
商品主题	subject	是	String(64)	测试商品1	商品主题
商品描述	body	是	String(256)	测试商品描述	商品描述信息
渠道用户ID	channelUserId	否	String(256)	oIkQuwhPgPUgl-TvQ48_UUpZUwMs	指的是在支付通道测的用户ID，当为微信公众号或小程序支付时，该参数必填，指微信openID
是否jsapi的预下单模式	jsApiPreOrderMode	否	int	0	是否jsapi的预下单模式 1.是, 0-否   预下单模式不直接生成payOrderId, 返回链接地址直接支付。 仅支持 微信公众号支付和支付宝服务窗支付 京东H5和云闪付扫一扫支付。
附加参数	extra	否	String(512)	134586944573118714	特定渠道发起时额外参数，当为微信条码或支付宝条码支付时，该参数必填，指付款用户的条码值
扩展参数1	param1	否	String(64)		支付中心回调时原样返回
扩展参数2	param2	否	String(64)		支付中心回调时原样返回
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

响应结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	0	0-处理成功，其他-处理有误，详见错误码
返回信息	retMsg	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误

以下字段在retCode=0 时有返回

字段名	变量名	必填	类型	示例值	描述
支付订单号	payOrderId	是	String(30)	P01201907231119090520000	返回支付系统订单号
支付方式	payMethod	是	String(16)	formJump	支付方式，目前包含两种： formJump-表单跳转，codeImg-二维码图片
支付表单地址	payUrl	否	text	<form name="punchout_form" method="post" action="https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.page.pay&sign=WWg59GEcTkMHYnE8fKRd%2F4fzFi"></form> ……	payMethod=formJump时存在该参数； 一般为支付表单内容
支付跳转地址	payJumpUrl	否	text		支付跳转地址，可直接重定向的URL
表单提交方式	payAction	否	String(16)	GET	指定表单提交方式: POST/GET
二维码地址	codeUrl	否	String(16)	https://qr.alipay.com/bax08687odiyi06c	payMethod=codeImg时存在该参数； 二维码内容地址
二维码图片地址	codeImgUrl	否	String(16)	http://pay.52pay.com/api/qrcode_img_get?url=https://qr.alipay.com/bax08687z006c&width=200&height=200	payMethod=codeImg时存在该参数； 二维码图片地址
支付自定义参数	payParams	否	String(16)		支付自定义参数，当为app支付或小程序或公众号支付时，返回给客户端调起支付所需参数
是否需要查单	needQuery	否	Boolean	true	如果返回true则表示商户需要主动发起订单查询
当前订单状态	orderStatus	否	String(16)	2	当前订单状态: -2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款
签名信息	sign	是	String(128)	CCD9083A6DAD9A2DA9F668C3D4517A84	签名信息

3. 查询支付订单

接口描述

业务系统通过查询支付订单接口获取最新的支付订单状态，并根据状态结果进一步处理业务逻辑。

接口链接

URL地址：{payUrl}/api/pay/query_order

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	1000000010	支付中心分配的商户号
支付订单号	payOrderId	是	String(30)	P20160427210604000490	支付中心生成的订单号，与mchOrderNo二者传一即可
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号，与payOrderId二者传一即可
是否执行回调	executeNotify	否	Boolean	true	是否执行回调，如果为true，则支付中心会再次向商户发起一次回调，如果为false则不发起
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

响应结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	0	0-处理成功，其他-处理有误，详见错误码
返回信息	retMsg	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误

以下字段在retCode=0 时有返回

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	20001222	支付中心分配的商户号
应用ID	appId	否	String(30)	wx390ee383939c4fb2	应用ID
支付产品ID	productId	是	String(24)	8001
支付订单号	payOrderId	是	String(30)	P01201907231119090520000	返回支付系统订单号
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	int	100	支付金额,单位分
币种	currency	是	String(3)	cny	三位货币代码,人民币:cny
订单状态	status	是	String(3)	2	当前订单状态: -2:订单已关闭,0-订单生成,1-支付中,2-支付成功,3-业务处理完成,4-已退款
渠道用户ID	channelUserId	否	String		渠道用户ID
渠道订单号	channelOrderNo	否	String wx20170910211043fb206e92260071822007	对应的第三方支付订单号
渠道数据包	channelAttach	否	String		渠道数据包
支付成功时间	paySuccTime	否	Long	1505049094262	支付成功时间，精确到毫秒
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

4. 关闭支付订单

接口描述

业务系统通过关闭支付订单接口关闭支付订单，只有在支付中的订单才可以发起关闭。

接口链接

URL地址：{payUrl}/api/pay/close_order

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	1000000010	支付中心分配的商户号
支付订单号	payOrderId	是	String(30)	P20160427210604000490	支付中心生成的订单号，与mchOrderNo二者传一即可
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号，与payOrderId二者传一即可
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

响应结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	0	0-处理成功，其他-处理有误，详见错误码
返回信息	retMsg	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误

以下字段在retCode=0 时有返回

字段名	变量名	必填	类型	示例值	描述
业务结果	resultCode	是	String	SUCCESS	SUCCESS/FAIL
处理结果描述	resultMsg	否	String	失败	失败
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

5. 支付结果通知

接口描述

当订单支付成功时，支付中心会向商户的returnUrl地址发起回调，通知订单状态。

接口链接

该链接是通过统一下单接口提交的参数returnUrl设置，如果无法访问链接，业务系统将无法接收到支付中心的通知。

通知参数

字段名	变量名	必填	类型	示例值	描述
支付订单号	payOrderId	是	String(30)	P20160427210604000490	支付中心生成的订单号
商户ID	mchId	是	String(30)	20001222	支付中心分配的商户号
支付产品ID	productId	是	String(24)	8001
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	int	100	支付金额,单位分
状态	status	是	int	1	支付状态,0-订单生成,1-支付中,2-支付成功,3-业务处理完成
渠道订单号	channelOrderNo	否	String(64)	wx2016081611532915ae15beab0167893571	三方支付渠道订单号
支付成功时间	paySuccTime	是	long		精确到毫秒

返回结果

业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为60/120/180/240/300,单位：秒）

注意：返回的字符串必须是小写，且前后不能有空格。

6. 支付产品

产品ID	产品名称
8004	微信公众号支付
8020	微信条码支付
8023	微信小程序支付
8008	支付宝服务窗支付
8021	支付宝条码支付

7. 错误码

RetCode	描述
0	成功
9999	业务异常，具体错误详见RetMsg字段
0100	商户签名异常
0010	系统错误
0011	请使用post方法
0012	post数据为空
0013	签名错误
0014	参数错误
0015	商户不存在
0110	第三方超时
0111	第三方异常
0112	订单不存在
0113	订单已支付
0114	商品不存在
0115	价格不对
0116	物品数量不对
0117	过程返回255
0118	DB错误
0119	支付中心没有对应的渠道
0120	修改订单状态失败