支付功能之代收代付

        有很多老板问小编：“这个分账功能好是好，也能搞定项目中的二清问题和税务纠纷，但还是太复杂了，每次要添加被分账对象都需要提交材料进行审核，太繁琐了，有没有更方便快捷的支付产品来解决资金问题？”

        那当然是有的，现在我们牛卡派推出了代收代付的支付功能，老板们只需要在后台添加姓名、银行卡和开户行无需审核即可输入具体的金额代发到其银行卡中，操作简单快捷，与分账不同，分账操作是根据每笔交易来进行下发资金，代收代付不按照比例分账，而是将具体的金额下发。

1.产品说明

1.1产品简介

三方支付机构的批量代付产品，用于商户向银行账户提出多笔转账交易。

1.2产品协议说明

• 支付请求是HTTP 协议请求，商户以POST 方式（Content-type 为：application/json）发
• 送到后台网站中。
• 此接口文档统一使用utf-8 编码方式。
• 请求参数列表中有必填/选填项，注意填写必填项。
• 参数名称和参数说明中规定的固定值必须与列表中完全一致（大小写敏感，除hmac参数值外）。

2数据交互

1.构造请求数据

• 商户根据支付机构提供的接口规则，通过程序生成得到签名结果及要传输给支付机构
• 的数据集合。

2.发送请求数据

• 把构造完成的数据集合，通过以JSON 的数据格式请求支付机构。

3.对请求数据进行处理

• 支付机构得到这些集合后，会先进行安全校验等验证，一系列验证通过后便会处理这
• 次发送过来的数据请求。

4.返回处理的结果数据

• 对于处理完成的交易，支付机构会以两种方式把数据反馈给商户网站。程序上自动进
• 行重新构造URL 地址链接，在用户当前页面上通过自动跳转的方式跳回商户在请求时设
• 定好的页面路径地址。

5.对返回数据进行处理

• 商户收到支付机构返回的结果数据后，可以结合自身网站的业务逻辑对数据进行处
• 理。

3.接口说明

3.1单笔代付接口

3.1.1业务功能

通过此接口商户可以付款到指定银行卡账户。

3.1.2交互模式

后台系统调用交互模式。

3.1.3请求参数列表

参数名称	参数含义	说明	数据类型	是否必填	签名顺序
userNo	商户编号	商户编号和商户密钥在商户后台获取	String	是	1

tradeMerchantNo	报备商户号	报备商户号	String	否	2
productCode	产品类型	产品类型	String	是	3
requestTime	交易请求时间	格式：yyyy-MM-dd HH:mm:ss 如：2018-05-28 18:00:00	String	是	4
merchantOrderNo	商户订单号	全局唯一，由数字或字母组成，长度须控制在 12 到 25 之间，可包含边界 值	String	是	5
receiverAccountNo Enc	收款账户号	收款人银行卡卡号	String	是	6
receiverNameEnc	收款人	收款人银行卡持卡人名称	String	是	7
receiverAccountTyp e	账户类型	对私账户：201 对公账户：204	Integer	是	8
receiverBankChann elNo	收款账户联行号	对公账户必须填写此字段	String	否	9
paidAmount	交易金额	单位：元，精确到分，保留两位小数。	BigDec imal	是	10
currency	币种	人民币币种填写：201	String	是	11
isChecked	是否复核	复核：201，不复核：202 (见注释 一)	String	是	12

paidDesc	代付说明	填写此次单笔代付的代付说明（长度 为 30 个字符以内）	String	是	13
paidUse	代付用途	代付用途	String	是	14
callbackUrl	商户通知地址	代付完成后异步回调通知地址	String	否	15
firstProductCode	优先使用产品	组合付必填，非组合付不用填写	String	否	16
hmac	签名数据		String	是

• 注释一
• 是否审核→填写为201 时，需到商户后台进行审核，审核通过支付机构才会进行打款，审核不通过，则订单状态为订单已取消（没有异步）；填写为202 时，不需要到商户后台进行审核，订单提交支付机构成功则开始打款。（代付金额：单位：元，精确到分，保留两位小数。例如：10.23）
• 注释二
• 产品类型：
• 普通代付：在工作日9:00-17:30 出款，使用“可取余额”，正常2 小时内到账，建议在17:00 前提交（并在商户后台审核）订单；

