扫码支付API接口说明文档.docx
《扫码支付API接口说明文档.docx》由会员分享，可在线阅读，更多相关《扫码支付API接口说明文档.docx（22页珍藏版）》请在冰点文库上搜索。
扫码支付API接口说明文档
扫码支付API接口开发指南
商户接口规
版本（3.0.7）
修订时间：
2017-08-01
第一章文档描述
1、文档说明
本说明文档用于指导商户接入扫码支付API系统进行的对接，目前支持支付宝、微信扫码。
请相关技术人员详细阅读本文档。
2、阅读对象
商户开发人员。
扫码支付API接口相关技术人员。
3、名词定义
合作方：
指对接扫码支付平台的机构。
商户：
指委托收单的营业机构，如超市、便利店等。
用户：
指在商户系统进行消费的企业或者个人。
商户ID：
指支付系统为使用外部接入接口的商户统一分配的唯一标识。
商户密钥：
指商户在和支付系统进行数据签名认证的密钥，采用RSA加密算法。
第二章接口定义
1、扫码支付
1、接入URL：
118.178.126.35:
8088/payservice/pay/smzf
2、接入方式：
POST方式均可
3、请求协议参数：
参数名
参数
数据类型
必填
说明
订单ID
orderId
VARCHAR
Y
交易订单ID
支付通道
payType
VARCHAR
Y
支付通道：
WXZF-微信支付，ZFBZF-支付宝支付
商户编码
merchantCode
VARCHAR
Y
商户编码，接入时系统分配
交易金额
totalAmount
VARCHAR
Y
交易金额，单位：
元，最小2元
交易标题
subject
VARCHAR
Y
交易标题，显示在微信或支付宝支付页面
交易描述
desc
VARCHAR
Y
交易描述
商户操作员id
operatorId
VARCHAR
N
操作员编号，如员工编码
门店编号
storeId
VARCHAR
N
商户的门店编号
商户终端编号
terminalId
VARCHAR
Y
商户机器的终端编号
支付方式
limitPay
VARCHAR
N
微信/支付宝：
1-不能使用信用卡
支付宝：
2-不适用花呗
3-不使用信用卡/花呗
来源信息
source
VARCHAR
N
支付宝分配给下游的pid识别号，2088开头的一串16位数字,对应支付宝的sys_service_provider_id字段
商品标记
goodsTag
VARCHAR
N
微信渠道可选上送，代金券或立减优惠功能参数，对应微信的goods_tag字段
支付宝目前用不到该参数。
支付有效时间
expireTime
VARCHAR
N
指定订单的支付有效时间（分钟数），超过有效时间用户将无法支付。
若不指定该参数则系统默认设置24小时支付有效时间。
参数允许设置围：
1-1440区间的整数值，超过1440默认设置1440
支付宝：
用户扫码后开始计算支付有效时间
微信：
用户下单后开始计算支付有效时间
回调通知地址
notifyurl
VARCHAR
Y
支付成功失败的通知地址
交易终端ip
createip
VARCHAR
Y
交易终端IP
备注
extend1
VARCHAR
N
备注信息，测试系统必填
签名
sign
VARCHAR
Y
RSA签名
4、返回协议参数：
参数名
参数
数据类型
必填
说明
返回状态
rspCode
VARCHAR
Y
返回的错误码，000000代表成功，其它为失败
返回信息
rspMsg
VARCHAR
Y
返回信息
二维码
qrCode
VARCHAR
Y
订单的二维码，商户生成二维码提供给用户扫码支付
签名
sign
VARCHAR
Y
RSA签名
5、接入实例：
请求提交方法：
{
"payType":
"ZFBZF",
"orderId":
"WE1124567810",
"merchantCode":
"",
"totalAmount":
"2",
"subject":
"firsttest",
"desc":
"testproduct",
"body":
"testproduct",
"terminalId":
"1213412134",
"extend1":
"test",
"notifyurl":
"118.178.126.35:
8088/payservice/pay/notifytestsucc",
"createip":
"192.168.0.1"
}
返回值：
{
"rspCode":
"000000",
"rspMsg":
"OK",
"qrCode":
"https:
//qr.alipay./bax02559bawzwz2erezj00d4",
"sign":
"Ek7H4c6f5OgechohLFrxcgPoGC/vVy0Bg5XDzYGVIReHYaFtEBfSUxhSxCf/rDMhM+DZKJaw5jhTU1mE1ijEQoguj6c6gKDSg6fXuEEwbKODlQDW9cHRFxMVki2THexox/g8KgipUiEW5HOdNNm4LcwQe8YC+8gauHcKEXSW7Rw="
}
2、公众号支付
1、接入URL：
118.178.126.35:
8088/payservice/pay/pn
2、接入方式：
POST方式均可
3、请求协议参数：
参数名
参数
数据类型
必填
说明
订单ID
orderId
VARCHAR
Y
交易订单ID
支付通道
payType
VARCHAR
Y
支付通道：
WXZF-微信支付
商户编码
merchantCode
VARCHAR
Y
商户编码，接入时系统分配
交易金额
totalAmount
VARCHAR
Y
交易金额，单位：
元，最小2元
交易标题
subject
VARCHAR
Y
交易标题，显示在微信或支付宝支付页面
交易描述
desc
VARCHAR
Y
交易描述
商户操作员id
operatorId
VARCHAR
N
操作员编号，如员工编码
门店编号
storeId
VARCHAR
N
商户的门店编号
商户终端编号
terminalId
VARCHAR
Y
商户机器的终端编号
支付方式
limitPay
VARCHAR
N
微信/支付宝：
1-不能使用信用卡
支付宝：
2-不适用花呗
3-不使用信用卡/花呗
商品标记
goodsTag
VARCHAR
N
微信渠道可选上送，代金券或立减优惠功能参数，对应微信的goods_tag字段
支付宝目前用不到该参数。
支付有效时间
expireTime
VARCHAR
N
指定订单的支付有效时间（分钟数），超过有效时间用户将无法支付。
若不指定该参数则系统默认设置24小时支付有效时间。
参数允许设置围：
1-1440区间的整数值，超过1440默认设置1440
支付宝：
用户扫码后开始计算支付有效时间
微信：
用户下单后开始计算支付有效时间
回调通知地址
notifyurl
VARCHAR
Y
支付成功失败的通知地址
交易终端ip
createip
VARCHAR
Y
交易终端IP
跳转路径
callbackUrl
VARCHAR
N
支付成功跳转路径；form表单形式提交商户后台；
子商户公众号标识
subAppId
VARCHAR
Y
子商户公众号标识
子商户公众号下关注的用户openid
subOpenId
VARCHAR
Y
子商户公众号下关注的用户openid
微信子商户号
wxSubMchId
VARCHAR
N
微信支付分配的子商户号
是否开具电子发票
receipt
VARCHAR
N
是否开具电子发票
是否原生公众号
isRaw
VARCHAR
Y
1:
原生公众号（返回json串给jsapi拉起支付）
备注
extend1
VARCHAR
N
备注信息，测试系统必填
签名
sign
VARCHAR
Y
RSA签名
4、返回协议参数：
参数名
参数
数据类型
必填
说明
返回状态
rspCode
VARCHAR
Y
返回的错误码，000000代表成功，其它为失败
返回信息
rspMsg
VARCHAR
Y
返回信息
支付码信息
payCode
VARCHAR
Y
"payCode":
"{\"sign\":
\"D9F4C32B8F20D348DDFA85C95B291E55\",\"timestamp\":
\"1476774382\",\"noncestr\":
\"368c7e90e499484e901edbbd501a8dd9\",\"partnerid\":
\"15233133\",\"prepayid\":
\"wx33454fd6f1dc\",\"package\":
\"Sign=WXPay\",\"appid\":
\"wxb5d8ad7674532882\"}"）
签名
sign
VARCHAR
Y
RSA签名
5、接入实例：
请求提交方法：
{
"payType":
"ZFBZF",
"orderId":
"WE1124567810",
"merchantCode":
"",
"totalAmount":
"2",
"subject":
"firsttest",
"body":
"testproduct",
"terminalId":
"1213412134",
"extend1":
"test",
"notifyurl":
"118.178.126.35:
8088/payservice/pay/notifytestsucc",
"createip":
"192.168.0.1"
"callbackUrl":
"118.178.126.35:
8088/payservice/pay/callbackurl"
"subAppId":
"wxa3dbb6050f553164"
"subOpenId":
"9efi3dbb6050f653164"
}
返回值：
{
"rspCode":
"000000",
"rspMsg":
"OK",
"payCode":
{"timeStamp":
"74",
"signType":
"MD5",
"package":
"prepay_id=wx2657a0",
"paySign":
"6B0EEA6AE668593A6A290F8247CE46B7",
"nonceStr":
"05571626a6f6415f8cb11c91e64b8450",
"appId":
"wxa3dbb6050f353164"}，
"sign":
"Ek7H4c6f5OgechohLFrxcgPoGC/vVy0Bg5XDzYGVIReHYaFtEBfSUxhSxCf/rDMhM+DZKJaw5jhTU1mE1ijEQoguj6c6gKDSg6fXuEEwbKODlQDW9cHRFxMVki2THexox/g8KgipUiEW5HOdNNm4LcwQe8YC+8gauHcKEXSW7Rw="
}
3、支付异步通知
1、接入URL：
过程1中请求参数notifyurl值
2、接入方式：
POST方式
3、通知请求协议参数：
参数名
参数
数据类型
必填
说明
订单号
orderid
VARCHAR
Y
商户请求订单号
商户编码
merchantid
VARCHAR
Y
商户编码
交易金额
totalAmount
VARCHAR
Y
交易金额，单位：
元
交易成功时间
payTime
VARCHAR
Y
支付成功的时间
交易状态
trade_state
VARCHAR
Y
交易状态：
INIT-初始化
SUCCESS-成功
USERPAYING-等待用户支付
NOTPAY-未支付
ERROR-支付失败
支付系统订单号
transcation_id
VARCHAR
Y
支付系统部交易号
签名
sign
VARCHAR
Y
RSA签名
4、返回协议参数：
参数名
参数
数据类型
必填
说明
返回状态
rspCode
VARCHAR
Y
返回的错误码，000000代表成功，其它为失败。
返回成功后，将不会再次通知。
返回信息
rspMsg
VARCHAR
Y
返回信息
签名
sign
VARCHAR
Y
RSA签名
5、接入实例：
请求提交方法：
{
"orderid":
"WE1124567810",
"merchantid":
"",
"totalAmount":
"2",
"payTime":
"433",
"trade_state":
"SUCCESS",
"transcation_id":
"BJ55124",
}
返回值：
{
"rspCode":
"000000",
"rspMsg":
"OK",
"sign":
"Ek7H4c6f5OgechohLFrxcgPoGC/vVy0Bg5XDzYGVIReHYaFtEBfSUxhSxCf/rDMhM+DZKJaw5jhTU1mE1ijEQoguj6c6gKDSg6fXuEEwbKODlQDW9cHRFxMVki2THexox/g8KgipUiEW5HOdNNm4LcwQe8YC+8gauHcKEXSW7Rw="
}
6、特别说明：
1支付异步通知过程在整个支付流程中一定存在。
商户系统在收到异步通知过程后，需向接口返回rspCode为“000000”。
支付接口根据该返回值判断商户系统是否已经收到结果。
若返回结果不是“000000”，支付系统会再次反复向notifyurl发送结果，直到商户返回“000000”或者达到重复发送次数。
2当支付系统在异步通知过程中返回在线支付结果时，商户系统在收到数据后，应该通过sign值判断是否是有效的返回数据，防止数据在网络传输过程中被恶意篡改。
7、注意事项
1在收到支付接口订单下行异步通知结果时，商户系统需首先验证订单通知的合法性，如果不合法，则不要更新商户系统上的订单状态。
2商户系统订单状态和订单实际金额务必以此次接口订单异步通知的结果为准。
3商户系统在成功提交订单后，在未没有收到此接口异步通知结果时，请不要更新商户系统上的订单状态
4在交易异步通知过程中商户系统返回结果值rspCode“00000”回支付接口时，“000000”并不是将支付接口在交易异步通知的结果原样返回。
商户系统返回值“000000”时表示商户系统已经成功接收到了结果（不论结果是什么，总之是收到了），而其他值表示因为某些原因商户系统并不认为支付接口的返回是有效的。
支付接口在收到商户系统的返回后，如果返回的值为“000000”支付接口将不再次发送结果，否则支付接口会根据同商户的约定再次发送结果。
4、交易查询
1、接入URL：
118.178.126.35:
8088/payservice/pay/query
2、接入方式：
POST方式，JSON格式
3、请求协议参数：
参数名
参数
数据类型
必填
说明
订单号
orderId
VARCHAR
Y
商户请求订单号
商户编码
merchantCode
VARCHAR
Y
商户编码
签名
sign
VARCHAR
Y
RSA签名
4、返回协议参数：
参数名
参数
数据类型
必填
说明
返回值
rspCode
VARCHAR
Y
返回的错误码，000000代表成功，其它为失败
返回信息
rspMsg
VARCHAR
Y
返回信息
订单号
orderId
VARCHAR
Y
商户请求订单号
支付通道
payType
VARCHAR
Y
支付通道
交易金额
totalAmount
VARCHAR
Y
交易金额
交易时间
orderTime
VARCHAR
Y
订单生成时间
交易状态
status
VARCHAR
Y
交易状态：
INIT-初始化
USERPAYING-等待用户支付
SUCCESS-成功
NOTPAY-未支付
ERROR-支付失败
交易标题
subject
VARCHAR
Y
交易标题，显示在微信或支付宝支付页面
交易描述
desc
VARCHAR
Y
交易描述
门店编号
storeId
VARCHAR
Y
门店编号
终端编号
terminalId
VARCHAR
Y
终端编号
签名
sign
VARCHAR
Y
RSA签名
5、接入实例：
请求提交方法：
{
"orderId":
"WE1124567810",
"merchantCode":
"",
}
返回值：
{
"rspCode":
"000000",
"rspMsg":
"OK",
"orderId":
"WE1124567810",
"payType":
"ZFBZF",
"totalAmount":
"2",
"status":
"SUCCESS",
"subject":
"firsttest",
"desc":
"testproduct",
"storeid":
"333333",
"terminalId":
"1213412134"
}
5、对账查询
1、接入URL：
118.178.126.35:
8088/payservice/pay/settlement
2、接入方式：
POST方式
3、请求协议参数：
参数名
参数
数据类型
必填
说明
商户编码
merchantCode
VARCHAR
Y
商户编码
对账日期
settleDate
VARCHAR
Y
对账日期
签名
sign
VARCHAR
Y
RSA签名
4、返回协议参数：
参数名
参数
数据类型
必填
说明
返回值
rspCode
VARCHAR
Y
返回的错误码，000000代表成功，其它为失败
返回信息
rspMsg
VARCHAR
Y
返回信息
对账单
content
VARCHAR
Y
对账单容
签名
sign
VARCHAR
Y
RSA签名
5、对账单格式：
请求提交方法：
hzf001||87623|950|2.00|20160811|S|000000|success|0.00|ZFBZF|0|X1|
每个字段以“|”分割,字段含义参见下表
对账流水只包含状态为成功的交易
域
字段名称
类型
要求
备注
1
agentNum
VARCHAR（32）
M
代理商编号
2
merchantCode
VARCHAR（32）
M
商户编号
3
transcationId
VARCHAR（32）
M
平台流水号
4
orderId
VARCHAR（32）
M
代理商请求订单号
5
amount
Numberic（12,2）
M
交易金额（保留两位）
6
settleDate
CHAR（8）
M
对账日期
7
respType
CHAR
（1）
M
S成功;
8
respCode
CHAR（6）
M
响应码
9
respMsg
VARCHAR（256）
O
响应描述
10
fee
Numberic（12,2）
M
商户手续费（保留两位）
11
payWay
VARCHAR（32）
M
12
storeId
Vachar2（32）
0
商户的门店编号
13
terminalId
Vachar2（32）
0
商户机具终端编号
6、接入实例：
请求提交方法：
{
"merchantCode":
"",
"settleDate":
"20170624",
}
返回值：
{
"rspCode":
"000000",
"rspMsg":
"OK",
"content":
"hzf001||87623|950|2.00|20160811|S|000000|success|0.00|ZFBZF|0|X1|",
}
第三章签名说明
1、签名算法
为了保证网络数据的传输安全，防止数据在传输过程中被截取、篡改等，在调用API时双方约定使用HTTPS和RSA加密算法对通讯数据进行加解密处理。
RSA通用加密算法，加密后需要转换为Base64，解密前需要将Base64加密串转换为RSA的字节数组。
RSA签名算法描述如下:
1：
将所有参数名称（不包含sign本身）按照字母顺序排序，从a-z;
2：
将这些参数的值连接成一个字符串，中文字符使用UTF-8编码;
3：
将这个字符串作为源字符串，将商户自有的RSA私钥（该私钥对应的公钥需要;
在支付系统进行报备，以获取支付系统的公钥）作为key，使用RSA算法生成签名;
4：
将生成的签名值添加到参数列表中，参数名称为“sign”;
2、密钥生产
使用openssl生成密钥方法如下；
1）生成RSA私钥：
opensslgenrsa-outrsa_private_key.pem1024
该命令会生成1024位的私钥，生成成功的界面如下：
此时我们就可以在当前路径下看到rsa_private_key.pem文件了。
2）把RSA私钥转换成PKCS8格式
输入命令opensslpkcs8-topk8-nocrypt-informPEM-inrsa_private_key.pem-outformPEMoutform，并回车
得到生成功的结果，这个结果就是PKCS8格式的私钥，如下图：
3）生成RSA公钥
输入命令opensslrsa-inrsa_private_key.pem-pubout-outrsa_public_key.pem，并回车，
得到生成成功的结果，如下图：
此时，我们可以看到一个文件名为rsa_public_key.pem的文件，打开它，可以看到-----BEGINPUBLICKEY-----开头，
-----ENDPUBLICKEY-----结尾的没有换行的字符串，这个就是公钥。
附录1错误码说明
错误码
说明
1000
系统数据库异常
3000
系统错误:
1000001
商户不存在
1000002
签名验证失败
1000003
参数错误
1000004
缺少参数
1000005
网关异常
1000006
代理商不存在
1000007
系统异常
1000008
错误的过期时间：
expireTime
1000
升级会员 