代付接口文档

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得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

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

    Map signMap = new HashMap<>();
    signMap.put("userId", "test01");
    signMap.put("type", "wechat");
    signMap.put("money", Double.valueOf(2));
    signMap.put("remark", "");
    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. 申请代付

接口描述

商户通过代付接口发起代付申请，支付系统收到请求后同步返回申请结果，申请成功并不代表代付成功。
商户有两种方式确定代付结果：
1）发起代付时传递代付结果回调地址，支付系统处理代付确定结果后会向改地址发起通知请求。
2）商户系统客户主动发起代付查询，以查询到的最终结果确定代付是否成功。
注意：商户访问该接口需要申请IP白名单。

接口链接

URL地址：https://域名(联系运营人员获取)/api/agentpay/apply
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long	20001222	分配的商户号
商户代付单号	mchOrderNo	是	String(30)	20160427210604000490	商户代付订单号
代付金额	amount	是	int	8000	代付金额,单位分
收款人账户名	accountName	是	String(64)	manager	收款人账户名
收款人账户号	accountNo	是	String(64)	6222020200098541458	收款人账户号
开户行名称	bankName	是	String(128)	北京银行	开户行名称
开户行所在省份	province	否	String(32)	北京	开户行所在省份
开户行所在市	city	否	String(32)	北京	开户行所在市
开户支行	bankNetName	否	String(128)	北京上地支行	支行网点
联行号	bankNumber	否	String(64)		开户行行号
银行编码	bankCode	否	String(32)	ICBC	银行编码，可咨询客服获取编码表
商户来源商家号	mchSourceNo	否	String(512)	test	商户来源商家号
代付通道	passageId	否	int	123	如果指定通道代付，请传入通道Id
账户属性	accountAttr	否	Byte	0	0-对私,1-对公,默认对私
代付结果回调URL	notifyUrl	否	String(128)	http://notify.xxx.com	代付结果回调URL（NO_NOTIFY则表示不回调）
扩展域	extra	否	String(128)		扩展域
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

Content-Type：application/json

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
返回信息	retMsg	否	String(128)	签名失败	返回信息
代付单号	agentpayOrderId	是	String(30)	G01201810090642059440884	支付系统生成的代付订单号
手续费	fee	是	long	100	手续费，单位分
扩展域	extra	否	String(128)		扩展域
状态	status	是	int	1	状态:0-待处理,1-处理中,2-成功,3-失败
签名	sign	是	String(32)	6012FB85432A4BBAA309985A1C054219	签名值

3. 查询代付订单

接口描述

商户通过该接口查询代付订单结果，并根据状态结果进一步处理业务逻辑。

接口链接

URL地址：https://域名(联系运营人员获取)/api/agentpay/query_order
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

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

返回结果

Content-Type：application/json

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
返回信息	retMsg	否	String(128)	签名失败	返回信息
商户订单号	mchOrderNo	是	String(30)	AP1538919309174	商户生成的订单号
代付订单号	agentpayOrderId	是	String(30)	G01201810070935094340418	支付中心生成的订单号
币种	currency	是	String(128)	CNY	三位货币代码,人民币:CNY
代付金额	amount	是	long	119	代付金额,单位分
手续费	fee	是	long	3	手续费,单位分
状态	status	是	int	1	状态:0-待处理,1-处理中,2-成功,3-失败
转账提示	transMsg	否	String(128)		转账提示
签名	sign	是	String(32)	3B166CA71811D4A0FEC25D511A365ED3	签名值，详见签名算法

4. 支付结果通知

接口描述

当代付处理完成后，支付系统会通过该接口向商户发起通知。

接口链接

该链接是通过代付申请接口提交的参数notifyUrl设置，如果无法访问链接，业务系统将无法接收到支付中心的通知。
Content-Type：application/x-www-form-urlencoded
Method：POST

通知参数（QueryString）

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long	20001222	分配的商户号
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户代付订单号
商户来源商家号	mchSourceNo	否	String(512)	test	商户来源商家号
代付单号	agentpayOrderId	是	String(30)	G01201810090642059440884	支付中心生成的订单号
状态	status	是	int	1	状态:0-待处理,1-处理中,2-成功,3-失败
代付金额	amount	是	long	119	代付金额,单位分
手续费	fee	是	long	3	手续费，单位分
转账提示	transMsg	否	String(128)		转账提示
扩展域	extra	否	String(128)		扩展域
签名	sign	是	String(32)	3B166CA71811D4A0FEC25D511A365ED3	签名值，详见签名算法