请求报文案例：

{
"userNo": "888100000004182",
"productCode": "BANK_PAY_ORDINARY_ORDER",
"hmac": "A5FFC45489254A0438D27628F346EC2C",
"requestTime": "2018-05-28 14:10:10",
"merchantOrderNo": "300000000001",
"receiverAccountNoEnc": "6225882010007926",
"receiverNameEnc": "支付机构",
"receiverAccountType": "201",
"receiverBankChannelNo": "",
"paidAmount": "1.00",
"currency": "201",
"isChecked": "202",
"paidDesc": "工资发放",
"paidUse": "201",
"callbackUrl":"http://10.10.10.10:8080/pay/merchantCallback"
}

3.1.4应答参数列表

参数名称	中文名称	说明	数据类型	是否必填	签名顺序
statusCode	应答码	请求响应的应答码	String	是	1
message	应答信息	请求响应的应答码信息描述	String	是	2
data	应答数据	见应答数据域	json 字符串	是
应答信息域(data)
errorCode	错误码	受理失败、受理中会在应答中返回错误码	String	否	3
errorDesc	错误描述	受理失败、受理中会在应答中返回错误码	String	否	4
userNo	商户编号	商户在支付平台系统的唯一身份标识	String	是	5
merchantOrderN o	商户订单号	全局唯一性，由商户生成并在发起代付 请求的时候传入	String	是	6
hmac	签名数据		String	是

应答报文案例：

{
"statusCode": 2001,
"message": "受理成功",
"data": {
"errorCode": "",
"errorDesc": "",
"userNo": "888100000002985",
"merchantOrderNo": "3000000000001",
"hmac": "B326EF80B13649C15415C19748FA78D7"
}
}

注：响应数据的顺序不代表签名的顺序，签名顺序请查阅文档的表格所对应的顺序。

3.1.5异步通知参数列表

交易成功或交易失败时异步通知以POST 请求方式返回Json 数据。如若通知响应statusCode 为
2001，则我司系统将进行补发通知，补发频率为5, 20, 60, 120, 180, 240s。

接入方对异步通知需要作幂等处理

参数名称	中文名称	说明	数据类型	是否 必填	签名顺 序
status	交易状态	代付明细的交易状态	Integer	是	1
errorCode	错误码	交易失败对应错误码	String	否	2
errorCodeDesc	错误描述	交易失败对应错误码描述	String	否	3
userNo	商户编号	商户在支付平台系统的唯一身份标识。	String	是	4
tradeMerchantNo	报备商户号	报备商户号	String	否	5
merchantOrderNo	商户订单号	全局唯一性，由商户生成并在发起 代付请求的时候传入	String	是	6
platformSerialNo	平台流水号	全局唯一性，成功受理商户的代付 请求时生成的流水号	String	是	7
receiverAccountNoEn c	收款账户号	收款账户号	String	是	8
receiverNameEnc	收款人	收款人信息	String	是	9
paidAmount	交易金额	交易金额	BigDecimal	是	10
fee	手续费	计算受理成功的订单所需额外支付 的费用	BigDecimal	是	11
completeTime	完成时间	代付完成时间，格式：yyyy-MM-dd HH:mm:ss 默认不返回，如果有此参数需求，请 联系支付机构客服。	String	否	12
hmac	签名数据		String	是

返回报文案例：

{
"fee": 0.11,
"merchantOrderNo": "130000000006",
"paidAmount": 52.00,
"platformSerialNo": "30032018052900031256",
"receiverAccountNoEnc": "6225882010007926",
"receiverNameEnc": "支付机构",
"status": 205,
"userNo": "888100000002020"
"hmac":"XXXXX"
}

注：响应数据的顺序不代表签名的顺序，签名顺序请查阅文档的表格所对应的顺序

3.1.6商户返回确认信息

