支付接口文档

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. 统一下单

接口描述

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

接口链接

URL地址：https://apipay.jiefu168.xyz/api/pay/create_order

请求参数

字段名	变量名	必填	签名	类型	示例值	描述
商户ID	mchId	是	是	long	20001222	分配的商户号
支付产品ID	productId	是	是	int	8000	支付产品ID
商户订单号	mchOrderNo	是	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	是	int	100	支付金额,单位分
客户端IP	clientIp	否	是	String(32)	210.73.10.148	客户端IP地址
设备	device	否	是	String(64)	ios10.3.1	客户端设备
支付结果前端跳转URL	returnUrl	否	是	String(128)	https://merchant.example.com/return.htm （商户填写自己的支付完成同步跳转地址）	支付结果同步跳转URL
支付结果后台回调URL	notifyUrl	是	是	String(128)	https://merchant.example.com/notify.htm （商户填写自己的异步回调地址）	支付结果异步通知URL
商品主题	subject	是	是	String(64)	测试商品1	商品主题
商品描述信息	body	是	是	String(256)	聚合测试商品描述	商品描述信息
扩展参数1	param1	否	是	String(64)		支付中心回调时会原样返回
会员姓名	param2	否	是	String(64)		卡转卡通道必传
附加参数	extra	是	是	String(512)	abcd	额外参数,预留参数
签名	sign	是	否	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
返回信息	retMsg	否	String(128)	签名失败	返回信息，如非空，为错误原因签名失败参数格式校验错误

以下字段在retCode为SUCCESS的时候有返回

字段名	变量名	必填	类型	示例值	描述
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
支付订单号	payOrderId	是	String(32)	20160427210604000490	支付中心生成的订单号
支付参数	payParams	是	JSONObject	{payMethod: "formJump", payUrl: "支付Url" }	统一返回支付链接，获取payUrl即可

3. 查询支付订单

接口描述

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

接口链接

URL地址：https://apipay.jiefu168.xyz/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)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
返回信息	retMsg	否	String(128)	签名失败	返回信息，如非空，为错误原因签名失败参数格式校验错误

以下字段在retCode为SUCCESS的时候有返回

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long(30)	20001222	支付中心分配的商户号
支付产品ID	productId	是	int	8001	支付产品ID
支付订单号	payOrderId	是	String(30)	P20160427210604000490	支付中心生成的订单号
商户订单号	mchOrderNo	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	int	100	支付金额,单位分
币种	currency	是	String(3)	cny	三位货币代码,人民币:cny
状态	status	是	int	1	支付状态,0-订单生成,1-支付中,2-支付成功,3-业务处理完成
渠道用户ID	channelUser	否	String(64)		渠道测支付时使用的用户ID
渠道订单号	channelOrderNo	否	String	wx20170910211043fb206e92260071822007	对应的第三方支付订单号
渠道数据包	channelAttach	否	String	{"bank_type":"CMB_DEBIT","trade_type":"pay.weixin.micropay"}	支付渠道数据包
支付成功时间	paySuccTime	否	Long	1505049094262	支付成功时间

4. 支付结果通知

接口描述

接口链接

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

通知参数

字段名	变量名	必填	签名	类型	示例值	描述
支付订单号	payOrderId	是	是	String(30)	P20160427210604000490	支付中心生成的订单号
商户ID	mchId	是	是	String(30)	20001222	支付中心分配的商户号
支付产品ID	productId	是	是	int	8001	支付产品ID
商户订单号	mchOrderNo	是	是	String(30)	20160427210604000490	商户生成的订单号
支付金额	amount	是	是	int	100	支付金额,单位分
实际支付金额	income	是	是	int	100	实际支付金额,单位分
状态	status	是	是	int	1	支付状态,0-订单生成,1-支付中,2-支付成功,3-业务处理完成
渠道订单号	channelOrderNo	否	是	String(64)	wx2016081611532915ae15beab0167893571	三方支付渠道订单号
渠道数据包	channelAttach	否	是	String	{"bank_type":"CMB_DEBIT","trade_type":"pay.weixin.micropay"}	支付渠道数据包
扩展参数1	param1	否	是	String(64)		支付中心回调时会原样返回
扩展参数2	param2	否	是	String(64)		支付中心回调时会原样返回
支付成功时间	paySuccTime	是	是	long		精确到毫秒
通知类型	backType	是	是	int	1	通知类型，1-前台通知，2-后台通知
签名	sign	是	否	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

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

6. 查询商户余额

接口描述

业务系统查询余额。

接口链接

URL地址：/api/account/mch_balance

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	1000000010	支付中心分配的商户号
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
返回信息	retMsg	否	String(128)	签名失败	返回信息，如非空，为错误原因签名失败参数格式校验错误

以下字段在retCode为SUCCESS的时候有返回

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long(30)	20001222	支付中心分配的商户号
总余额	balance	是	int	1000	总余额,单位分
可用余额	availableBalance	是	int	1000	可用余额,单位分

