商户对接文档(所有字段均传字符串类型)

扫码支付

1：请求地址

http://localhost:10081/gateway/scan

2：商户请求数据，表单提交

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长30 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 productName 商品描述信息 变长64 是
03 orderPeriod 订单过期时间 变长4 订单过期时间，单位：小时 是
04 orderPrice 订单金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
05 payWayCode 扫码类型 变长8 支付宝：ALI_SCAN
微 信：WEIXIN_SCAN
QQ钱包：QQ_SCAN
百度扫码：BAIDU_SCAN
银联扫码：UNION_SCAN
京东扫码：JD_SCAN 		是
06 osType 支付设备系统类型 变长2 PC端：0
移动端：1		 是
07 notifyUrl 服务器异步通知页面路径 变长128 交易完成后，快付支付平台会按照此地址将交易结果以后台的方式发送到商户网站。
在后端支付请求中，notifyUrl为必填,否则无法将支付结果通知到商户网站。		 是
07 returnUrl 支付成功后跳转地址 变长128 支付成功后，如果上游的系统允许商户跳转自带的成功页面
不一定会按照填写的地址进行跳转		 是
08 payKey 支付key 固定长32 商户支付标识 是
10 sign 签名 固定长32 参见《签名与验签》 是

3：响应数据列表，JSON格式

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长32 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 orderPrice 订单金额 变长13 是人民币，且以元为单位
例如：1.00（1元），0.01（1分）		 是
03 payKey 支付key 固定长32 商户支付标识 是
04 payURL 二维码URL 变长128 商户可以用改链接地址，渲染成适配的扫码页面 是
05 statusCode 状态码 固定长2 00（订单生成成功）
其他值（失败）		 是
06 msg 信息 无固定长度 一些附带说明 否
07 sign 签名 固定长32 参见《签名与验签》 是

4：成功样例


{
 "orderNo": "1507966197960",
 "sign": "0D3F39874AF0B6F07C4AB5230FC7E55F",
 "orderPrice": "0.01",
 "payKey": "9ae9ef6d094d4de69bb5dc19abf48ec9",
 "payURL": "https://qr.alipay.com/bax04483swjy46gkbvms604e",
 "statusCode": "00",
 "msg":"请求成功"
}

5：失败样例

{
 "payKey": "9ae9ef6d094d4de69bb5dc19abf48ec9",
 "statusCode": "01",
 "msg":"获取二维码失败"
}

H5支付

1：请求地址

http://localhost:10081/gateway/h5

2：H5产品说明

H5应用产品都是在移动端使用，用户点击支付按钮，页面会自动拉起相应的APP。例如：拉起微信进行支付、拉起支付宝、拉起QQ等。

3：商户请求数据

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长30 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 productName 商品描述信息 变长64 是
03 orderPeriod 订单过期时间 变长4 订单过期时间，单位：小时 是
04 orderPrice 付款金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
05 payWayCode 支付类型 变长8 微信 H5 支付： WEIXIN_H5
支付宝H5支付： ALI_WAP
QQ H5 支付： QQ_H5
银联H5支付： UNION_H5 		是
06 osType 支付设备系统类型 变长2 PC端：0
移动端：1		 是
07 notifyUrl 服务器异步通知页面路径 变长128 交易完成后，快付支付平台会按照此地址将交易结果以后台的方式发送到商户网站。
在后端支付请求中，notify_url为必填,否则无法将支付结果通知到商户网站。		 是
08 sceneType 场景类型 变长10 场景类型
IOS:0
Android:1
Wap:2		 是
09 appName APP名称 变长128 场景类型sceneType=0、1时必填
例如：王者荣耀
否则不填		 否
10 bundleId 绑定ID 变长128 场景类型sceneType=0时必填
例如：com.tencent.wzryIOS
否则不填		 否
11 packageName 包名 变长128 场景类型sceneType=1时必填
例如：com.tencent.tmgp.sgame
否则不填		 否
12 wapUrl WAP网站URL 变长128 场景类型sceneType=2时必填
例如：https://pay.qq.com
否则不填		 否
14 payKey 支付key 固定长32 商户支付标识 是
16 sign 签名 固定长32 参见《签名与验签》 是

4：H5支付产品，无数据返回。商户在提交数据后，会自动拉起APP。

