单笔代收协议查询接口
1.修订记录
| 修订 | 日期 | 说明 | 作者 |
|---|---|---|---|
| V0.1 | 2017/04/26 | 新接口参数定义 | 唐川楗 |
| V0.2 | 2017/08/18 | 修改返回参数bank_accout_no为bank_account_no | 唐川楗 |
| V0.3 | 2017/10/20 | 新增异常类型ACQ.BUSINESS_TIMEOUT_ERROR（业务超时） | 陈宋东 |
| V0.4 | 2020/11/11 | 修改ACQ_QUERY_NO_RECORD的说明 | 汤吉齐 |
| V0.5 | 2021/01/21 | 修改关于ACQ.QUERY_NO_RECORD的错误描述 | 王晶 |
| V0.6 | 2021/12/27 | 支持国密 | 王晶 |
2.接口说明
（1）场景说明
1、单笔代收交易授权
（2）接口说明
1、 单笔代收交易授权
3.请求地址
| 环境 | HTTPS请求地址 |
|---|---|
| 正式环境 | https://searchds.ysepay.com/gateway.do |
4.请求参数说明
4.1公共请求参数
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| method | String(1,128) | Y | 接口名称。固定值：ysepay.ds.protocol.single.query |
| partner_id | String(1,20) | Y | 商户在银盛支付平台开设的用户号[商户号] |
| timestamp | String(1,19) | Y | 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"，示例值：2014-07-24 03:07:50 |
| charset | String(1,10) | Y | 商户网站使用的编码格式，如utf-8、gbk、gb2312等。示例值：GBK |
| sign_type | String(1,10) | Y | 签名类型，RSA/SM |
| sign | String(1,256) | Y | 签名字符串，再用Base64编码 |
| version | String(1,3) | Y | 接口版本，示例值：3.0 |
| biz_content | String | Y | 业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 业务请求参数
参数名biz_content,值为一个json格式对象，下面列表描述json对象的值
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| protocol_no | String(1,32) | Y | 企业、客户代收协议号 |
5.同步返回参数
银盛支付对商户的请求数据处理完成后，会将处理的结果数据同步回执给商户。
请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| sign | String | Y | 签名字符串，Base64编码 |
| ysepay_ds_protocol_single_query_respose | String | Y | 业务响应参数的集合，最大长度不限 |
5.2 业务响应参数
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| code | String | Y | 响应代码 |
| msg | String | Y | 响应代码描述 |
| protocol_no | String(1,32) | Y | 企业、客户代收协议号。 |
| protocol_state | String（1,32） | Y | 协议目前所处的状态。状态的值：PROTOCOL_IS_PROCESSING,示例值:附录7.2 |
| protocol_state_description | String（256) | N | 状态描述 |
| business_code | String（1,10) | Y | 业务代码 ，请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码 |
| effect_date | String（8,8) | Y | 协议生效时间。格式: yyyyMMdd，示例值：20220619 |
| expire_date | String（8,8) | Y | 协议失效时间。格式: yyyyMMdd，示例值：20220619 |
| bank_account_type | String（3,9) | Y | 付款方银行账户类型，此处必填corporate :对公账户;personal:对私账户。 |
| bank_card_type | String(3,6) | Y | 卡类型，此处必填debit:借记卡;credit:信用卡。 |
| bank_name | String(1,128) | Y | 银行名称，为了保证代付交易成功，银行名称最好具体到分行。示例值：中国银行深圳民治支行 |
| bank_account_no | String(15,19) | Y | 银行账号。 |
| bank_account_name | String(1,100) | Y | 银行帐号用户名。 |
| bank_province | String(40) | N | 开户行所在省份。示例值：广东省 |
| bank_city | String(1,40) | Y | 开户行所在城市。示例值：深圳市 |
| bank_telephone_no | String（1,13） | Y | 银行预留手机号码。 |
| cert_type | Number(2) | Y | 开户行证件类型。示例值：身份证 |
| cert_no | String(50) | Y | 证件号码，当前只对特殊银行机构特定场景下使用此字段注：如果签名方式为RSA，则用DES加密，密钥Src用户号前8位，不足8位前补空格；如果签名方式为SM，则用SM加密。示例值 :身份证号码 |
| cert_expire | String(8) | N | 证件有效期。格式：yyyyMMdd，长期有效的居民身份证可为空。示例值：20220619 |
| single_amount_limit | Number(10,2) | N | 单笔限额。单位为：RMB Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 |
| month_num_limit | Number(10) | Y | 月交易笔数限制。 |
| month_amount_limit | Number(10,2) | Y | 月交易限额。单位为：RMB Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 |
| fee | Number(10,2) | N | 手续费。单位为：RMB Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 |
6.样例
无
7.附录
7.1 业务错误码
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
| ACQ.SYSTEM_ERROR | 系统错误 | 请联系银盛客服 |
| ACQ.BUSINESS_TIMEOUT_ERROR | 业务超时 | 请调用查询接口查询订单状态 |
| ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数，修改后重新发起请求 |
| ACQ.QUERY_NO_RECORD | 暂未查询到记录，请检查partner_id/protocol_no后重试 | 该状态为未知状态，请勿当成失败状态处理 检查传入的订单号是否正确，修改后重新发起请求或继续查询 |
| ACQ.PROXY_CHECK_FAILD | 代理关系检查失败 | 比如委托关系不存在 |
| ACQ.PROXY_CHECK_PARAM | 代理关系参数验证失败 | 比如代理密码解密失败，或者代理密码与委托商户号没有同时传或者同时不传 |
7.2 交易状态
| 枚举名称 | 枚举说明 |
|---|---|
| PROTOCOL_ACCEPT_SUCCESS | 已受理，待审核。 |
| PROTOCOL_EFFECT | 生效 |
| PROTOCOL_INVALID | 失效 |