WEB页面接入
1.修订记录
| 修订 |
日期 |
说明 |
作者 |
| V0.1 |
2016/3/23 |
新接口参数定义 |
易显群 |
| V0.2 |
2016/4/21 |
修改接口业务参数格式，去掉Json形式，改为form表单提交 |
易显群 |
| V0.3 |
2016/4/25 |
修改请求方法名称 |
易显群 |
| V0.4 |
2016/5/18 |
确认交易状态 |
易显群 |
| V0.5 |
2016/5/27 |
扩大remark字段长度 |
易显群 |
| V0.6 |
2016/6/21 |
增加out_trade_no字段描述 |
莫尚校 |
| V0.7 |
2016/10/17 |
新增二级商户信息 |
郭勇 |
| V0.8 |
2016/11/09 |
新增币种字段 |
莫尚校 |
| V0.9 |
2017/1/13 |
extend_params字段增加民生网银B2B描述 |
郭勇 |
| V1.0 |
2017/3/2 |
新增收货人信息字段（consignee_info）、修改二级商户（添加身份证号） |
邓鑫 |
| V1.1 |
2017/3/17 |
增加跨境付款人信息字段（cross_border_info） |
莫尚校 |
| V1.2 |
2017/4/12 |
extend_params字段增加浦发网银B2B描述 |
莫尚校 |
| V1.3 |
2017/09/16 |
支持多URL异步通知 |
莫尚校 |
| V1.3 |
2017/11/02 |
支持担保交易 |
莫尚校 |
| V1.4 |
2018/03/19 |
交易超时时间调整 |
邓文泉 |
| V1.5 |
2018/04/13 |
修改extend_params字段描述 |
邓文泉 |
| V1.6 |
2018/05/09 |
请求参数新增appid参数、异步响应新增openid参数 |
刘敏 |
| V1.7 |
2018/05/22 |
补充异步通知 |
黄国强 |
| V1.8 |
2018/05/25 |
补充shopdate参数 |
黄国强 |
| V1.9 |
2018/12/03 |
新增订单所属地 |
邓鑫 |
| V2.0 |
2018/12/19 |
交易超时时间说明 |
邓文泉 |
| V2.1 |
2018/12/26 |
异步通知新增返回发往渠道流水、支付网关编号和渠道返回流水 |
邓文泉 |
| V2.2 |
2021/02/03 |
同步返回、异步返回增加公共扩展参数extra_common_param ,版本号3.4 |
汤吉齐 |
| V2.3 |
2022/02/17 |
seller_name修改为非必填 |
王晶 |
| V2.4 |
2022/09/16 |
异步通知新增付款方信息 |
康少雄 |
2.接口说明
（1）场景说明
（2）接口说明
3.请求地址
4.请求参数说明
请求参数是商户在与银盛支付进行数据交互时，提供给银盛支付的请求数据，以便银盛支付根据这些数据进一步处理。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| method |
String(128) |
Y |
接口名称 固定值：ysepay.online.directpay.createbyuser |
| partner_id |
String(20) |
Y |
在银盛支付开设的服务商商户号，请联系客户经理提供 |
| timestamp |
String(19) |
Y |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值：2014-07-24 03:07:50 |
| charset |
String(10) |
Y |
商户网站使用的编码格式，如UTF-8、GBK、GB2312等，默认值 GBK |
| sign_type |
String(10) |
Y |
报文签名算法，默认RSA |
| sign |
String(256) |
Y |
RSA签名字符串，再用Base64编码 |
| notify_url |
String(500) |
Y |
交易成功异步通知到商户的后台地址，多个url用分隔符“,”分开，格式如：url1,url2,url3，支持TLS1.0、TLS1.1、TLS1.2 |
| return_url |
String(200) |
N |
银盛支付处理完请求后，当前页面自动跳转到商户网站里指定页面的http路径。 |
| version |
String(3) |
Y |
接口版本3.0 /3.4,当前版本3.4 |
| tran_type |
String(1) |
N |
交易类型，说明：1或者空：非担保交易，2：担保交易，无特殊需求 不用填此字段 |
| out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号，须保证在商户端不重复，生成规则前8位必须为交易日期，如20220525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成，示例值：202205256843192280647118 |
| shopdate |
String(8,8) |
Y |
商户日期(该参数做交易与查询时需要一致) 该日期需在当日的前后一天时间范围之内 示例值：20180525 |
| subject |
String(1,250) |
Y |
订单备注 |
| total_amount |
Number(10,2) |
Y |
该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 |
| currency |
String(3,3) |
N |
默认CNY（人民币） |
| seller_id |
String(1,20) |
Y |
收款商户号（由银盛支付生成并下发） |
| seller_name |
String(1,50) |
N |
收款方银盛支付客户名 |
| timeout_express |
String(2,6) |
Y |
设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭，取值范围：1m～15d。m-分钟，h-小时，d-天。该参数数值不接受小数点，如1.5h，可转换为90m。注意：设置了未付款交易超时时间的情况下，若我司在限定时间内没有收到成功支付通知，则会关闭交易，关闭后该笔交易若付款方支付成功的情况下，会自动原路退款至付款方。示例值 96h 代表96小时后订单自动关闭 |
| pay_mode |
String(12) |
Y |
直连银行信息,直联模式使用,锁定指定的支付方式，目前支持internetbank |
| bank_type |
Number(7,9) |
Y |
直连银行信息,和paymode配合使用,若填写了则直接锁定该银行支付，如果paymodeY，此参数必填 |
| bank_account_type |
String(3,9) |
N |
直连银行信息,和paymode配合使用，付款方银行账户类型，bank_type非空时，此处必填corporate :对公账户;personal:对私账户 |
| support_card_type |
String(3,6) |
Y |
直连银行信息,和paymode配合使用，支持卡类型, bank_type非空时，此处必填debit:借记卡;credit:信用卡 |
| extend_params |
ExtendParams |
N |
业务扩展参数，一个json字符串 注：当用户选择民生网银B2B、浦发网银B2B进行支付时，必须上传对应的客户号ID，以保证交易成功。order_mode订单模式，暂时可选的值为:00 代表购物车模式;seller_list参与分账的收款方信息数组，每个元素包含seller_id收款方银盛支付用户号。实时分账业务，order_mode和seller_list均不能为空，order_mode的值必须为00。json字符串中Key所对应的值请参考样例中的描述。 示例值：样例7.1 |
| business_code |
String(1,10) |
Y |
业务代码 ，请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码 |
| extra_common_param |
String(2000) |
N |
公用回传参数 商户自定义数据域，原样返回 |
| sub_merchant |
SubMerchantInfo |
N |
二级商户信息, Json格式，暂包括merName、merShortName、merAddr、telephone、merNo、category、mrchntCertId 如果有值则二级商户信息都不能为空，如果没值则都不能有值 示例值：样例7.2 |
| consignee_info |
ConsigeeInfo |
N |
收货人信息json格式 示例值：样例7.3 |
| 保留参数(暂时不处理，后续功能再加） |
|
|
|
| buyer_id |
String(0,20) |
N |
付款人商户号（由银盛支付生成并下发） |
| buyer_name |
String(0,100) |
N |
付款人银盛支付客户名 |
| seller_phone |
Number |
N |
收款方电话号码 |
| seller_amount |
Number |
N |
收款方入账金额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| fee |
FeeInfo |
N |
描述手续费信息，json格式 |
| royalty_info |
RoyaltyInfo |
N |
描述分账信息，json格式 |
| appid |
String（32） |
N |
微信分配的子商户公众号账号ID 示例值：wx8888888888888888 |
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 |
身份证号,只支持身份证格式(用DES加密，密钥为商户号前8位，不足8位在商户号前补空格) |
4.4 收货人信息 ConsigeeInfo
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| consigneeName |
String(150) |
N |
收货人姓名 |
| consigneeAddr |
String(200) |
N |
收货地址 |
| transportationInfo |
String(200) |
N |
物流配送信息（物流名称+订单号） |
| commodityName |
String(150) |
N |
商品名称 |
| commodityNumber |
String(10) |
N |
商品数量, |
4.5 手续费信息 fee
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| flag |
String(1) |
Y |
平台外计算手续费 |
| seller_fee |
Number |
Y |
收款方手续费,单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| src_fee |
Number |
Y |
发起方手续,单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
4.6 分账信息 royalty_info
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| royalty_type |
String(100) |
N |
分账类型 卖家的分账类型，目前只支持传入ROYALTY（普通分账类型）。 |
| royalty_detail_infos |
RoyaltyDetailInfos [] |
Y |
分账明细的信息，可以描述多条分账指令，json数组。 |
| trans_in_type |
String |
Y |
接受分账金额的账户类型： l userId：银盛账号对应的唯一用户号。 默认值为userId。 |
| trans_in_id |
String(20) |
Y |
收款方银盛支付用户号 |
| trans_in_name |
String(100) |
Y |
收款方银盛支付客户名 |
| amount |
Number |
Y |
分账的金额，单位为元 |
| desc |
String(1000) |
N |
分账描述 |
5.页面跳转同步参数
银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过系统程序控制客户端页面自动跳转的方式通知给商户网站。这些处理结果数据就是页面跳转同步通知参数。
请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| sign |
String |
Y |
签名字符串，Base64编码 |
| ysepay_online_directpay_createbyuser_response |
String |
Y |
业务响应参数的集合，最大长度不限 |
5.2 业务响应参数
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| code |
String |
Y |
响应代码 |
| msg |
String |
Y |
响应代码描述 |
| sign_type |
String |
Y |
签名类型，默认RSA |
| sign |
String |
Y |
RSA签名字符串，Base64编码 |
| notify_type |
String |
N |
通知类型 固定值：directpay.status.sync |
| notify_time |
String(19) |
Y |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值： 2014-07-24 03:07:50 |
| out_trade_no |
String(32) |
Y |
商户系统生成的订单号 |
| trade_no |
String(30) |
N |
该交易在银盛支付系统中的交易流水号。 |
| trade_status |
String |
Y |
交易目前所处的状态。成功状态的值： TRADE_SUCCESS 示例值：附录8.2 |
| total_amount |
Number |
N |
该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| account_date |
String（19） |
N |
入账日期，格式"yyyyMMdd" 示例值：20140724 |
| extra_common_param |
String |
N |
公共扩展参数，版本3.4及以上支持 |
6.异步通知参数说明
银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。
请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| sign_type |
String |
Y |
签名类型，默认RSA |
| sign |
String |
Y |
签名字符串，Base64编码 |
| notify_type |
String |
Y |
通知类型 示例值：directpay.status.sync |
| notify_time |
String(19) |
Y |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
| out_trade_no |
String(32) |
Y |
商户系统生成的订单号 |
| total_amount |
Number |
N |
该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| trade_no |
String(30) |
N |
该交易在银盛支付系统中的交易流水号。 |
| trade_status |
String |
Y |
交易目前所处的状态。成功状态的值： TRADE_SUCCESS\ |
TRADE_CLOSED示例值：附录8.2 |
| account_date |
String（10） |
N |
入账的时间，格式"yyyyMMdd" 示例值：20140724 |
| openid |
String（128） |
N |
子商户appid下用户唯一标识 |
| payer_fee |
Number |
N |
该笔订单的付款方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| payee_fee |
Number |
N |
该笔订单的收款方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| partner_fee |
Number |
N |
该笔订单的合作方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| fee |
Number |
N |
该笔订单的手续费总和(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| channel_send_sn |
String |
N |
发往渠道流水号 |
| paygate_no |
String |
N |
支付网关编号 示例值：附录8.4 |
| channel_recv_sn |
String |
N |
渠道返回流水号 |
| extra_common_param |
String |
N |
公共扩展参数，版本3.4及以上支持 |
| card_type |
String |
N |
credit:信用卡debit:借记卡 |
| bank_type |
String |
N |
付款方开户行行别，版本6.1及以上支持 |
| payer_bank_account_no |
String |
N |
付款方账号/银行卡号，脱敏规则：保留前6后4，中间数据*； 版本3.2及以上支持 |
| payer_bank_account_name |
String |
N |
付款方账户户名，版本6.1及以上支持 |
7.样例
7.1 extend_params 说明
{
"paygate_CMBC_b2b_custId": "民生B2B客户号ID",
"paygate_SPDB_b2b_custId": "浦发B2B客户号ID",
"cartTYpe": "00",
"order_mode": "01",
"seller_list": [{
"seller_id": "123"
}, {
"seller_id": "456"
}]
}
7.2 sub_merchant 说明
{
"merName": "二级商户名称",
"merShortName": "二级商户简称",
"merAddr": "二级商户地址",
"telephone": "二级商户服务电话",
"merNo": "二级商户编号",
"category": "类目",
"mrchntCertId": "身份证号"
}
7.3 consignee_info 说明
{
"consigneeName": "收货人姓名",
"consigneeAddr": "收货地址",
"transportationInfo": "物流配送信息",
"commodityName": "商品名称",
"commodityNumber": "商品数量"
}
8.附录
8.1 业务错误码（仅供参考）
| 错误码 |
错误描述 |
解决方案 |
| ACQ.SYSTEM_ERROR |
接口返回错误 |
请立即调用查询订单API，查询当前订单的状态，并根据订单状态决定下一步的操作 |
| ACQ.INVALID_PARAMETER |
参数无效 |
检查请求参数，修改后重新发起请求 |
| ACQ.ACCESS_FORBIDDEN |
无权限使用接口 |
联系银盛市场人员进行签约 |
| ACQ.EXIST_FORBIDDEN_WORD |
订单信息中包含违禁词 |
修改订单信息后，重新发起请求 |
| ACQ.TOTAL_FEE_EXCEED |
订单总金额超过限额 |
修改订单金额再发起请求 |
| ACQ.CONTEXT_INCONSISTENT |
交易信息被篡改 |
更换商家订单号后，重新发起请求 |
| ACQ.TRADE_HAS_SUCCESS |
交易已被支付 |
确认该笔交易信息是否为当前买家的，如果是则认为交易付款成功，如果不是则更换商家订单号后，重新发起请求 |
| ACQ.TRADE_HAS_CLOSE |
交易已经关闭 |
更换商家订单号后，重新发起请求 |
| ACQ.BUYER_SELLER_EQUAL |
买卖家不能相同 |
更换买家重新付款 |
| ACQ.TRADE_BUYER_NOT_MATCH |
交易买家不匹配 |
更换商家订单号后，重新发起请求 |
| ACQ.BUYER_ENABLE_STATUS_FORBID |
买家状态非法 |
用户联系银盛客服，确认买家状态为什么非法 |
| ACQ.SELLER_BEEN_BLOCKED |
商家账号被冻结 |
联系银盛客服，解冻账号 |
| ACQ.ERROR_BUYER_CERTIFY_LEVEL_LIMIT |
买家未通过人行认证 |
让用户联系银盛客服并更换其它付款方式 |
8.2交易状态
| 枚举名称 |
枚举说明 |
| WAIT_BUYER_PAY |
交易创建，等待买家付款。 |
| TRADE_CLOSED |
在指定时间段内未支付时关闭的交易；客户主动关闭订单。 |
| TRADE_SUCCESS |
交易成功，且可对该交易做操作，如：多级分润、退款等。 |
| TRADE_PART_REFUND |
部分退款成功。 |
| TRADE_ALL_REFUND |
全部退款成功。 |
| WAIT_SELLER_SEND_GOODS |
买家已付款，等待卖家发货 |
| WAIT_BUYER_CONFIRM_GOODS |
卖家已发货，等待买家确认 |
8.3类目
类目字典：下载地址
8.4 支付网关编号
| 支付渠道代码 |
支付渠道 |
| 900000001 |
银联-支付宝 |
| 9000010 |
银联-微信 |
| 10810001 |
银联扫码-银联云闪付 |
| 10010001 |
网联-微信 |
| 10000012 |
网联-支付宝 |