收银台支付

1：请求地址

http://localhost:10081/gateway/syt

2：产品说明

收银台是上游提供完整的用户交互界面，无需商户自己渲染交互页面。因此收银台没有参数返回。

3：商户请求数据

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长30 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 productName 商品描述信息 变长64 是
03 orderPeriod 订单过期时间 变长4 订单过期时间，单位：小时 是
04 orderPrice 付款金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
05 payWayCode 支付类型 变长8 微信收银台：WEIXIN_SYT
QQ钱包收银台：QQ_SYT
银联收银台：UNION_SYT
支付宝收银台：ALI_SYT		 是
06 osType 支付设备系统类型 变长2 PC端：0
移动端：1		 是
07 notifyUrl 服务器异步通知页面路径 变长128 交易完成后，快付支付平台会按照此地址将交易结果以后台的方式发送到商户网站。
在后端支付请求中，notify_url为必填,否则无法将支付结果通知到商户网站。		 是
08 payKey 支付key 固定长32 商户支付标识 是
10 sign 签名 固定长32 参见《签名与验签》 是

快捷支付

1：请求地址

http://localhost:10081/gateway/fast

2：产品说明

快捷支付的用户交互页面，由上游提供，故此商户发送请求数据后，没有数据返回。

3：商户请求数据

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长30 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 productName 商品描述信息 变长64 是
03 orderPeriod 订单过期时间 变长4 订单过期时间，单位：小时 是
04 orderPrice 付款金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
05 payWayCode 支付类型 变长8 快捷支付：SCAN_FAST 是
06 osType 支付设备系统类型 变长2 PC端：0
移动端：1		 是
07 notifyUrl 服务器异步通知页面路径 变长128 交易完成后，快付支付平台会按照此地址将交易结果以后台的方式发送到商户网站。
在后端支付请求中，notify_url为必填,否则无法将支付结果通知到商户网站。		 是
08 returnUrl 页面跳转同步通知页面路径 变长128 交易完成后，快付支付平台会按照此地址将用户的交易结果页面重定向到商户网站。为保证商户能收到交易的结果，则必须至少提交ret_url，notify_url其中之一,前端支付请求必须传递returnUrl，否则无法正常返回商户网站 否
09 payKey 支付key 固定长32 商户支付标识 是
10 bankName 银行编号 固定长10 详细参见：附录 是
11 payType 支付卡种 固定长2 借记卡：01
贷记卡：02
暂时只支持借记卡		 是
12 certificateNo 身份证 变长20 开户人身份证 是
12 accountNo 银行卡号 变长20 银行卡的卡号 是
12 accountName 姓名 变长20 持卡者姓名 是
12 mobileNo 手机号码 变长20 跟银行卡绑定 是
14 sign 签名 固定长32 参见《签名与验签》 是

支付回调（post方式）

1：说明

客户支付成功后，平台向商户发起异步通知，通知地址为下单请求中传递给平台的notifyUrl地址(建议在接收到回调后验》证签名和判断状态)。 商户程序处理完业务逻辑后，需要返回success到平台，平台就不会再发起通知了； 否则会按照这个规律发起通知

2：回调机制

第N次 间隔时间(单位分钟)
第1次 0min
第2次 2min
第3次 5min
第4次 15min
第5次 30min

3：商户回调参数

{{/**/}}
序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长32 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 orderPrice 订单金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
02showPrice展示付款金额变长13是人民币，且以元为单位。展示在用户面前的金额。 是
02 factPrice 实际付款金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
03 orderTime 商户订单日期 定长14 商户生成订单的日期，格式yyyyMMddHHmmss 是
04 trxNo 平台交易流水号 固定长20 是
05 statusCode 状态码 固定长2 00（查询操作成功）
其他值（失败）		 是
06 tradeStatus 交易状态 变长 20 详见《交易状态说明》 是
08 payKey 支付key 固定长32 商户支付标识 是
09 sign 签名 固定长32 参见《签名与验签》 是

支付结果查询

1：请求地址

http://47.101.3.15/gateway/order/query

2：商户请求数据

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长32 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 payKey 支付key 固定长32 商户支付标识 是
03 sign 签名 固定长32 参见《签名与验签》 是

