WAP网站支付页面接入
1.修订记录
| 修订 |
日期 |
说明 |
作者 |
| V0.1 |
2016/6/23 |
新接口参数定义 |
郭勇 |
| V0.2 |
2016/9/21 |
同步地址改为非空 |
郭勇 |
| V0.3 |
2016/10/17 |
新增二级商户信息 |
郭勇 |
| V0.4 |
2017/3/2 |
新增收货人信息字段（consignee_info）、修改二级商户（身份证号） |
邓鑫 |
| V0.5 |
2017/08/02 |
新增支付方式 |
莫尚校 |
| V0.5 |
2017/08/08 |
新增QQ钱包支付 |
郭勇 |
| V0.6 |
2017/09/16 |
支持多URL异步通知 |
莫尚校 |
| V0.7 |
2017/11/01 |
新增交易状态说明，新增公用字段区分担保交易和即时到账 |
郭勇 |
| V0.8 |
2017/11/02 |
扩展参数（extend_params）新增H5支付json |
邓鑫 |
| V0.9 |
2017/11/10 |
新增快捷支付手机号 |
郭勇 |
| V1.0 |
2018/01/24 |
前台H5快捷支付优化 |
莫尚校 |
| V1.1 |
2018/03/19 |
交易超时时间调整 |
邓文泉 |
| V1.2 |
2018/04/13 |
修改extend_params字段描述 |
邓文泉 |
| V1.3 |
2018/05/09 |
请求参数新增appid参数、异步响应新增openid参数 |
刘敏 |
| V1.4 |
2018/05/22 |
补充异步通知 |
黄国强 |
| V1.5 |
2018/05/25 |
补充shopdate参数 |
黄国强 |
| V1.6 |
2018/12/03 |
新增订单所属地 |
邓鑫 |
| V1.7 |
2018/12/19 |
交易超时时间说明 |
邓文泉 |
| V1.8 |
2018/12/26 |
异步通知新增返回发往渠道流水、支付网关编号和渠道返回流水 |
邓文泉 |
| V1.9 |
2019/06/04 |
当pay_mode为fdfastpay:wap前台快捷支付时，取消银行卡必填的限制 |
刘进 |
| V2.0 |
2020/01/15 |
页面跳转同步返回extra_common_param参数补充。 |
宁华雄 |
| V2.1 |
2022/02/17 |
seller_name修改为非必填 |
王晶 |
2.接口说明
（1）场景说明
（2）接口说明
1、该接口支持wap进行支付，页面前端跳转方式
3.请求地址
4.请求参数说明
请求参数是商户在与银盛支付进行数据交互时，提供给银盛支付的请求数据，以便银盛支付根据这些数据进一步处理。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| method |
String(128) |
Y |
接口名称 固定值：ysepay.online.wap.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等。 |
| sign_type |
String(10) |
Y |
报文签名算法，默认值RSA |
| sign |
String(256) |
Y |
RSA签名字符串，再用Base64编码 |
| notify_url |
String(500) |
Y |
交易成功异步通知到商户的后台地址，http路径支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3，支持TLS1.0、TLS1.1、TLS1.2 |
| return_url |
String(200) |
Y |
银盛支付处理完请求后，当前页面自动跳转到商户网站里指定页面的http路径。若不想回调，则需传入我司指定地址https://wapcashier.ysepay.com 。备注：支付宝H5不支持页面自动跳转 |
| version |
String(3) |
Y |
接口版本3.0 当前版本3.0 |
| tran_type |
String(1) |
|
交易类型，说明：1或者空：非担保交易，2：担保交易 |
| out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号，须保证在商户端不重复，生成规则前8位必须为交易日期，如20220525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成，示例值：202205256843192280647118 |
| shopdate |
String(8,8) |
Y |
商户日期(该参数做交易与查询时需要一致) 该日期需在当日的前后一天时间范围之内 示例值：20180525 |
| subject |
String(1,250) |
Y |
订单备注。该参数最长为250个汉字。 |
| total_amount |
Number(10,2) |
Y |
该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 |
| 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) |
N |
直连银行信息,直联模式使用,锁定指定的支付方式，目前支持internetbank：网银；fastpay：快捷；native: 原生app支付；fdfastpay:wap前台快捷支付 |
| bank_type |
Number(7,9) |
N |
直连银行信息,和paymode配合使用,若填写了则直接锁定该银行支付，如果paymodeY，此参数必填。特别说明：当paymode为native时，只能填写1903000【支付宝H5】、1904000【QQ钱包】paymode为fdfastpay时，填写9001000【中国银联】 |
| bank_account_type |
String(3,9) |
N |
直连银行信息,和paymode配合使用，付款方银行账户类型，bank_type非空时，pay_mode为internetbank此处必填。corporate :对公账户;personal:对私账户，直连快捷默认为对私 |
| support_card_type |
String(3,6) |
N |
直连银行信息,和paymode配合使用，支持卡类型, bank_type非空时，pay_mode为internetbank此处必填。debit:借记卡;credit:信用卡 |
| mer_outside_custid |
String(50) |
N |
商户用户id |
| bank_account_no |
String(15-19) |
N |
卡号，当pay_mode为fastpay时必填 |
| fast_pay_name |
String(30) |
N |
姓名，当pay_mode为fastpay时必填 |
| fast_pay_id_no |
String(18) |
N |
证件号，当pay_mode为fastpay时必填 |
| fast_pay_validity |
String(4) |
N |
有效期，当pay_mode为fastpay时，且卡类型为信用卡时必填 |
| fast_pay_mobile |
String(11) |
N |
手机号,当pay_mode为fastpay时使用 |
| fast_pay_cvv2 |
String(3) |
N |
安全码,当pay_mode为fastpay时，且卡类型为信用卡时必填 |
| extend_params |
String(500) |
N |
业务扩展参数，一个json字符串,order_mode订单模式，暂时可选的值为:00 代表购物车模式;seller_list参与分账的收款方信息数组，每个元素包含seller_id收款方银盛支付用户号。实时分账业务，order_mode和seller_list均不能为空，order_mode的值必须为00。示例值：样例7.1 |
| business_code |
String(1,10) |
Y |
业务代码 ，请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码 |
| extra_common_param |
String(2000) |
N |
公用回传参数 商户自定义数据域，原样返回 |
| sub_merchant |
SubMerchantInfo |
|
二级商户信息, Json格式，暂包括merName、merShortName、merAddr、mobileNo、merNo、category 示例值：样例7.2 |
| consignee_info |
ConsigeeInfo |
N |
收货人信息json格式 示例值：样例7.3 |
4.3 业务扩展 extend_params
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| deviceInfo |
String(16) |
N |
应用类型 |
| machAppName |
String(256) |
N |
应用名 |
| mchAppId |
String(128) |
N |
应用标识 |
| order_mode |
String(2) |
N |
00 代表购物车模式 |
| seller_list |
List |
N |
参与分账的收款方信息数组 |
4.3.1 分账收款方 seller_list
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| seller_id |
String(16) |
Y |
收款商户号（银盛支付生成并下发），实时分账业务，order_mode和seller_list均不能为空，order_mode的值必须为00。 |
4.4 二级商户 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.5 收货人信息 ConsigeeInfo
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| consigneeName |
String(150) |
N |
收货人姓名 |
| consigneeAddr |
String(200) |
N |
收货地址 |
| transportationInfo |
String(200) |
N |
物流配送信息（物流名称+订单号） |
| commodityName |
String(150) |
N |
商品名称 |
| commodityNumber |
String(10) |
N |
商品数量, |
5.页面跳转同步参数
银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过系统程序控制客户端页面自动跳转的方式通知给商户网站。这些处理结果数据就是页面跳转同步通知参数。
请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| sign_type |
String |
Y |
签名类型，默认RSA |
| sign |
String |
Y |
签名字符串，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) |
V |
商户系统生成的订单号 |
| trade_no |
String(20) |
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(2000) |
N |
公用回传参数 商户自定义数据域，原样返回 |
6.异步通知参数
银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。
请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| sign_type |
String |
Y |
签名类型，默认RSA |
| sign |
String |
Y |
RSA签名字符串，Base64编码 |
| notify_type |
String |
Y |
通知类型 示例值：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 |
商户系统生成的订单号 |
| total_amount |
Number |
N |
该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| trade_no |
String(20) |
Y |
该交易在银盛支付系统中的交易流水号。 |
| 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]，精确到小数点后两位。示例值： 1.00 |
| payee_fee |
Number |
N |
该笔订单的收款方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值： 1.00 |
| partner_fee |
Number |
N |
该笔订单的合作方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值： 1.00 |
| fee |
Number |
N |
该笔订单的手续费总和(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值： 1.00 |
| channel_send_sn |
String |
N |
发往渠道流水号 |
| paygate_no |
String |
N |
支付网关编号 示例值：附录8.5 |
| channel_recv_sn |
String |
N |
渠道返回流水号 |
7.样例
7.1 extend_params
{
"deviceInfo": "应用类型",
"machAppName": "应用名",
"mchAppId": "应用标识",
"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 支付方式
一、 payMode为fastpay时，bank_account_no、fast_pay_name、fast_pay_id_no必传，bank_type,bank_account_type,support_card_type可空，传了就必须与卡号匹配，当时快捷信用卡直连时fast_pay_validity、fast_pay_ccv2必须要传，当为快捷借记卡直连时，fast_pay_validity、fast_pay_cvv2不可传
二、 payMode为internetbank时，bank_type、bank_account_type、support_card_type必传
三、payMode为native时，bank_type 只能为支付宝行别(1903000)
8.4 类目字典
类目字典：下载地址
8.5 支付网关编号
| 支付渠道代码 |
支付渠道 |
| 900000001 |
银联-支付宝 |
| 9000010 |
银联-微信 |
| 10810001 |
银联扫码-银联云闪付 |
| 10010001 |
网联-微信 |
| 10000012 |
网联-支付宝 |