产品ID	产品名称	支付类型
8000	支付宝转卡	支付宝转卡
8001	微信H5	微信H5
8002	支付宝H5	支付宝H5
8003	网银网关	网银网关
8004	卡转卡	卡转卡
8005	闲鱼SDK	闲鱼SDK
8006	支付宝原声H5	支付宝原声H5
8007	支付宝原声SDK	支付宝原声SDK
8008	手淘现金红包	手淘现金红包
8009	微信H5话费	微信H5话费
8010	天猫支付宝	天猫支付宝
8011	原生html	原生html
8102	支付宝网关	支付宝网关
8108	微信扫码	微信扫码
8109	支付宝话费h5	支付宝话费h5
8110	微信话费h5	微信话费h5

7. 错误码

错误码值	描述	原因	解决方案
0010	系统错误	系统超时或异常	系统异常，请用相同参数重新调用

代付接口文档

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://apipay.jiefu168.xyz/api/agentpay/apply

请求参数

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	long	20001222	分配的商户号
代付产品ID	productId	是	int	8000	代付产品ID
商户代付单号	mchOrderNo	是	String(30)	20160427210604000490	商户代付订单号
代付金额	amount	是	int	8000	代付金额,单位分
账户属性	accountAttr	否	Byte	0	0-对私,1-对公,默认对私
收款人账户名	accountName	是	String(64)	manager	收款人账户名
收款人账户号	accountNo	是	Number	6222020200098541458	收款人账户号
开户行所在省份	province	否	String(32)	北京	开户行所在省份
开户行所在市	city	否	String(32)	北京	开户行所在市
开户行名称	bankName	否	String(128)	北京上地支行	开户行名称
联行号	bankNumber	否	String(64)	11473707055	联行号
代付结果回调URL	notifyUrl	否	String(128)	https://merchant.example.com/agentpay/notify （商户填写自己的代付结果异步通知地址）	代付结果异步通知URL
备注	remark	是	String(128)	代付1000元	备注
扩展域	extra	否	String(128)		扩展域
请求时间	reqTime	是	String(20)	20181009171032	请求发起时间,时间格式:yyyyMMddHHmmss
签名	sign	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

返回结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	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://apipay.jiefu168.xyz/api/agentpay/query_order

请求参数

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

返回结果

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

4. 支付结果通知

接口描述

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

接口链接

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

通知参数

字段名	变量名	必填	类型	示例值	描述
代付单号	agentpayOrderId	是	String(30)	G01201810090642059440884	支付中心生成的订单号
商户单号	mchOrderNo	是	String(30)	G01201810090642059440884	商户订单号
代付金额	amount	是	int	100000	代付金额,单位分
状态	status	是	int	1	状态:0-待处理,1-处理中,2-成功,3-失败
手续费	fee	是	long	3	手续费，单位分
转账提示	transMsg	否	String(128)		转账提示
扩展域	extra	否	String(128)		扩展域
请求时间	reqTime	是	String(20)	20181009171032	请求发起时间,时间格式:yyyyMMddHHmmss
签名	sign	是	String(32)	3B166CA71811D4A0FEC25D511A365ED3	签名值，详见签名算法

返回结果

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

5. 查询余额

接口描述

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

接口链接

URL地址：https://apipay.jiefu168.xyz/api/agentpay/query_balance

请求参数

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

返回结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	retCode	是	String(16)	SUCCESS	SUCCESS/FAIL此字段标识是否成功
可用代付余额	availableAgentpayBalance	是	long	943618	商户可用代付余额
代付余额	agentpayBalance	是	long	943618	代付余额
签名	sign	是	String(32)	26319C79C2E5A581744C22AD3B61F9F3	签名值

越南银行编码

银行编码	银行名称
BacABank	BacABank
DongaBank	Donga Bank
SeABank	SeABank
TPBank	TP Bank
VietCapitalBank	VietCapitalBank
ABBANK	AB BANK
NamABank	Nam A Bank
MSB	MSB
KienLongBank	KienLongBank
VPBank	VPBank
OCB	OCB Vietnam
HDBank	HDBank
MilitaryBank	Military Bank
VIBBank	VIBBank
PVcombank	PVcombank
Sacombank	Sacombank
VietABank	VietABank
BaoVietBank	BaoVietBank
Eximbank	Eximbank
LienVietPostBank	LienVietPostBank
PGBank	PG Bank
VietinBank	VietinBank
BIDV	BIDV
Vietcombank	Vietcombank
SAIGONBANK	SAIGONBANK
SHB	SHB
CBBANK	C B BANK
GPBank	GPBank
Agribank	Agribank
TCBTechcombank	TCB Techcombank
MBmbbank	MB mbbank
MaritimeBank	Maritime Bank
Oceanbank	Oceanbank
EIB	EIB
STB	STB
SCB	SCB
ShinhanBank	ShinhanBank
ACB	ACB
NCB	National Citizen Bank
IndovinaBank	IndovinaBank
HSBC	HSBC
CIMBBank	CIMBBank

7. 错误码

错误码值	描述	原因	解决方案
0010	系统错误	系统超时或异常	系统异常，请用相同参数重新调用

支付接口文档

1. 协议规则

1.1 参数规范

1.2 安全规范

2. 统一下单

以下字段在retCode为SUCCESS的时候有返回

3. 查询支付订单

返回结果

以下字段在retCode为SUCCESS的时候有返回

4. 支付结果通知

接口链接

通知参数

返回结果

6. 查询商户余额

返回结果

以下字段在retCode为SUCCESS的时候有返回

6. 支付产品

7. 错误码

代付接口文档