3:响应数据

序号 字段 名称 长度 说明 是否必填
01 orderNo 商户唯一订单号 变长32 订单号码支持数字、英文字母、-、_、*、+、#，其他字符将不支持 是
02 orderPrice 订单金额 变长13 是人民币，且以元为单位，例如：1.00（1元），0.01（1分） 是
02 factPrice 实际付款金额 变长13 是人民币，且以元为单位。 是
03 orderTime 商户订单日期 定长14 商户生成订单的日期，格式yyyyMMddHHmmss 是
04 trxNo 平台交易流水号 固定长20 是
05 statusCode 状态码 固定长2 00（查询操作成功）
其他值（失败）		 是
06 tradeStatus 交易状态 变长 20 详见《交易状态说明》 是
08 payKey 支付key 固定长32 商户支付标识 是
09 sign 签名 固定长32 参见《签名与验签》 是

4：订单查询成功样例


{
  "orderNo": "1508055453731",
  "orderTime": "20171015162249",
  "trxNo": "77772017101510000722",
  "tradeStatus": "wait",
  "sign": "8E3DC89AB06B0E6361D7D2CDF164456C",
  "payKey": "9ae9ef6d094d4de69bb5dc19abf48ec9",
  "orderPrice": "0.01",
  "factPrice": "0.01",
  "statusCode": "00"
}

5：订单查询失败样例

{
  "payKey": "9ae9ef6d094d4de69bb5dc19abf48ec9",
  "statusCode": "01",
  "msg": "商户不存在"
}

支付状态说明

序号 枚举名称 说明 备注
01 wait 交易创建，等待买家付款
02 success 交易成功，不能再次进行交易
03 cancel 交易撤销
04 fail 交易失败 失败可能风控引起

代付接口

1：请求地址

http://47.101.3.15/gateway/payfor

2：商户请求数据

序号 字段 名称 长度 说明 是否必填
01 merchantKey 商户key 变长32 商户key,可找商务获取 是
02 realname 持卡人姓名 变长60 持卡人真实姓名 是
03 cardNo 卡号 变长30 代付卡卡号 是
04 bankCode 银行编码 变长10 银行编码，文档最后附有 是
05 accType 开户账号类型 固定长2 01 -- 对公帐户
02 --对私借记卡		 是
06 province 开户行所在省份 变长14 开户行所在省份 是
07 city 开户行所在城市 变长30 开户行所在城市 是
08 bankAccountAddress 开户行全称 变长32 开户行全称 是
09 amount 代付金额 变长12 订单金额，以元为单位(保留2位小数 100.00) 是
10 moblieNo 银行预留手机号码 变长15 银行预留手机号码 是
11 merchantOrderId 商户订单号 变长32 商户订单号 是
12 sign 签名 固定长32 使用商户key对报文签名后的值 是

3：响应数据

序号 字段 名称 长度 说明 是否必填
01 resultCode 返回码 固定长2 00 -- 受理成功
01 -- 其它		 是
02 resultMsg 商户订单号 变长256 返回码信息提示 否
03 merchantOrderId 卡号 变长32 商户系统的订单号 resultCode为00时必填
其余可不填
04 settAmount 代付金额 变长10 代付金额 ，以元为单位 resultCode为00时必填
其余可不填
08 sign 签名 固定长32 使用商户key对报文签名后的值 是

4：成功返回样例

{
  "settAmount":"15,
  "resultCode":"00",
  "sign":"2509743B7C6A12011A7BAD16F7A78F8F",
  "merchantOrderId":"1522654509571",
  "resultMsg":"代付订单已生成"
}

5：失败样例

{
  "resultCode":"01",
  "resultMsg":"accType类型错误"
}

代付结果查询

1:代付查询地址

http://47.101.3.15/gateway/payfor/query

2：商户请求数据

序号 字段 名称 长度 说明 是否必填
01 merchantKey 商户key 变长32 商户key,可找商务获取 是
02 timestamp 时间戳 固定长10 unix时间戳 是
03 merchantOrderId 商户订单号 变长32 商户订单号 是
04 sign 签名 固定长32 使用商户key对报文签名后的值 是

3：响应数据，JSON格式

