申请代付
接口描述
商户通过代付接口发起代付申请，支付系统收到请求后同步返回申请结果，申请成功并不代表代付成功。
商户有两种方式确定代付结果：
1）发起代付时传递代付结果回调地址，支付系统处理代付确定结果后会向改地址发起通知请求。
2）商户系统客户主动发起代付查询，以查询到的最终结果确定代付是否成功。
注意：商户访问该接口需要申请IP白名单。
接口链接
URL地址：{payUrl}/agentpay/apply
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 1000000010 | 支付中心分配的商户号 |
| 商户代付单号 | mchOrderNo | 是 | String(30) | A201907011234 | 商户代付单号 |
| 代付金额 | amount | 是 | int | 1000 | 代付金额， 单位分 |
| 账户属性 | accountAttr | 否 | String(2) | 0 | 账户属性：0-对私,1-对公,默认对私 |
| 银行名称 | bankName | 是 | String(128) | 中国工商银行 | 收款卡的银行名称 |
| 收款人姓名 | accountName | 是 | String(64) | 张三 | 收款人姓名 |
| 收款人卡号 | accountNo | 是 | String(64) | 622848988712341234 | 收款人卡号 |
| 开户行所在省份 | province | 否 | String(32) | 北京市 | 开户行所在省份 |
| 开户行所在市 | city | 否 | String(32) | 北京市 | 开户行所在市 |
| 联行号 | bankNumber | 否 | String(64) | 联行号 | |
| 代付结果回调URL | notifyUrl | 否 | String(128) | 代付结果回调URL | |
| 备注 | remark | 否 | String(128) | 备注 | |
| 扩展域 | extra | 否 | String(128) | 扩展域 | |
| 请求时间 | reqTime | 是 | String(30) | 20190723141000 | 请求接口时间， yyyyMMddHHmmss格式 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 代付订单号 | agentpayOrderId | 是 | String(32) | T201990131313 | 代付订单号 |
| 状态 | status | 是 | String(2) | 2 | 状态:0-待处理,1-处理中,2-成功,3-失败,4-待人工处理 |
| 手续费 | fee | 是 | String(30) | 10 | 手续费，单位分 |
| 转账提示 | transMsg | 否 | String(128) | 转账提示 | |
| 扩展域 | extra | 否 | String(128) | 扩展域 | |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
2. 代付确认
接口描述
当商户通过接口发起代付请求后，如果商户开启代付二次确认，那么支付平台会向商户配置的代付确认地址发起请求，等待商户系统返回确认结果。
接口链接
该链接是商户在支付平台配置的二次确认地址。
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户订单号 | mchOrderNo | 是 | String(32) | M201990131313 | 商户订单号 |
| 金额 | amount | 是 | int | 10 | 代付发起金额，单位分 |
响应结果
商户业务系统处理后同步返回给支付平台，返回字符串 ok 则表示商户系统确认该代付订单正确存在，返回 fail 则表示确认不存在，返回其他或无响应则支付平台会每延迟10秒再发请求(最多3次)。
注意：返回的字符串必须是小写，且前后不能有空格，不能有换行。返回ok则继续执行代付，否则代付退回商户
3. 查询代付订单
接口描述
商户通过该接口查询代付订单结果，并根据状态结果进一步处理业务逻辑。
接口链接
URL地址：{payUrl}/agentpay/query_order
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 1000000010 | 支付中心分配的商户号 |
| 商户订单号 | mchOrderNo | 否 | String(32) | M1000000010 | 商户订单号， 与 代付订单号 二选一 |
| 代付订单号 | agentpayOrderId | 否 | String(32) | T1000000010 | 代付订单号， 与 商户订单号 二选一 |
| 请求时间 | reqTime | 是 | String(30) | 20190723141000 | 请求接口时间， yyyyMMddHHmmss格式 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 代付订单号 | agentpayOrderId | 是 | String(32) | T201990131313 | 代付订单号 |
| 商户订单号 | mchOrderNo | 是 | String(32) | M201990131313 | 商户订单号 |
| 代付金额 | amount | 是 | int | 1000 | 代付金额，单位分 |
| 手续费 | fee | 是 | int | 10 | 手续费，单位分 |
| 状态 | status | 是 | String(2) | 2 | 状态:0-待处理,1-处理中,2-成功,3-失败,4-待人工处理 |
| 转账提示 | transMsg | 否 | String(128) | 转账提示 | |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
4. 查询余额
接口描述
商户可通过该接口查询代付账户余额。
接口链接
URL地址：{payUrl}/agentpay/query_balance
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 1000000010 | 支付中心分配的商户号 |
| 请求时间 | reqTime | 是 | String(30) | 20190723141000 | 请求接口时间， yyyyMMddHHmmss格式 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 代付余额 | agentpayBalance | 是 | int | 10000 | 代付余额 |
| 可用代付余额 | availableAgentpayBalance | 是 | int | 10000 | 可用代付余额 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
5. 代付结果通知
接口描述
当代付处理完成后，支付系统会通过该接口向商户发起通知。
接口链接
该链接是商户通过代付申请接口提交的参数notifyUrl设置，如果无法访问链接，商户业务系统将无法接收到支付平台的通知。
通知参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 代付订单号 | agentpayOrderId | 是 | String(32) | T201990131313 | 代付订单号 |
| 商户订单号 | mchOrderNo | 是 | String(32) | M201990131313 | 商户订单号 |
| 状态 | status | 是 | String(2) | 2 | 状态:0-待处理,1-处理中,2-成功,3-失败,4-待人工处理 |
| 手续费 | fee | 是 | int | 10 | 手续费，单位分 |
| 转账提示 | transMsg | 否 | String(128) | 转账提示 | |
| 扩展域 | extra | 否 | String(128) | 扩展域 | |
| 通知请求时间 | reqTime | 是 | String(30) | 20190723141000 | 通知请求时间，yyyyMMddHHmmss格式 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为60/120/180/240/300,单位：秒）
注意：返回的字符串必须是小写，且前后不能有空格，不能有换行。
6. 错误码
| RetCode | 描述 |
|---|---|
| 0 | 成功 |
| 9999 | 业务异常，具体错误详见RetMsg字段 |
| 0100 | 商户签名异常 |
| 0010 | 系统错误 |
| 0011 | 请使用post方法 |
| 0012 | post数据为空 |
| 0013 | 签名错误 |
| 0014 | 参数错误 |
| 0015 | 商户不存在 |
| 0110 | 第三方超时 |
| 0111 | 第三方异常 |
| 0112 | 订单不存在 |
| 0113 | 订单已支付 |
| 0114 | 商品不存在 |
| 0115 | 价格不对 |
| 0116 | 物品数量不对 |
| 0117 | 过程返回255 |
| 0118 | DB错误 |
| 0119 | 支付中心没有对应的渠道 |
| 0120 | 修改订单状态失败 |