银联商务全民付移动支付
APP综合支付
商户接入接口规范
V1.0.1
银联商务有限公司
2017.07
版本控制信息
版本 |
日期 |
修改人 |
说明 |
V1.0.0 |
2017/7/14 |
xxx |
初版 |
V1.0.1 |
2017/8/1 |
xxx |
增加支付宝APP支付 |
本文档中的所有内容为银联商务有限公司专属所有。未经银联商务有限公司的明确书面许可，任何组织或个人不得以任何目的、任何形式及任何手段复制或传播本文档部分或全部内容。 |
目 录2
1. 简介4
1.1. 概述4
1.2. 适用范围4
2. 参数规范说明4
2.1. 序号4
2.2. 数据项4
2.3. 类型5
2.4. 长度5
2.5. 输入/选择5
2.6. 备注6
3. 平台下单接口6
3.1. 接口介绍6
3.2. 参数配置6
3.3. 接口参数说明6
3.4. 账单号生成规范6
3.5. 下单请求7
3.6. 下单请求示例报文9
3.7. 下单请求响应9
3.8. 下单响应示例报文10
4. 支付请求接口11
4.1. Android综合支付接口11
4.1.1. SDK包说明11
4.1.2. 快速集成11
4.1.3. 接口说明12
4.2. iOS综合支付接口14
4.2.1. 快速集成14
4.2.2. 接口说明14
4.3. 综合支付参数说明15
4.3.1. 支付渠道15
4.3.2. 支付结果信息15
4.3.3. 结果码16
5、 支付结果查询接口16
5.1 接口介绍16
5.2 参数配置17
5.3 查询请求17
5.4 查询请求示例报文17
5.5 查询响应18
6、 订单退款接口19
6.1 接口介绍19
6.2 参数配置19
6.3 订单退款请求20
6.4 订单退款请求示例报文20
6.5 订单退款响应21
7、 支付结果通知22
8、 签名规则23
9、 errCode取值说明24
10、 status取值说明26
11、 targetSys取值说明27
1. 简介
1.1. 概述
本接口定义第三方接入银联商务全民付移动支付APP综合支付的接口标准。
1.2. 适用范围
此接口适用第三方接入银联商务全民付移动支付APP综合支付的开发。
1. 参数规范说明
1.1. 序号
报文中每个字段的顺序
1.2. 数据项
报文中此字段所代表的属性
1.3. 类型
报文中此字段的类型
字符 |
含义 |
A |
字母字符，A至Z，a至z |
N |
数值，0至9，右靠，首位有效数字前填零。若表示人民币金额，则最右二位为角、分。 |
P |
填充字符，如空格。 |
S |
特殊符号。 |
C |
字符类型 |
An |
字母和数字字符 |
As |
字母和特殊字符 |
Ns |
数字和特殊字符 |
Ans |
字母、数字和特殊字符。 |
MM |
月份，01至12。 |
DD |
日期，01至31。 |
YY |
年份，00至99。 |
hh |
时，00至23。 |
mm |
分，00至59。 |
ss |
秒，00至59。 |
1.4. 长度
报文中此字段允许的最大长度报文中此字段允许的长度。
如A3：3字节定长字母字符，AN1…9 长度为1~9字节的变长字母和/或数字字符
1.4. 输入/选择
报文中此字段输入要求：
M 此字段必须出现，且不能为空
O 此字段可选
C 在特定环境下，此字段必须出现，且不为空
1.5. 备注
对字段的一些解释
3. 平台下单接口
3.1. 接口介绍
本接口为商户的账单H5页面向银商网络支付前置系统发起的支付跳转
3.2. 参数配置
Server端发送HTTP POST请求到下列接口地址：
测试环境接口地址：http://umspay.izhong.me/netpay-route-server/api/
生产环境接口地址：https://qr.chinaums.com/netpay-route-server/api/
3.3. 接口参数说明
消息来源、MD5密钥、系统编号需银商根据不同的对接系统进行分配。消息类型需根据业务不同进行分配。银商会在商户接入时安排工作人员进行相关支持。
3.4. 账单号生成规范
商户需自行生成merOrderId。此时merOrderId需要符合银商规范，以银商分配的4位系统编号作为账单号的前4位，且在商户系统中此账单号保证唯一。总长度需大于6位，小于32位。
3.5. 下单请求
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
|
msgId |
消息ID，原样返回 |
String |
max =64 |
false |
||
msgSrc |
消息来源 |
String |
min = 1 max = 32 |
true |
请求来源：PCARD, NETPAY, TPOS, ULINK, MOBILE, MARKET, NEIMENG |
|
msgType |
消息类型 |
String |
min = 1 max = 64 |
true |
微信 :wx.unifiedOrder 支付宝： trade.precreate 全民付： qmf.order |
|
requestTimestamp |
报文请求时间，格式yyyy-MM-dd HH:mm:ss |
Date |
true |
yyyy-MM-dd HH:mm:ss |
||
merOrderId |
商户订单号 |
String |
min = 6 max = 32 |
true |
商户自行生成 |
|
srcReserve |
请求系统预留字段 |
String |
max = 255 |
false |
||
mid |
商户号 |
String |
min = 8 max = 32 |
true |
||
tid |
终端号 |
String |
min = 2 max = 32 |
true |
||
instMid |
机构商户号 |
String |
min = 8 max = 32 |
true |
APPDEFAULT |
|
goods |
discount |
Long |
max=1024 |
false |
||
unit |
String |
max = 32 |
||||
goodsId |
商品ID |
String |
max = 64 |
|||
goodsName |
商品名称 |
String |
max = 256 |
|||
quantity |
商品数量 |
Long |
max = 20 |
|||
price |
商品单价（分） |
Long |
max = 20 |
|||
goodsCategory |
商品分类 |
String |
max = 64 |
|||
body |
商品说明 |
String |
max= 1024 |
|||
attachedData |
商户附加数据 |
String |
max = 255 |
false |
||
expireTime |
订单过期时间 |
Date |
false |
订单过期时间，为空则使用系统默认过期时间（30分钟），格式yyyy-MM-dd HH:mm:ss |
||
goodsTag |
商品标记，用于优惠活动 |
String |
max = 32 |
fasle |
||
goodsTradeNo |
商品交易单号 |
String |
false |
跟goods字段二选一，商品信息通过goods.add接口提前上送 |
||
orderDesc |
订单描述 |
String |
max = 255 |
false |
||
originalAmount |
订单原始金额，单位分，用于记录前端系统打折前的金额 |
Long |
min = 1 max = 100000000 |
false |
||
productId |
商品ID |
String |
false |
|||
totalAmount |
支付总金额，单位分 |
Number |
min = 1 max = 100000000 |
true |
||
openId |
用户标识 |
String |
用户标识 |
false |
||
notifyUrl |
支付结果通知地址 |
String |
max=255 |
false |
||
returnUrl |
网页跳转地址 |
String |
max=255 |
false |
||
showUrl |
订单展示页面 |
String |
max = 255 |
false |
||
signType |
签名算法 |
String |
false |
MD5,SHA1,RSA |
||
subOpenId |
用户子标识 |
String |
false |
|||
tradeType |
交易类型 |
String |
false |
微信必传:APP |
||
merchantUserId |
商户用户号 |
String |
max = 32 |
false |
全民付必传 |
|
mobile |
手机号 |
String |
max = 11 |
false |
全民付必传 |
|
sign |
签名 |
String |
true |
签名规则 |
||
1.6. 下单请求示例报文
{
"tid":"88880001",
"msgSrc":"ERP_SCANPAY",
"requestTimestamp":"2017-04-25 19:38:16",
"merOrderId":"3028201704251133163636273122",
"sign":"C646FC8AA7EB6EA52F846AAE2D9E577E",
"totalAmount":"1",
"mid":"123456789054321",
"msgType":"wx.unifiedOrder",
"instMid":"APPDEFAULT",
"tradeType":"APP"
}
3.6. 下单请求响应
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
errCode |
平台错误码 |
String |
max = 64 |
true |
|
errMsg |
平台错误信息 |
String |
max = 255 |
false |
|
msgId |
消息ID |
String |
max = 64 |
false |
|
msgType |
消息类型 |
String |
false |
||
msgSrc |
消息来源 |
String |
max = 32 |
true |
|
srcReserve |
请求系统预留字段 |
String |
max = 255 |
false |
|
responseTimestamp |
报文响应时间，格式yyyy-MM-dd HH:mm:ss |
Date |
true |
||
merName |
商户名称 |
String |
false |
||
merOrderId |
商户订单号 |
String |
false |
||
mid |
商户号 |
String |
true |
||
tid |
终端号 |
String |
true |
||
seqId |
平台流水号，类似检索参考号 |
String |
false |
||
settleRefId |
清分ID，如果来源方传了bankRefId就等于bankRefId，否则等于seqId |
String |
false |
||
Status |
交易状态 |
String |
false |
取值说明 |
|
totalAmount |
支付总金额 |
Number |
false |
||
targetOrderId |
第三方订单号 |
String |
false |
||
targetSys |
目标平台代码 |
String |
false |
取值说明 |
|
targetStatus |
目标平台的状态 |
String |
false |
||
jsPayRequest |
JSAPI支付用的请求报文，带有签名信息 |
Map |
false |
||
appPayRequest |
APP支付用的请求报文，带有签名信息 |
Map |
false |
||
prepayId |
支付ID，用于APP支付和公众号支付 |
String |
max=64 |
false |
|
qrCode |
支付二维码，内容为URL，由终端转换成二维码显示 |
String |
max=64 |
false |
|
Sign |
报文签名，算法参考文档 |
String |
false |
||
signType |
签名算法 |
String |
false |
MD5,SHA1,RSA |
|
targetMid |
支付渠道商户号，各渠道情况不同，酌情转换。 |
String |
false |
1.8. 下单响应示例报文
{
"msgType": "wx.unifiedOrder",
"msgSrc": "ERP_SCANPAY",
"merName": "仲晶晶测试",
"mid": "123456789054321",
"appPayRequest": {
"package": "Sign=WXPay",
"appid": "wxcf7c37f82cf75798",
"sign": "8C4B63127BE65757C41369D21EB211B8",
"partnerid": "102510208503",
"prepayid": "wx20170425193304c92c9f33a10089330713",
"noncestr": "MquuMZwYnACubCaXSqrTrxKkpINYtRPt",
"timestamp": "20170425193304"
},
"settleRefId": "00221257500N",
"tid": "88880001",
"totalAmount": 1,
"qrCode": "weixin://wxpay/bizpayurl?pr=GhOkBtP",
"targetMid": "102510208503",
"responseTimestamp": "2017-04-25 19:33:04",
"errCode": "SUCCESS",
"prepayId": "wx20170425193304c92c9f33a10089330713",
"targetStatus": "SUCCESS|SUCCESS",
"seqId": "00221257500N",
"merOrderId": "3028201704251133163636273122",
"status": "WAIT_BUYER_PAY",
"targetSys": "WXPay",
"sign": "49144C973BAE19B4336111539A65F2B9"
}
2. 支付请求接口
下单成功后，使用返回数据中的appPayRequest即可调用支付。
支付需要集成APP综合支付SDK，以下章节介绍集成SDK及调起支付，处理支付请求结果等内容。
1.1. Android综合支付接口
本小节涉及到银联商务全民付移动支付APP综合支付SDK的接口说明、及其接口调用细节，需要读者具有一定Android编程经验。
1.1.1. SDK包说明
APP综合支付SDK的形式为aar格式，其中包含了所支持支付渠道的开发包(如：微信)，商户无需再手动添加。
1.1.2. 快速集成
1. 引入APP综合支付开发包
由于APP综合支付SDK为aar形式，因此需要在Gradle文件中加入综合支付SDK的引用。
2. 集成指导
不同的支付渠道在集成方式上会有不同的要求，以下内容描述了怎样进行支付渠道相关的特殊设置
微信支付渠道
微信支付由于其返回支付结果的特殊性，需要将随综合支付SDK一起提供的WXPayEntryActivity.java文件放入包名对应的路径中，否则有可能会无法收到支付结果。
此外，还需遵从微信支付所要求的包名及签名设置，否则无法调起微信支付。详细请参考微信的开发者网站。
1.1.3. 接口说明
1. 新建支付插件对象
在使用APP综合支付SDK之前，首先需要创建支付请求对象。
/*
* 新建统一支付SDK对象
* 参数：Context
* */
UnifyPayPlugin payPlugin = new UnifyPayPlugin(this);
/*
* 新建统一支付请求类
* */
UnifyPayRequest payRequest = new UnifyPayRequest();
2. 初始化支付请求数据
商户在完成下单之后，可以获取到支付方式所对应的app数据。(详细请参考下单接口)。使用该数据，完成支付请求的初始化。
/*
* 初始化支付渠道(如：微信支付)
* */
payRequest.payChannel = UnifyPayPlugin.WX_PAY;
/*
* 设置下单接口中返回的数据(appRequestData)
* */
payRequest.payData = appRequestData;
字段名 |
变量名 |
类型 |
长度 |
输入/选择 |
备注 |
支付渠道 |
payChannel |
N |
2 |
M |
指定的支付渠道 |
支付数据 |
payData |
C |
M |
下单成功后获取的支付数据。 |
|
3. 设置支付结果监听
通过APP综合支付SDK的setPayListener接口，可以设置支付结果监听。支付完成后，会通过onResult接口返回支付结果，支付成功则调用查询接口获取支付状态后再展示用户实际支付结果。注意一定不能以插件SDK返回作为用户支付的结果，应以服务器端的接收的支付通知或查询API返回的结果为准。
注：支付宝渠道如果支付请求发送成功，则会跳转至支付宝APP，并且支付完成后会停留在支付宝，因此商户 APP无法通过UnifyPayListener收到支付结果，请以后台的支付结果为准。
/*
* 设置支付结果监听
*/
payPlugin.setPayListener(new UnifyPayListener() {
@Override
public void onResult(String resultCode, String resultMsg) {
/*
* 根据返回的支付结果进行处理
*/
if (resultCode.equals(UnifyPayPlugin.UNIFY_PAY_SUCCESS)) {
} else {
}
}
});
支付结果信息：
字段名 |
变量名 |
类型 |
长度 |
输入/选择 |
备注 |
结果码 |
resultCode |
C |
M |
“0000”表示成功 商户订单是否成功支付应该以商户后台收到支付结果为准，此处返回的结果仅作为支付请求的发送结果 |
|
结果信息 |
resultMsg |
C |
M |
接口返回的状态描述，为JSON字符串 |
|
4. 支付请求
设置完支付结果监听接口之后，即可使用startPay接口调起相应的支付SDK进行支付。
/*
* 开始支付
*/
payPlugin.startPay(payRequest);
1.1. iOS综合支付接口
1.1.3. 快速集成
集成iOS版APP综合支付SDK时，请先导入SDK所依赖的库。
1.1.4. 接口说明
引入UMSPPPayUnifyPayPlugin头文件，调用UMSPPPayUnifyPayPlugin的类方法：
参数说明：
字段名 |
变量名 |
类型 |
长度 |
输入/选择 |
备注 |
支付渠道 |
payChannel |
N |
|
M |
指定的支付渠道 |
支付数据 |
payData |
C |
M |
下单成功后获取的支付数据。 |
|
支付结果 |
callbackBlock |
|
M |
获取支付结果的回调 |
注：支付宝渠道如果支付请求发送成功，则会跳转至支付宝APP，并且支付完成后会停留在支付宝，因此商户 APP无法通过callbackBlock收到支付结果，请以后台的支付结果为准。
callbackBlock返回的支付结果信息：
字段名 |
变量名 |
类型 |
长度 |
输入/选择 |
备注 |
结果码 |
resultCode |
C |
M |
“0000”表示成功 商户订单是否成功支付应该以商户后台收到支付结果为准，此处返回的结果仅作为支付请求的发送结果 |
|
结果信息 |
resultInfo |
C |
M |
接口返回的状态描述，为JSON字符串 |
|
|
|
|
|
|
|
1.1. 综合支付参数说明
1.1.5. 支付渠道
在调用综合支付插件进行支付时，需要指定所想使用的支付渠道，渠道相关说明如下。
字段名 |
编号 |
备注 |
支付渠道 |
00 |
银商渠道支付 |
01 |
Apple Pay |
|
02 |
Sumsung Pay |
|
03 |
微信支付 |
|
04 |
支付宝支付 |
1.1.2. 支付结果信息
字段名 |
变量名 |
类型 |
长度 |
输入/选择 |
备注 |
|
结果码 |
resultCode |
C |
M |
“0000”表示成功 商户订单是否成功支付应该以商户后台收到支付结果为准，此处返回的结果仅作为支付请求的发送结果 |
||
结果信息 |
C |
M |
接口返回的状态描述，为JSON字符串 |
|||
结果描述 |
resultMsg |
C |
M |
支付结果描述 |
||
附加信息 |
extraMsg |
C |
M |
支付结果附加的信息 |
||
原始信息 |
rawMsg |
C |
M |
原始支付渠道返回的信息 |
||
1.1.1. 结果码
结果码说明
字段名 |
编号 |
备注 |
结果码 |
0000 |
支付请求发送成功。商户订单是否成功支付应该以商户后台收到支付结果。 |
1000 |
用户取消支付 |
|
1001 |
参数错误 |
|
1002 |
网络连接错误 |
|
1003 |
支付客户端未安装 |
|
2001 |
订单处理中，支付结果未知(有可能已经支付成功)，请通过后台接口查询订单状态 |
|
2002 |
订单号重复 |
|
2003 |
订单支付失败 |
|
9999 |
其他支付错误 |
5、 支付结果查询接口
5.1 接口介绍
钱包支付时，因通讯故障、服务器故障等原因，造成收银机最终没有收到支付结果通知，收银员不确定该笔支付后台处理结果，可以在收银机上发起“查询”交易，查询该笔交易订单在钱包后台的支付结果，并将支付结果返回给收银机。
5.2 参数配置
Server端发送HTTP POST请求到下列接口地址：
测试环境接口地址：http://umspay.izhong.me/netpay-route-server/api/
生产环境接口地址：https://qr.chinaums.com/netpay-route-server/api/
5.3 查询请求
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
msgId |
消息ID |
String |
max = 64 |
false |
|
msgSrc |
消息来源 |
String |
min = 1 max = 20 |
true |
|
msgType |
消息类型 |
String |
min = 1 max = 64 |
true |
query |
requestTimestamp |
报文请求时间，格式yyyy-MM-dd HH:mm:ss |
Date |
true |
||
srcReserve |
请求系统预留字段 |
String |
max = 255 |
false |
|
mid |
商户号 |
String |
min = 8 max = 32 |
true |
|
tid |
终端号 |
String |
min = 2 max = 32 |
true |
|
instMid |
机构商户号 |
String |
min = 8 max = 32 |
true |
APPDEFAULT |
merOrderId |
商户订单号 |
String |
min = 6 max = 64 |
false |
|
targetOrderId |
支付订单号 |
String |
min = 6 max = 64 |
false |
|
sign |
签名 |
String |
true |
5.4 查询请求示例报文
{
"msgType": "query",
"requestTimestamp": "2016-11-11 17:30:07",
"msgSrc": "WWW.SUPERB-PAY.COM",
"mid": "898310060514001",
"tid": "0001",
"merOrderId": "301599028982611111637001000",
"instMid": "YUEDANDEFAULT"
}
5.5 查询响应
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
errCode |
平台错误码 |
String |
max = 64 |
true |
|
errMsg |
平台错误信息 |
String |
max = 255 |
false |
|
msgId |
消息ID |
String |
max = 64 |
false |
|
msgType |
消息类型 |
String |
false |
||
msgSrc |
消息来源 |
String |
max = 32 |
true |
|
srcReserve |
请求系统预留字段 |
String |
max = 255 |
false |
|
responseTimestamp |
报文响应时间，格式yyyy-MM-dd HH:mm:ss |
Date |
true |
||
mid |
商户号 |
String |
true |
||
tid |
终端号 |
String |
true |
||
instMid |
机构商户号 |
String |
true |
||
seqId |
平台流水号，类似检索参考号 |
String |
false |
||
settleRefId |
清分ID，如果来源方传了bankRefId就等于bankRefId，否则等于seqId |
String |
false |
||
refId |
检索参考号，用在银联体系交易中 |
String |
false |
||
status |
交易状态 |
String |
false |
||
totalAmount |
支付总金额 |
Number |
false |
||
merName |
商户名称 |
String |
false |
||
merOrderId |
商户订单号 |
String |
false |
||
targetOrderId |
第三方订单号 |
String |
false |
||
targetSys |
目标平台代码 |
String |
false |
||
targetStatus |
目标平台的状态 |
String |
false |
||
buyerId |
买家ID |
String |
false |
||
targetMid |
支付渠道商户号，各渠道情况不同，酌情转换。 |
String |
false |
||
bankCardNo |
银行卡号，如果有的话 |
String |
false |
||
bankInfo |
银行信息 |
String |
false |
||
billFunds |
支付渠道列表 示例：支付宝余额:33|优惠券:55 |
String |
false |
||
billFundsDesc |
支付渠道描述 |
String |
false |
||
buyerPayAmount |
买家付款的金额，支付宝会有 |
Number |
false |
||
buyerUsername |
买家用户名 |
String |
false |
||
couponAmount |
网付计算的优惠金额 |
Number |
false |
||
invoiceAmount |
交易中可给用户开具发票的金额 |
Number |
false |
||
payTime |
支付时间，格式yyyy-MM-dd HH:mm:ss |
Date |
false |
||
receiptAmount |
商户实收金额，支付宝会有 |
Number |
false |
||
settleDate |
结算日期，格式yyyy-MM-dd |
Date |
false |
||
subBuyerId |
子买家ID，比如微信的subOpenId |
String |
false |
6、 订单退款接口
6.1 接口介绍
当成功交易之后一段时间内，由于买家或商户的原因需要退款时，商户可以通过本接口将支付款退还给买家，退款请求验证成功之后，银商将通知支付渠道方按照退款规则把支付款按原路退回到买家帐号上。
6.2 参数配置
Server端发送HTTP POST请求到下列接口地址：
测试环境接口地址：http://umspay.izhong.me/netpay-route-server/api/
生产环境接口地址：https://qr.chinaums.com/netpay-route-server/api/
6.3 订单退款请求
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
msgId |
消息ID，原样返回 |
String |
max =64 |
false |
|
msgSrc |
消息来源 |
String |
min = 1 max = 20 |
true |
|
msgType |
消息类型 |
String |
min = 1 max = 64 |
true |
refund |
requestTimestamp |
报文请求时间，格式yyyy-MM-dd HH:mm:ss |
Date |
true |
||
srcReserve |
请求系统预留字段 |
String |
false |
||
merOrderId |
商户订单号 |
String |
min = 6 max = 64 |
false |
|
instMid |
机构商户号 |
String |
min = 8 max = 32 |
true |
|
mid |
商户号 |
String |
min = 8 max = 32 |
true |
|
targetOrderId |
支付订单号 |
String |
min = 6 max = 64 |
false |
|
tid |
终端号 |
String |
min = 2 max = 32 |
true |
|
refundAmount |
要退货的金额 |
Number |
min = 1 max = 100000000 |
true |
|
refundDesc |
退货说明 |
String |
max = 255 |
false |
|
refundOrderId |
退货交易的订单号，如不指定，则系统自动生成。 |
String |
min = 6 max = 64 |
false |
|
sign |
签名 |
String |
true |
6.4 订单退款请求示例报文
{
"msgType": "refund",
"requestTimestamp": "2016-09-22 16:01:42",
"msgSrc": "ULINK",
"sign": "c70b87f94bc945bfe838880002a456b1",
"msgId": "07S30609000023115850160142",
"mid": "103290070111407",
"tid": "12340042",
"instMid": "YUEDANDEFAULT",
"refundAmount": "1",
"merOrderId": "20160922145952000023114819"
}
6.5 订单退款响应
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
errCode |
平台错误码 |
String |
max = 64 |
true |
|
errMsg |
平台错误信息 |
String |
max = 255 |
false |
|
msgId |
消息ID |
String |
max = 64 |
false |
|
msgType |
消息类型 |
String |
false |
||
msgSrc |
消息来源 |
String |
max = 32 |
true |
|
srcReserve |
请求系统预留字段 |
String |
false |
||
responseTimestamp |
报文响应时间，格式yyyy-MM-dd HH:mm:ss |
Date |
true |
||
mid |
商户号 |
String |
true |
||
tid |
终端号 |
String |
true |
||
merOrderId |
商户订单号 |
String |
false |
||
merName |
商户名称 |
String |
false |
||
seqId |
平台流水号 |
String |
false |
||
status |
交易状态 |
String |
false |
||
targetMid |
支付渠道商户号 |
String |
false |
||
targetOrderId |
第三方订单号，退货交易时不返回 |
String |
false |
||
targetStatus |
目标平台的状态 |
String |
false |
||
targetSys |
目标平台代码 |
String |
false |
||
totalAmount |
支付总金额 |
Number |
false |
||
refundAmount |
总退款金额 |
Number |
false |
||
refundFunds |
退款渠道列表 |
String |
false |
||
refundFundsDesc |
退款渠道描述 |
String |
false |
||
refundInvoiceAmount |
实付部分退款金额 |
Number |
false |
||
refundOrderId |
退货订单号 |
String |
false |
||
refundTargetOrderId |
目标系统退货订单号 |
false |
7、 支付结果通知
支付完成后，渠道方会通知网付前置账单系统，账单系统收到通知后会组织结果信息发送通知到商户的通知地址。商户的通知地址可以在商户信息中配置，也可以在上送详单信息时上送，若都多处都配置了通知地址，那么账单系统会把结果通知到所有的地址上。
注意：商户收到通知后，需要对通知做出响应：成功时响应”SUCCESS”；失败时响应”FAILED”。
通知会以POST形式发出，包含参数如下：
参数字段 |
参数说明 |
类型 |
范围 |
必传 |
备注 |
mid |
商户号 |
String |
false |
||
tid |
终端号 |
String |
false |
||
instMid |
机构商户号 |
String |
false |
||
attachedData |
附加数据 |
String |
false |
||
bankCardNo |
支付银行信息 |
String |
false |
||
billFunds |
资金渠道 |
String |
false |
||
billFundsDesc |
资金渠道说明 |
String |
false |
||
buyerId |
卖家ID |
String |
false |
||
buyerUsername |
买家用户名 |
String |
false |
||
buyerPayAmount |
实付金额 |
Number |
false |
||
totalAmount |
订单金额，单位分 |
Number |
false |
||
invoiceAmount |
开票金额 |
Number |
false |
||
merOrderId |
商户订单号 |
String |
false |
||
payTime |
支付时间，格式yyyy-MM-dd HH:mm:ss |
Date |
false |
||
receiptAmount |
实收金额 |
Number |
|||
refId |
支付银行卡参考号 |
String |
false |
||
refundAmount |
退款金额 |
Number |
false |
||
refundDesc |
退款说明 |
String |
false |
||
seqId |
系统交易流水号 |
String |
false |
||
settleDate |
结算日期，格式yyyy-MM-dd |
Date |
false |
||
status |
订单状态 |
String |
false |
||
subBuyerId |
卖家子ID |
String |
false |
||
targetOrderId |
渠道订单号 |
String |
false |
||
targetSys |
支付渠道 |
String |
false |
8、 签名规则
签名采用MD5方式，计算MD5的输入数据为待签名字符串加上key（即：md5密钥），key由网付前置平台分配。在请求参数列表中，除去sign参数外，其他需要使用到的参数均为要签名的参数。
生成待签名字符串
对于如下的参数数组：
string[] parameters={
"attachedData={merBillNo:2015090700000000}",
"merOrderId=2015090700000000",
"targetOrderId=2015090700000000",
"buyerUsername=张三",
"status=SUCCESS",
"invoiceAmount=800",
"totalAmount=1000",
"billFunds=COUPON:200|PCARD:800",
"billFundsDesc=优惠金额2.00元，银行卡支付金额8.00元",
"payTime=2015-09-07 16:00:00"
};
对数组里的每一个值从a到z的顺序排序，若遇到相同首字母，则看第二个字母，以此类推。
排序完成之后,再把所有数组值以“&”字符连接起来,如:
attachedData={merBillNo:2015090700000000}&billFunds=COUPON:200|PCARD:800&billFundsDesc=优惠金额2.00元，银行卡支付金额8.00元&buyerUsername=张三&invoiceAmount=800&merOrderId=2015090700000000&payTime=2015-09-07 16:00:00&status=SUCCESS&targetOrderId=2015090700000000&totalAmount=1000
这串字符串便是待签名字符串。
注：
没有值（包含空字符串）的参数无需传递，也不需包含到待签名数据中；
根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、@等），则该值需要做URL Encoding，这样请求接收方才能接收到正确的参数值。注意：这种情况下，待签名数据应该是原始值而不是encoding之后的值。
签名示例，假设key的值为：
AAABBBCCCDDDEEEFFFGGG
则待签名的字符串：
attachedData={merBillNo:2015090700000000}&billFunds=COUPON:200|PCARD:800&billFundsDesc=优惠金额2.00元，银行卡支付金额8.00元&buyerUsername=张三&invoiceAmount=800&merOrderId=2015090700000000&payTime=2015-09-07 16:00:00&status=SUCCESS&targetOrderId=2015090700000000&totalAmount=1000AAABBBCCCDDDEEEFFFGGG
MD5签名：
4AE1B3EB1D983B42FB7D859AAA757C73
跳转链接的跳转链接地址（特别注意，key不放在跳转链接中）：
http://url?attachedData={merBillNo:2015090700000000}&merOrderId=2015090700000000&targetOrderId=2015090700000000&buyerUsername=张三&status=SUCCESS&invoiceAmount=800&totalAmount=1000&billFunds=COUPON:200|PCARD:800&billFundsDesc=优惠金额2.00元，银行卡支付金额8.00元&payTime=2015-09-07 16:00:00&sign=4AE1B3EB1D983B42FB7D859AAA757C73
9、 errCode取值说明
取值 |
描述 |
原因和应对措施 |
系统失败 |
SUCCESS |
成功 |
无。 |
|
INTERNAL_ERROR |
内部错误 |
系统错误，请联系技术支持。 |
是 |
BAD_REQUEST |
请求报文有错 |
报文格式有错误，请对照文档检查报文格式。 |
是 |
NO_SERVICE |
没有能处理请求msgtype的服务 |
msgType错误，请检查文档，msgType是否拼写正确。 |
是 |
TIMEOUT |
处理超时 |
处理超时，很可能是微信和支付宝的网络请求没应答，建议重试或者撤销交易。 |
是 |
NO_ORDER |
找不到请求的原始订单 |
对应的mid+merOrderId不正确，无法找到原交易，请检查merOrderId是否跟原交易一致。 |
否 |
OPERATION_NOT_ALLOWED |
当前不允许此操作 |
订单已经关闭，不能执行退货等操作。 |
否 |
TARGET_FAIL |
支付宝方支付失败，如请求没有成功，或者请求成功，但是没有正确处理。 |
支付宝或者微信方业务失败，请根据返回信息确定具体原因。 |
否 |
DUP_ORDER |
重复的订单请求 |
支付请求的merOrderId重复，请检查终端是否做过复位操作，导致流水号等重复。 |
是 |
NET_ERROR |
跟支付包通讯出问题，包括请求发送异常，报文应答不是200，请求被取消，应答超时等。 |
通讯问题，联系运行检查网络情况。 |
是 |
NO_MERCHANT |
找不到请求指定的商户 |
请求报文的mid在网付前置无法找到相关的配置，请确认终端的商户号是否正确在网付前置配置，是否经过转商户处理。 |
否 |
ORDER_PROCESSING |
订单正在处理中，不允许并发操作。 |
当前订单的上一次操作没有完成，订单处于锁定状态，请等待一分钟后再试。 |
否 |
INACTIVE_MERCHANT |
商户被置为inactive状态 |
交易商户在网付前置被冻结。 |
否 |
ABNORMAL_REQUEST_TIME |
请求时间异常 |
请求终端或者平台的系统时间不正常，请检查系统时间。 |
是 |
TXN_DISCARDED |
请求开始处理时间延迟过大，交易被丢弃。 |
系统负载过大，交易被丢弃，请联系运行。 |
是 |
BAD_SIGN |
签名错误 |
报文签名错误，请联系技术指导签名算法。 |
是 |
INVALID_MSGSRC |
商户来源错误 |
系统配置有问题，请联系技术。 |
是 |
INVALID_ORDER |
订单信息异常 |
该订单支付时有异常，缺少关键数据，请先做一笔订单查询，补充关键数据后再次进行退货等操作。 |
是 |
NO_CROSS_DAY_TRADING |
不允许跨日交易 |
可能某些渠道不支持跨日撤销，建议做退货。 |
否 |
DENIED_IP |
不允许此IP交易 |
IP不在白名单中，请联系管理员确认。 |
否 |
INVLID_MERCHANT_CONFIG |
错误的商户配置 |
商户配置参数有问题，请联系业务人员检查商户配置参数。 |
是 |
INVALID_RESPONSE |
无效的应答报文 |
支付渠道方的应答报文有问题，比如验签失败、报文格式错误等。 |
是 |
10、 status取值说明
取值 |
描述 |
备注 |
NEW_ORDER |
新订单 |
|
UNKNOWN |
不明确的交易状态 |
|
TRADE_CLOSED |
在指定时间段内未支付时关闭的交易；在交易完成全额退款成功时关闭的交易；支付失败的交易。 |
TRADE_CLOSED的交易不允许进行任何操作。 |
WAIT_BUYER_PAY |
交易创建，等待买家付款。 |
|
TRADE_SUCCESS |
支付成功 |
|
TRADE_REFUND |
订单转入退货流程 |
退货可能是部分也可能是全部。 |
11、 targetSys取值说明
取值 |
描述 |
备注 |
Alipay 1.0 |
支付宝1.0协议 |
比较少用 |
Alipay 2.0 |
支付宝2.0协议 |
主流 |
WXPay |
微信 |
|
YQB |
壹钱包 |
|
QMF |
全民付远程快捷 |
|
UnionPay |
银联钱包 |
|
BaiDu |
百度钱包 |
|
JD |
京东钱包 |
|
SF |
顺丰顺手付 |
|
COMM |
交通银行 |
|
BestPay |
翼支付 |
|
ACP |
银联全渠道立码付 |
|
NetPayBills |
银商网付平台账单模块 |
|
NetPayGtwy |
银商网付平台网关模块 |
|
QmfWebPay |
POS通插件WEB版 |
|