序号 字段 名称 长度 说明 是否必填
02 resultMsg 商户订单号 变长256 返回码信息提示 是
03 merchantOrderId 卡号 变长32 商户系统的订单号 是
04 settAmount 代付金额 变长32 代付金额 ，以元为单位 settStatus为 00 时，必须
06 settFee 手续费 变长10 代付手续费 settStatus为 00 时，必须
07 settStatus 代付结果 变长30 00 -- 打款成功
01-- 打款失败
02 -- 打款中
03 -- 查询失败		 是
08 sign 签名 变长30 使用商户key对报文签名后的值 是

4：成功样例

{
  "resultMsg":"打款成功",
  "merchantOrderId":"123456",
  "settAmount":"10000.00",
  "settFee":"2.00",
  "settStatus":"00",
  "sign":"70387FEBC8487EFFBE93511299BB30A7"
}

5：失败样例

{
  "resultMsg":"查询失败",
  "settStatus":"03",
  "merchantOrderId":"123456",
  "sign":"70387FEBC8487EFFBE93511299BB30A7"
}

账户余额查询

请求地址

http://47.101.3.15/gateway/balance

商户请求数据

序号 字段 名称 长度 说明 是否必填
01 merchantKey 商户key 变长32 商户key,可找商务获取 是
02 timestamp 时间戳 固定长10 unix时间戳 是
04 sign 签名 固定长32 使用商户key对报文签名后的值 是

响应数据

序号 字段 名称 长度 说明 是否必填
01 resultCode 返回码 固定长2 00 -- 成功
其它 -- 失败		 是
02 balance 账户余额 变长12 账户总余额 是
03 availableAmount 可用余额 变长12 账户可结算余额 resultCode为00时必填
其余可不填
05 freezeAmount 冻结金额 变长12 账户可结算余额 resultCode为00时必填
其余可不填
06 waitAmount 待结算金额 变长12 账户可结算余额 resultCode为00时必填
其余可不填
07 loanAmount 押款金额 变长12 账户可结算余额 resultCode为00时必填
其余可不填
08 payforAmount 在出款金额 变长12 账户可结算余额 resultCode为00时必填
其余可不填
09 resultMsg 返回码描述信息 变长256 返回码信息提示 resultCode为00时必填
其余可不填
10 sign 签名 变长30 使用商户key对报文签名后的值 resultCode为00时必填
其余可不填

成功样例

{
  "resultCode":"00",
  "balance":"25000.00",
  "availableAmount":"5000.00",
  "freezeAmount":"5000.00",
  "waitAmount":"5000.00",
  "loanAmount":"5000.00",
  "payforAmount":"5000.00",
  "resultMsg":"查询成功",
  "sign":"70387FEBC8487EFFBE93511299BB30A7"
}

失败样例

{
  "resultCode":"-1",
  "resultMsg":"查询失败"
}

签名与验签

1：签名算法

在请求参数列表中，除去sign参数外，其它必填的字段均参加签名。

参与签名的键值对，根据key值按照acsii码从小到大进行排序，每个键值对之间用"&"进行连接。

在拼接完得到的字符串尾部，再将支付密钥(paySecret)拼接上。

最后将得到的待签名字符串进行MD5加密，将字母全部转为大写。

2：格式样例，需要签名的字符串

waitSign: a=xxxxxxx&b=xxxxxxx&c=xxxxx&d=xxxxxx&e=xxxxx&f=xxxxxx&paySecret=xxxx

3：得到的签名字符串

sign=70387FEBC8487EFFBE93511299BB30A7

银行编码

支付银行 描述
ICBC 中国工商银行
ABC 中国农业银行
CCB 中国建设银行
BOC 中国银行
COMM 交通银行
PSBC 中国邮政储蓄银行
CMB 招商银行
CMBC 民生银行
SPDB 上海浦东发展银行
CITIC 中信银行
HXB 华夏银行
CIB 兴业银行
PINGANBANK 平安银行
CZB 浙商银行
HFB 恒丰银行
GDB 广发银行
CEB 光大银行
CBHB 渤海银行
CSCB 长沙银行

常见问题解答

1：支付key和商户密钥怎么获取

答：这两个字段在开户成功后，相关运营人员会将两者发送给商户。请求商户妥善保管。

2：请求协议是支持get还是post

答：同时支持get和post。