参数名称	中文名称	说明	数据类型	是否必 填	签名顺序
statusCode	应答码	商户回调通知后返回的应答码	String	是	1
message	应答信息	商户接收回调通知后处理失 败返回的错误描述	String	否	2

应答报文案例：

{
"statusCode": "2001",
"message": "成功"
}

3.2单笔代付查询接口

3.2.1请求参数列表

注：请求返回交易状态未知时，需要调用查询接口核实订单状态!
仅能查询15 天内的订单。

参数名称	中文名称	说明	数据类型	是否 必填	签名 顺序
userNo	商户编号	商户在支付平台系统的唯一身份标识。	String	是	1
merchantOrderNo	商户订单号	全局唯一，由数字或字母组成，长度须控制在 12 到 25 之间，可包含边界值	String	是	2
hmac	签名数据		String	是

请求报文案例：

{
"userNo": "888100000004182",
"merchantOrderNo": "880000000001",
"hmac": "81D3430BF3E4A1D05958FE99FB5434A4"
}

3.2.2应答参数列表

参数名称	中文名称	说明	数据类型	是否必填	签名 顺序
statusCode	应答码	请求响应的应答码	String	是	1
message	应答信息	请求响应的应答码信息描述	String	是	2
data	应答数据	见应答信息域（应答信息域对象转成 json 字符串）	json 字符串	是
应答信息域
status	状态	单笔代付查询请求的交易状态	Integer	是	3
errorCode	错误码	交易失败返回错误码，	String	否	4
errorDesc	错误描述	受理失败、受理中会在应答中返回描述	String	否	5
userNo	商户号	商户在支付平台系统的唯一身份标识。	String	是	6
tradeMerchantN o	报备商户号	报备商户号	String	否	7
merchantOrder No	商户订单号	全局唯一性，由商户生成并在发起代付请 求的时候传入	String	是	8
platformSerialN o	平台流水号	全局唯一性，成功受理商户的代付请求时 生成的流水号	String	是	9
receiverAccount NoEnc	收款账户号	收款账户号信息	String	是	10
receiverNameEn c	收款人	收款人信息	String	是	11
paidAmount	交易金额	交易金额	BigDecimal	是	12
fee	手续费	计算受理成功的订单在该次代付交易中所 需额外支付的费用。	BigDecimal	否	13
completeTime	完成时间	代付完成时间,交易成功或失败时返回， 默认不返回，如果有此参数需求，联系客服	String	否	14
hmac	签名数据		String	是

应答报文成功案例：

{
"statusCode": 2001,
"message": "受理成功",
"data": {
"status": 203,
"errorCode": "",
"errorDesc": "",
"userNo": "888100000004182",
"merchantOrderNo": "880000000001",
"platformSerialNo": "30032018052900031237",
"receiverAccountNoEnc": "6225882010007926",
"receiverNameEnc": "支付机构",
"paidAmount": 1.00,
"fee": 0.11，
"hmac": "81D3430BF3E4A1D05958FE99FB5434A4"
}
}

应答报文订单不存在报文

{
"statusCode": 2001,
"message": "受理成功",
"data": {
"status": "214",
"errorCode": "300002014",
"errorDesc": "订单记录不存在",
"userNo": "888100000002720",
"merchantOrderNo": "8800eee00000001",
"platformSerialNo":"" ,
"receiverAccountNoEnc": "",
"receiverNameEnc": "",
"paidAmount": "",
"fee": "",
"hmac": "57396ca5bc0c1b6834f61bcb04bf0af2"
}
}

3.3批量代付接口

3.3.1请求参数列表

