批量代付普通(平台内)受理接口

1.修订记录

版本号 日期 说明 作者
V0.1 2017/7/11 新接口参数定义 陈宋东
V0.2 2017/8/28 新增参数shopdate 黄月巧
V0.3 2017/9/18 公共参数新加proxy_ password和merchant_usercode参数 黄月巧
V0.4 2017/10/20 新增异常类型ACQ.BUSINESS_TIMEOUT_ERROR（业务超时） 陈宋东
V0.5 2020/11/30 修改关于ACQ.SYSTEM_ERROR的中文描述 汤吉齐
V0.6 2021/12/27 支持国密 王晶

2.接口说明

（1）场景说明

1、批量代付时需查询明细

（2）接口说明

1、 批量代付普通(平台内)受理接口

3.请求地址

环境 HTTPS请求地址
正式环境 https://batchdf.ysepay.com/gateway.do

4.请求参数说明

4.1公共请求参数

参数 类型(字节长度） 必填 参数说明
method String(1,128) Y 接口名称。固定值：ysepay.df.batch.normal.inner.accept
partner_id String(1,20) Y 在银盛支付开设的服务商商户号，请联系客户经理提供
proxy_ password String(50) Y 代理密码，加密传输
merchant_usercode String(20) Y 真实商户用户号，示例值：pinganyinhang02
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路径。示例值：http://api.test.ysepay.net/atinterface/receive_return.htm
version String(1,3) Y 接口版本，示例值：3.0
biz_content String Y 业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递

4.2 业务请求参数

参数名biz_content,值为一个json格式对象，下面列表描述json对象的值

参数 类型(字节长度） 必填 参数说明
out_batch_no String(16,16) Y 商户批次号,格式：F+15位唯一流水，建议格式：F+YYYYMMDD+XXXXXXX只能由大小写英文字母、数字、下划线及横杠组成，示例值：F201703081234567
shopdate String(8,8) Y 商户日期(该参数做交易与查询时需要一致) 该日期需在当日的前后一天时间范围之内，示例值：20170308
total_num String(1,4) Y 总笔数,最大交易笔数不能超过2000笔
total_amount Number(12，2) Y 代付的总金额。单位为：RMB YUAN。取值范围为[0.01，9999999999.99]，精确到小数点后两位。
business_code String(1,10) Y 业务代码 ，请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码
currency String(3,3) Y 暂时只支持币种：CNY（人民币）
sub_merchant SubMerchantInfo N 二级商户信息，如果有值则都不能为空，如果没值则都不能有值,二级商户信息, Json格式，暂包括merName、merShortName、merAddr、telephone、merNo、category，示例值：7.1
detail_data list Y 代付详细数据，最多支持2000笔。Json数组格式，暂包括out_trade_no、amount、subject、bank_telephone_no，示例值：7.2

4.3 二级商户 SubMerchantInfo

参数 类型(字节长度） 必填 参数说明
merName String(50) N 二级商户名称,支持25个中文
merShortName String(50) N 二级商户简称,支持25个中文
merAddr String(200) N 二级商户地址,支持100个中文
telephone String(13) N 固定电话/手机号码二选一
merNo String(32) N 二级商户编号
category String(20) N 类目，按附件内容输入类目编号
mrchntCertId String（15\ 18） N 身份证号,只支持身份证格式(如果签名方式为RSA，则用DES加密，密钥为商户号前8位，不足8位在商户号前补空格；如果签名方式为SM，则用SM加密)

4.4 代付列表 detail_data

参数 类型(字节长度） 必填 参数说明
out_trade_no String(1,32) Y 订单号,批次内唯一,只能由大小写英文字母、数字、下划线及横杠组成
amount Number(10，2) Y 单笔代付的金额。单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。
subject String(1,500) Y 订单说明
payee_user_code String(1,20) Y 收款方银盛用户号
payee_cust_name String(1,50) Y 收款方银盛客户名
telephone_no String(0,11) N 客户手机号

5.同步返回参数说明

银盛支付对商户的请求数据处理完成后，会将处理的结果数据同步回执给商户。

请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

5.1 公共响应参数

参数 类型(字节长度） 必填 参数说明
sign String Y 签名字符串，Base64编码
ysepay_df_batch_normal_inner_accept_respose String Y 业务响应参数的集合，最大长度不限

5.2 业务响应参数

参数 类型(字节长度） 必填 参数说明
code String Y 响应代码
msg String Y 响应代码描述
out_batch_no String(16,16) Y 商户批次号,格式：F+15位唯一流水，建议格式：F+YYYYMMDD+XXXXXXX，示例值：F201703081234567
batch_no String(1，30) Y 批次流水号
trade_status String（1，32） Y 交易目前所处的状态。状态的值：BATCH_TRADE_SUCCESS、BATCH_TRADE_FAILURE，示例值：8.2
trade_status_description String（256) N 状态描述，当trade_status为TRADE_FAILURE时，该字段是代付失败原因描述。该参数最长为128个汉字。示例值：代付银行号与姓名不一致
total_amount Number(10，2) Y 总金额
total_num String(1,4) Y 总笔数

6.服务器异步返回参数

银盛支付对商户的请求数据处理完成后，会将处理的结果数据同步回执给商户。

请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

参数 类型(字节长度） 必填 参数说明
out_batch_no String(16,16) Y 商户批次号,格式：F+15位唯一流水，建议格式：F+YYYYMMDD+XXXXXXX，示例值：F201703081234567
batch_no String(1，30) Y 批次流水号
trade_status String（1，32） Y 交易目前所处的状态。状态的值：BATCH_TRADE_SUCCESS/BATCH_TRADE_FAILURE，示例值：8.2
trade_status_description String（256) N 状态描述，当trade_status为TRADE_FAILURE时，该字段是代付失败原因描述。该参数最长为128个汉字。示例值：代付银行号与姓名不一致
total_amount Number(10，2) Y 总金额
total_num String(1,4) Y 总笔数
success_total_amount Number(10，2) Y 成功总金额
success_total_num String(1,6) Y 成功总笔数
fee Number(10，2) N 参考手续费,单位为：RMB Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。
batch_account_date String(1，10) N 批次会计日期：日账单格式为yyyyMMdd，示例值：20160413
notify_type String Y 通知类型，示例值：ysepay.df.batch.notify
notify_time String(19) Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"，示例值：2014-07-24 03:07:50
sign_type String Y 签名类型，交易请求时传入的签名类型RSA/SM
sign String Y 签名字符串，Base64编码

7.样例

7.1 二级商户 sub_merchant

{
    "merName": "二级商户名称",
    "merShortName": "二级商户简称",
    "merAddr": "二级商户地址",
    "telephone": "二级商户服务电话",
    "merNo": "二级商户编号",
    "category": "类目"
}

7.2 代付详细 detail_data

[{
    "out_trade_no": "201703080768835",
    "amount": "1.5",
    "subject": "订单说明",
    "bank_name": "中国银行深圳民治支行",
    "bank_province": "广东省",
    "bank_city": "深圳市",
    "bank_account_no": "1111111111111111",
    "bank_account_name": "姓名",
    "bank_account_type": "personal",
    "bank_card_type": "credit"
}, ..]

8.附录

8.1 业务错误码

错误码 错误描述 解决方案
ACQ.SYSTEM_ERROR 系统错误 支付中该状态为未知状态，请勿当成失败状态处理，请等待支付通知或继续查询
ACQ.BUSINESS_TIMEOUT_ERROR 业务超时 请调用查询接口查询订单状态
ACQ.INVALID_PARAMETER 参数无效 检查请求参数，修改后重新发起请求
PARAM_ERROR 参数错误 检查请求参数，修改后重新发起请求
REPEAT_ORDER 订单重复 该笔订单已受理,请使用新订单号发起请求
RISK_ERROR 风控检查异常 请检查风控是否有异常，然后再重新发起
ROUTE_ERROR 路由失败 请联系客服或市场技术支持人员
ACCOUNT_ERROR 账户扣款失败 请联系客服或市场技术支持人员
FEE_ERROR 计费失败 请联系客服或市场技术支持人员
DEAL_ERROR 处理失败 请重新发起代付受理请求
ACQ.SHOPDATE_VALID_FAILD 商户日期获取失败 检查参数
ACQ.PROXY_CHECK_FAILD 代理关系检查失败 比如委托关系不存在
ACQ.PROXY_CHECK_PARAM 代理关系参数验证失败 比如代理密码解密失败，或者代理密码与委托商户号没有同时传或者同时不传

8.2 批次交易状态

枚举名称 枚举说明
BATCH_ACCEPT_SUCCESS 批次受理成功
BATCH_TRADE_SUCCESS 批次交易处理完成
BATCH_TRADE_FAILURE 批次交易处理失败
TRADE_SUCCESS 明细交易成功
TRADE_FAILURE 明细交易失败

results matching ""

    No results matching ""