单笔代收(代收协议)加急受理
1.修订记录
| 修订 | 日期 | 说明 | 作者 |
|---|---|---|---|
| V0.1 | 2020/5/14 | 新接口参数定义 | 宁华雄 |
| V0.2 | 2020/11/11 | 修改ACQ_QUERY_NO_RECORD的说明 | 汤吉齐 |
| V0.3 | 2021/12/27 | 支持国密 | 王晶 |
2.接口说明
（1）场景说明
1、单笔代收协议签约后，进行代收受理
（2）接口说明
1、单笔代收加急受理(代收协议)接口
3.请求地址
| 环境 | HTTPS请求地址 |
|---|---|
| 正式环境 | https://ds.ysepay.com/gateway.do |
4.请求参数说明
4.1公共请求参数
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| method | String(1,128) | Y | 接口名称 固定值 ysepay.ds.single.dsprotocol.accept |
| 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编码 |
| notify_url | String(190) | Y | 银盛支付服务器主动通知商户网站里指定的页面http路径。 |
| version | String(1,3) | Y | 接口版本3.0 当前版本：3.0 |
| biz_content | String | Y | 业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 业务请求参数
参数名biz_content,值为一个json格式对象，下面列表描述json对象的值
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| out_trade_no | String(1,32) | Y | 商户系统生成的订单号，生成规则前8位必须为交易日期，如20161012，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成 示例值：2017083020120 |
| protocol_no | String(1,32) | Y | 商户签约时银盛返回的签约订单号 示例值：2017083020120 |
| shopdate | String(8,8) | Y | 商户系统的交易发生日期格式yyyyMMdd 示例值：20180525 |
| merchant_usercode | String(0,20) | N | 商户主体(收款方)用户号，空时默认为合作方商户的用户号 |
| total_amount | Number(10,2) | Y | 总金额。单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 |
| subject | String(1,500) | Y | 订单备注 |
| currency | String(3) | Y | 默认CNY（人民币） |
5.同步返回参数说明
银盛支付对商户的请求数据处理完成后，会将处理的结果数据同步回执给商户。
请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| sign | String | Y | 签名字符串，Base64编码 |
| ysepay_ds_single_dsprotocol_accept_respose | String | Y | 业务响应参数的集合，最大长度不限 |
5.2 业务响应参数
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| code | String | Y | 响应代码 |
| msg | String | Y | 响应代码描述 |
| out_trade_no | String(1,32) | Y | 商户系统生成的订单号 |
| trade_status | String（1，32） | Y | 交易目前所处的状态。受理成功状态的值TRADE_SUCCESS｜TRADE_ACCEPT_SUCCESS｜TRADE_WAIT_AUTH 示例值：附录8.2 |
| trade_status_description | String（256) | N | 状态描述 |
| total_amount | Number(10，2) | Y | 总金额。单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。 |
| account_date | String(8) | Y | 会计日期：日账单格式为yyyyMMdd 示例值：20160413 |
| trade_no | String(30) | Y | 银盛支付交易流水号 |
| fee | Number(10,2) | N | 参考总手续费,单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。 |
| partner_fee | Number(10，2) | Y | 参考合作方手续费 |
| payee_fee | Number(10，2) | Y | 参考收款方手续费 |
| payer_fee | Number(10，2) | Y | 参考付款方手续费 |
6.异步通知参数说明
银盛支付对商户的请求数据处理完成后，会将处理的最终结果数据异步回执给商户。
请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
| 参数 | 类型(字节长度） | 必填 | 参数说明 |
|---|---|---|---|
| out_trade_no | String(1,32) | Y | 商户系统生成的订单号 |
| trade_status | String（1,32） | Y | 交易目前所处的状态。状态的值：TRADE_SUCCESS｜TRADE_FAILURE 示例值：附录8.2 |
| trade_status_description | String（256) | N | 状态描述，当trade_status为TRADE_FAILURE时，该字段是失败原因描述。该参数最长为128个汉字。 |
| total_amount | Number(10，2) | Y | 总金额。单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。 |
| account_date | String(1，10) | Y | 会计日期：日账单格式为yyyyMMdd 示例值：20160413 |
| trade_no | String(30) | N | 银盛支付交易流水号 |
| fee | Number(15) | N | 参考总手续费,单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。 |
| partner_fee | Number(10，2) | Y | 参考合作方手续费 |
| payee_fee | Number(10，2) | Y | 参考收款方手续费 |
| payer_fee | Number(10，2) | Y | 参考付款方手续费 |
| notify_type | String(1,32) | Y | 通知类型 固定值：ysepay.ds.single.notify |
| notify_time | String(1,19) | Y | 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值：2014-07-24 03:07:50 |
| sign_type | String(1,10) | Y | 报文签名算法，交易请求时的签名类型RSA/SM |
| sign | String(1,256) | Y | 签名字符串，Base64编码 |
7.样例
无
8.附录
8.1 业务错误码
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
| ACQ.SYSTEM_ERROR | 系统错误 | 请调用查询接口查询订单状态 |
| ACQ.BUSINESS_TIMEOUT_ERROR | 业务超时 | 请调用查询接口查询订单状态 |
| ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数，修改后重新发起请求 |
| PARAM_ERROR | 参数错误 | 检查请求参数，修改后重新发起请求 |
| REPEAT_ORDER | 订单重复 | 该笔订单已受理,请使用新订单号发起请求 |
| RISK_ERROR | 风控检查异常 | 请检查风控是否有异常，然后再重新发起 |
| ROUTE_ERROR | 路由失败 | 请联系客服或市场技术支持人员 |
| FEE_ERROR | 计费失败 | 请联系客服或市场技术支持人员 |
| DEAL_ERROR | 处理失败 | 请重新发起代收受理请求 |
| ACQ.QUERY_NO_RECORD | 暂未查询到记录 | 该状态为未知状态，请勿当成失败状态处理 检查传入的订单号是否正确，修改后重新发起请求或继续查询 |
| ACQ.ORDER_STATUS_ERROR | 订单状态不支持此操作 | 请核查该订单的状态是否为待授权 |
| ACQ.UNABLE_TO_OBTAIN_PROTOCOL_BOUND_TEL_NO | 无法获取协议绑定的手机号 | 请核查该订单所用的协议，是否绑定了电话号码 |
| ACQ.GET_AUTH_MSG_FAILURE | 获取授权码失败 | 请联系客服或市场技术支持人员 |
| SEND_SMS_ERROR | 发送短信异常 | 请联系客服或市场技术支持人员 |
| ACQ.AUTH_TEL_IS_NOT_AGREE | 授权验证手机号不一致 | 请核查该手机号与签约时的手机号是否一致 |
| ACQ.SHOPDATE_VALID_FAILD | 商户日期获取失败 | 检查参数 |
| VAILD_SMS_CODE_FAILURE | 校验短信授权码失败 | 请核查授权码是否超时，超时时间120秒，同一手机号每天限发20次 |
| VAILD_SMS_CODE_ERROR | 校验短信授权码异常 | 请联系客服或市场技术支持人员 |
| REPEAT_OBTAIN_AUTH_CODE_FAILURE | 重复获取授权码失败,每次获取授权码之后，需等待30秒后才能重新获取，还需等待：{0}秒 | 请稍候重试 |
| ACQ.PROXY_CHECK_FAILD | 代理关系检查失败 | 比如委托关系不存在 |
| ACQ.PROXY_CHECK_PARAM | 代理关系参数验证失败 | 比如代理密码解密失败，或者代理密码与委托商户号没有同时传或者同时不传 |
8.2 交易状态
| 枚举名称 | 枚举说明 |
|---|---|
| TRADE_ACCEPT_SUCCESS | 受理成功 |
| TRADE_SUCCESS | 交易成功 |
| TRADE_FAILURE | 交易失败 |
| TRADE_WAIT_AUTH | 交易待授权,当出现该状态时，是因为商户配置了”代收交易下发短信校验”，需要执行“单笔代收交易授权-V3.0版本.docx”的获取授权码和授权接口 |
| GET_AUTH_CODE | 已获取授权码 |
| TRADE_ALL_REFUND | 全部退款成功 |
| TRADE_PART_REFUND | 部分退款 |