参数名称	中文名称	说明	数据类型	是否 必填	签名 顺序
userNo	商户编号	商户在支付平台系统的唯一身份标识。	String	是	1
productCode	产品类型	产品类型	String	是	2
merchantBatchN o	商户批次号	全局唯一，由数字或字母组成，长度须控 制在 12 到 25 之间，可包含边界值	String	是	3
requestCount	请求总笔数	须商户传入请求代付的总笔数核计	Integer	是	4
requestAmount	请求总金额	须商户传入请求代付的总金额核计	BigDecima l	是	5
requestTime	交易请求时间	格式：yyyy-MM-dd HH:mm:ss 如：2018-05-28 18:00:00	String	是	6
callbackUrl	商户通知地址	支付机构处理完请求后，处理结果页面跳 转到商户网站里指定的 http 地址。	String	否	7
firstProductCod e	优先使用产品	组合付必填，非组合付不用填写	String	否	8
details	代付明细数据	代付明细数据见子域（子域 List 转成json 字符串）	json 字符 串	是
代付明细数据域
userNo	商户编号	商户入网后生成的数字字符串	String	是	9
tradeMerchantN o	报备商户号	报备商户号	String	否	10
merchantOrderN o	商户订单号	全局唯一，由数字或字母组成，长度须控 制在 12 到 25 之间，可包含边界值	String	是	11
receiverAccount NoEnc	收款账户号	收款人银行卡卡号	String	是	12
receiverNameEn c	收款人	收款人银行卡持卡人名称	String	是	13

receiverAccount Type	账户类型	账户类型	Integer	是	14
receiverBankCh annelNo	收款账户联行号	对公账户必须填写此字段	String	否	15
paidAmount	交易金额	交易金额	BigDecima l	是	16
currency	币种	人民币：201	String	是	17
isChecked	是否复核	复核：201，不复核：202	String	是	18
paidDesc	代付说明	填写此次单笔代付的代付说明（长度为 30 个字符以内）	String	是	19
paidUse	代付用途	代付用途	String	是	20
hmac	签名数据		String	是

请求报文案例：

{
"userNo": "888100000004182",
"productCode": "BANK_PAY_ORDINARY_ORDER",
"hmac": "A47EB696F9C41EAE72010456B556CFDB",
"merchantBatchNo": "990000000001",
"requestCount": "2",
"requestAmount": "2.00",
"requestTime": "2018-05-28 14:10:10",
"callbackUrl":"http://10.10.10.10:8080/pay/merchantCallback",
"details": [{
"userNo": "888100000004182",
"merchantOrderNo": "880000000001",
"receiverAccountNoEnc": "6225882010007926",
"receiverNameEnc": "支付机构",
"receiverAccountType": "201",
"receiverBankChannelNo": "45545",
"paidAmount": "1.00",
"currency": "201",
"isChecked": "202",
"paidDesc": "工资发放",
"paidUse": "201"
},
{
"userNo": "888100000004182",
"merchantOrderNo": "880000000002",
"receiverAccountNoEnc": "6225882010007926",
"receiverNameEnc": "支付机构",
"receiverAccountType": "201",
"receiverBankChannelNo": "45545",
"paidAmount": "1.00",
"currency": "201",
"isChecked": "202",
"paidDesc": "工资发放",
"paidUse": "201"
}
]
}

3.3.2应答代付接口

参数名称	中文名称	说明	数据类 型	是否 必填	签名 顺序
statusCode	应答码	请求响应的应答码	String	是	1
message	应答信息	请求响应的应答码信息描述	String	是	2
data	应答数据	代付数据见应答信息域（应答信息域对象转 成 json 字符串）	json 字符 串	是
应答数据域
errorCode	错误码	受理失败、受理中会在应答中返回错误码	String	否	3
errorDesc	错误描述	受理失败、受理中会在应答中返回错误码	String	否	4
userNo	商户编号	商户在支付平台系统的唯一身份标识。	String	是	5
merchantBatchN o	商户批次号	全局唯一性，由商户生成并在发起代付请求 的时候传入	String	是	6
acceptSuccessC ount	受理成功笔数	已受理商户批量请求笔数的累加	Integer	是	7

acceptFailCount	受理失败笔数	没有受理商户批量请求笔数的累加	Integer	是	8
requestCount	请求总笔数	商户请求的批量请求笔数总和	Integer	是	9
requestAmount	请求总金额	商户请求的批量请求金额总和	BigDeci mal	是	10
hmac	签名数据	参考 5.签名机制	String	是