返回结果

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

6. 代付反查

接口描述

需要商户提供对外反查api给支付中心，支付中心将按照下列参数格式反查订单。

接口链接

URL地址：优先取商户开通代付通道中的配置，其次取商户信息中的配置，都没配置则表示关闭反查
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数（QueryString）

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long	20001222	分配的商户号
通道ID	passageId	是	int	8	代付通道Id
商户代付单号	mchOrderNo	是	String(30)	20160427210604000490	商户代付订单号
商户来源商家号	mchSourceNo	否	String(512)	test	商户来源商家号
收款人账户号	accountNo	是	Number	6222020200098541458	收款人账户号
代付金额	amount	是	int	8000	代付金额,单位分
扩展域	extra	否	String(128)		扩展域
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

业务系统处理后返回给支付中心，返回字符串 success 则表示成功继续进行代付，返回非success则表示中止这单代付

7. 代付订单反查接口

接口描述

支付中心对外提供反查api，请求方将按照下列参数格式完成代付订单的反向检查。

接口链接

URL地址：https://域名(联系运营人员获取)/api/agentpay/check
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long	1000000010	分配的商户号
商户订单号	mchOrderNo	是	String(30)	AP1538919309174	商户生成的订单号，与agentpayOrderId二者传一即可
代付订单号	agentpayOrderId	是	String(30)	G01201810070935094340418	支付中心生成的订单号，与mchOrderNo二者传一即可
代付金额	amount	是	int	8000	代付金额,单位分
收款人账户号	accountNo	是	String(64)	6222020200098541458	收款人账户号
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

支付中心处理后返回字符串 success 则表示通过校验可继续进行代付，返回非success则表示代付订单校验未通过可中止代付

8. 查询余额

接口描述

商户可通过该接口查询账户余额。

接口链接

URL地址：https://域名(联系运营人员获取)/api/agentpay/query_balance
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long	20001222	分配的商户号
请求时间	reqTime	是	String(20)	20181009171032	请求发起时间,时间格式:yyyyMMddHHmmss
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

Content-Type：application/json

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
可用代付余额	availableAgentpayBalance	是	long	943618	商户可用代付余额
代付余额	agentpayBalance	是	long	943618	代付余额
保证金金额	securityMoney	是	long	943618	保证金金额
可用结算余额	availableSettAmount	否	long	943618	当前可用结算余额(代收代付分离账户时返回)
结算余额	settAmount	否	long	943618	结算余额(代收代付分离账户时返回)
签名	sign	是	String(32)	26319C79C2E5A581744C22AD3B61F9F3	签名值

6. 银行编码表

银行名称	银行编码
CIMBBANK	CIMB
vikkibank	DAB
HSBC	HSBC
CAKE by VPBank	CAKE
UBANK BY VPBANK	UBANK
DBS	DBS
NONGHYUP	NHBHN
Saigonbank	SGN
MHB	MHB
Sacombank	SACB
Agribank	AGB
DongA	DAB
GPbank	GPB
BacAbank	NASB
Standard Chartered Vietnam	SCBL
PVcombank	PVCB
Oceanbank	OJB
Vietinbank	VTB
ACB	ACB
BIDV	BIDV
Quoc Dan	NCB
VRbank	VRB
MBbank	MB
TPbank	TPB
Shinhanbank	SHBVN
ABbank	ABB
MSB	MSB
VietAbank	VAB
NamAbank	NAMABA
SCB	SCB
PGbank	PGB
Eximbank	EIB
VPbank	VPB
Vietbank	VB
Indovinabank	IVB
Vietcombank	VCB
HDbank	HDB
BaoVietbank	BVB
Seabank	SEAB
VIB	VIB
HONGLEONG	HLB
SHB	SHB
CBbank	CB
OCB	OCB
Lienvietbank	LPB
KienLongbank	KLB
BanVietbank	VCPB
IBK	IBK
IBK HCM	IBKHCM
Wooribank	WB
UOB	UOB
Kookminbank	KOOKMI
Techcombank	TCB
QuocDan	NCB
BVBank	VCPB
CAKEbyVPBank	CAKE