应答报文案例：

{
"statusCode": 2001,
"message": "受理成功"
"data": {
"errorCode": "",
"errorDesc": "",
"userNo": "888100000004182",
"merchantBatchNo": "990000000001",
"acceptSuccessCount": 2,
"acceptFailCount": 0,
"requestCount": 2,
"requestAmount": 2.00,
"hmac": "81D3430BF3E4A1D05958FE99FB5434A4"
},
}

3.3.3异步通知参数列表

交易成功或交易失败时异步通知以 POST 请求方式返回 Json 数据。如若通知响应 statusCode 为

2001，则我司系统将进行二次补发通知，补发频率为 5, 20, 60, 120, 180, 240s。

接入方对异步通知需要作幂等处理。

参数名称	中文名称	说明	数据类型	是否 必填	签名 顺序
status	状态	批量代付请求的交易状态	Integer	是	1
userNo	商户号	商户在支付平台系统的唯一身份标识。	String	是	2
merchantBatchNo	商户批次号	全局唯一性，由商户生成并在发起代付请 求的时候传入	String	是	3
platformBatchNo	支付批次号	全局唯一性，成功受理商户的代付请求时 生成的批次号	String	否	4
successCount	成功笔数	成功处理的笔数累加	Integer	是	5
successAmount	成功金额	成功处理的金额累加	BigDecimal	是	6
failCount	失败笔数	处理失败的笔数累加	Integer	是	7
failAmount	失败金额	处理失败的金额累加	BigDecimal	是	8
processCount	处理中笔数	在处理中的笔数累加	Integer	是	9

processAmount	处理中金额	在处理中的金额累加	BigDecimal	是	10
requestCount	请求总笔数	商户请求的批量请求笔数总和	Integer	是	11
requestAmount	请求总金额	商户请求的批量请求金额总和	BigDecimal	是	12
acceptCount	受理总笔数	受理商户批量请求笔数的累加	Integer	是	13
acceptAmount	受理总金额	受理商户批量请求金额的累加	BigDecimal	是	14
feeSum	总手续费	成功订单计算的手续费总和	BigDecimal	否	15
singleNotifyList	批量明细列 表	代付明细数据见子域（子域 List 转成json 字符串）	json 数据字 符串	是	16
批量明细列表域
status	状态	代付明细交易状态	Integer	是	17
errorCode	错误码	受理失败、受理中会在应答中返回错误码	String	否	18
errorCodeDesc	错误描述	受理失败、受理中会在应答中返回错误码	String	否	19
userNo	商户编号	商户在支付平台系统的唯一身份标识。	String	是	20
tradeMerchantNo	报备商户号	报备商户号	String	否	21
merchantOrderNo	商户订单号	全局唯一性，由商户生成并在发起代付请求的时候传入	String	是	22
platformSerialNo	平台流水号	全局唯一性，在成功受理商户的代付请求 时生成的流水号	String	否	23
receiverAccount NoEnc	收款账户号	收款账户号信息	String	是	24
receiverNameEnc	收款人	收款人信息	String	是	25
paidAmount	交易金额	此订单交易金额	BigDecimal	是	26
fee	手续费	此成功订单在该次代付交易中所需额外支 付的费用。	BigDecimal	否	27
completeTime	完成时间	代付完成时间，格式：yyyy-MM-dd HH:mm:ss 默认不返回，如果有此参数需求，请联系客服。	String	是	28
hmac	签名数据		String	是

请求报文案例：

{
"status": 203,
"successAmount": 2.00,
"successCount": 2,
"userNo": "888100000004182"
"hmac": "81D3430BF3E4A1D05958FE99FB5434A4"
"acceptAmount": 2.00,
"acceptCount": 2,
"failAmount": 0.00,
"failCount": 0,
"feeSum": 0.22,
"merchantBatchNo": "990000000001",
"platformBatchNo": "20022018053100002949",
"processAmount": 0.00,
"processCount": 0,
"requestAmount": 2.00,
"requestCount": 2,
"hmac": "81D3430BF3E4A1D05958FE99FB5434A4"
"singleNotifyList": [{ "fee": 0.11,
"merchantOrderNo": "880000000002",
"paidAmount": 1.00,
"platformSerialNo": "30032018053100031394",
"receiverAccountNoEnc": "6225882010007926", "receiverNameEnc": "支付机构",
"status": 205,
"userNo": "888100000004182"}, {"fee": 0.11,
"merchantOrderNo": "880000000001",
"paidAmount": 1.00,
"platformSerialNo": "30032018053100031393",
"receiverAccountNoEnc": "6225882010007926", "receiverNameEnc": "支付机构",
"status": 205,
"userNo": "888100000004182"}],
}

3.3.4商户返回确认信息

参数名称	中文名称	说明	数据类 型	是否 必填	签名 顺序
statusCode	应答码	商户受理回调通知后返回的应答码	String	是	1

message

应答信息

商户受理回调通知后处理失败返回的错 误描述

String

否

2

应答报文案例：

{
"statusCode": "2001", 
" message ": "成功"
}

3.4余额查询

3.4.1请求参数列表

参数名称	中文名称	说明	数据类型	是否必填	签名 顺序
userNo	商户编号	商户在支付平台系统的唯一身份标识。	String	是	1
hmac	签名数据		String	是

请求报文案例：

{"userNo": "888100000000002","hmac": "484F1C01DED2A9176B17C6AFC11DA219"}

注：以上案例仅限于格式的参考，并不能作为真实数据发起请求。

3.4.2应答参数接口

参数名称	中文名称	说明	数据类型	是否 必填	签名 顺序
statusCode	应答码	请求响应的应答码	String	是	1
message	应答信息	请求响应的应答码信息 描述	String	是	2
data	应答数据	数据见应答信息域（应答信息域对象转成 json 字符串）	json 字符串	是
应答数据域（data）

userNo	商户号	商户在支付平台系统的 唯一身份标识。	String	是	3
userName	商户名称	商户在支付平台系统注 册的名称	String	是	4
currency	币种	余额账户统一记录的币种 人民币：201	Integer	是	5
useAbleSettAmount	可取金额	除去风控冻结金额剩余 的可结算金额	BigDecimal	是	6
availableSettAmount Frozen	可结算冻结金额	代付处理中的金额	BigDecimal	是	7
errorCode	错误码	受理失败、受理中会在应答中返回错误码	String	否	8
errorDesc	错误描述	受理失败、受理中会在应答中返回错误信息	String	否	9
hmac	签名数据		String	是

应答报文案例：

{"data": {"userNo": "888100000004182","userName": "支付机构", "currency": 201,"useAbleSettAmount": 29233.05,"availableSettAmountFrozen": 82982.81, "errorCode": "","errorDesc": "","hmac": "484F1C01DED2A9176B17C6AFC11DA219"},"statusCode": 2001, "message": "查询成功"}

注：响应数据的顺序不代表签名的顺序，签名顺序请查阅文档的表格所对应的顺序

4.签名机制

为了保证数据传输过程中的数据真实性和完整性，我们需要对请求和返回数据进行签名，在接收签名数据之后进行签名校验。
签名按照参数的签名顺序将参数的值拼接后将密钥拼接在后面，生成签名的原始串，再按照相应的加密方法进行加密计算出签名的结果。

4.1待签名字符串

无论是请求还是应答，都按照以下方式拼接待签名字符串：
1、除hmac 字段外，所有参数按照文档要求的顺序设值，并参与拼接待签名字符串。
2、在待签名字符串中，字段名和字段值都采用原始值，不进行URL Encode。
3、空值及null 不参与验签。

4.2MD5签名

商户支付：签名方式，在商户入网时，由商户后台自行选择MD5 还是RSA 方式。
采用MD5 算法进行签名。在MD5 签名时需要商户密钥参与签名，商户密钥是以英文字母和数字组成的32 位字符串，商户可以登录汇聚支付门户系统，查看密钥信息。通过在待签名字符串后加商户密钥的内容，进行MD5 运算，形成的摘要字符串为签名结果。