快捷协议支付

1、修订记录

修订记录 日期 说明
1.0 2023.09.12 初版

2、业务说明

（1）接口说明

一、用户先进行签约，签约完成后进调用本接口进行支付

场景说明

二、用户签约成功后，通过该接口可以创建无卡快捷订单及明细登记 协议快捷支付流程：
1、协议签约接口签约；
2、协议签约后，会收到短信验证码，再调用协议签约确认接口进行确认；
3、协议签约确认完成后，调用创建无卡快捷订单及明细登记接口订单创建；
4、创建无卡快捷订单及明细登记后，会收到短信验证码，调用确认协议快捷支付短信接口进行确认支付；
5、如果没有收到协议快捷短信验证码，调用重新获取协议快捷支付短信接口再发送短信验证码进行确认支付；

请求主体类型：application/json

请求方式：POST

3、请求地址

环境 HTTPS请求地址
测试环境 https://appdev.ysepay.com/openapi/unify/basePay/quickProtocol/pay
正式环境 https://ysgate.ysepay.com/openapi/unify/basePay/quickProtocol/pay

4、请求参数说明

4.1、公共请求参数

参数 类型(长度） 必填 参数说明
timeStamp String Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"
method String(128) Y 接口名称，固定值：unify.basePay.quickProtocol.pay
charset String(10) Y 请求使用的编码格式，如utf-8,gbk,gb2312等,固定为utf-8
sign String Y 商户请求参数的签名串（签名算法默认为国密）,详见demo,注意:请用商户私钥进行签名
check String Y 银盛公钥加密随机生成的字符串（key）得到的加密值，详见demo
bizContent String Y 业务参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递。注意：需要通过AES以及随机生成的字符串（key）加密业务参数集合，得到bizContent
reqId String Y 请求唯一流水号,商户系统唯一，要求32个字符内（最少14个字符），只能是数字、大小写字母_-且在同一个商户号下唯一。最后12位要求格式为"yyMMddHHmmss" 示例值：xy1415220315145602
certId String Y 发起方商户号，服务商在银盛给自己开设的商户号，即可当作发起方商户号，由银盛生成并下发。 注意：不同于子商户号，服务商发展的商户即为子商户号
version String Y 调用的接口版本，固定为：1.0

4.2、业务请求参数

（bizContent加密前的json数据明文字符串）

参数 类型(长度） 必填 参数说明
orderId String(32) Y 商户系统生成的订单号,建议：生成规则前8位为交易日期，如20180525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成 示例值：201805256843192280647118
shopDate String(8) Y 商户日期,该日期需在当日的前后一天时间范围之内，格式：yyyyMMdd， 示例值：20180525
note String(250) Y 订单备注
totalAmount String(10) Y 该笔订单的资金总额,单位：分。必须为正整数
currency String(3) N 币种,默认：CNY
payeeMercId String(20) Y 收款商户号,银盛支付生成并下发
payeeMercName String(50) N 收款方银盛支付客户名,收款商户号对应客户名
timeoutExpress String(21600) Y 订单失效时间,设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭。单位：分钟。例如：30，则订单失效时间为30分钟。
extendParams String(250) N 业务扩展参数
extraCommonParam String(1000) N 公用回传参数,商户自定义数据域，原样返回
busiCode String(10) Y 业务代码,请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码
userId String(25) Y 唯一客户标识,商户旗下客户号。签约时的userId
protocolNo String(20) Y 银盛协议号,签约确认成功时返回的银盛协议号
cvvCode String(32) N CVV码,贷记卡必填
cardExprDt String(8) N 有效日期,贷记卡必填
srcIP String(16) Y 发起方IP,例：10.210.61.088
submerIP String(16) N 子商户IP,例：10.210.61.089
mccCode String(200) N MCC码,支持多个，多个时用 | 分割。例：5811|5812|5813
province String N 所属省,通过"地区信息查询"接口获取cityCd，详见地区信息查询，示例：2360。
city String N 所属市,通过"地区信息查询"接口获取cityCd，详见地区信息查询，示例：2360。
notifyUrl String(500) Y 异步通知地址
subMerchant Object N 二级商户信息
consignee Object N 收货人信息
installment Object N 分期请求信息
msgCode String Y 报文编号,固定传值：S3001

4.2.1 subMerchant具体参数

参数 类型(长度） 必填 参数说明
merName String(25) N 二级商户名称,支持25个中文
merShortName String(25) N 二级商户简称,支持25个中文
merAddr String(100) N 二级商户地址,支持100个中文
phoneNo String(13) N 电话号码,固定电话/手机号码二选一
merNo String(32) N 二级商户编号
category String(20) N 类目
mrchntCertId String(18) N 身份证号

4.2.2 consignee具体参数

参数 类型(长度） 必填 参数说明
consigneeName String(150) N 收货人姓名
consigneeAddr String(200) N 收货地址
transportationInfo String(200) N 物流配送信息,物流名称+订单号
commodityName String(150) N 商品名称
commodityNumber String(10) N 商品数量

4.2.3 installment具体参数

参数 类型(长度） 必填 参数说明
installmentNum String(2) Y 分期期数,支持：3-99 期
discountFeeMode String(2) Y 商户补贴分期手续费方式,0-不贴息；1-贴息；2-全额贴息
discountFeeRate String(20) N 商户分期贴息费率

5、响应参数说明

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

5.1、公共响应参数

参数 类型(长度） 必填 参数说明
code String(5) Y 网关响应码，示例值：00000 ，详见网关公共响应码
msg String(50) Y 网关响应码描述
subCode String Y 业务响应码，参见具体的API接口文档
subMsg String Y 业务响应描述
timeStamp String Y 响应时间，格式"yyyy-MM-dd HH:mm:ss"
norce String(128) Y 随机参数
sign String Y 响应参数的签名串，详见demo,
注意:请用银盛公钥进行验签
businessData String Y 业务响应参数集合，
注意：银盛网关通过AES加密业务响应参数集合，得到businessData，商户需要对其进行解密，详情请见demo

5.2、业务响应参数

响应业务参数businessData(json数据)

参数 类型(长度） 必填 参数说明
reqMsgId String Y 请求流水号
businessData Object N 响应结果

5.2.1 businessData具体参数

参数 类型(长度） 必填 参数说明
orderId String N 订单号,商户系统生成的订单号
tradeSn String N 交易流水号,该交易在银盛支付系统中的
tradeStatus String N 交易状态,交易目前所处的状态。00-交易成功；01-支付成功；02-支付成功,合单交易渠道成功但参与营销，需人工调账；10-待支付；11-支付中（已向渠道跳转）；13-全部已支付(担保交易使用)等待发货；14-未确认收货（等待付款方确认）；80-部分退款；81-全部退款；93-订单撤销；95-关闭订单；96-交易失败（超金额支付）97-客户主动关闭；99-到时关闭；
totalAmount String N 订单总金额,该笔订单的资金总额。单位：分
accountDate String N 入账日期
needSign String N 是否需要重新签约,Y-需重新签约（协议不可用或渠道不可用 ）；N或空（null）-无需重新签约
needSmsConfirm String N 是否需要短信确认,Y-需短信确认；N或空（null）-无需短信确认
paySn String N 支付流水
subMsg String N 返回信息
merDiscountFee String N 商户贴息手续费,单位：分
payStatus String N 该笔支付目前所处的状态,00-交易成功；01-交易处理中；02-已支付,待确认收货；03-待支付,需短信确认；99-交易失败
installment Object N 分期响应信息

5.2.1.1 installment具体参数

参数 类型(长度） 必填 参数说明
installmentNum int N 分期期数
installmentFeeTotal String N 分期应付手续费,单位：分
installmentFeePayMode String N 持卡人手续费支付方式
firstFee String N 首期手续费,单位：分
eachFee String N 每期手续费,单位：分
firstBackAmount String N 首期还款金额,单位：分
realDiscountFeeRate String N 商户分期实际贴息费率

6、业务响应码 网关公共响应码

响应码 响应码描述 解决方案
0000 交易成功
9999 系统错误 请根据返回提示操作或联系银盛技术人员处理
5000 请求超时 请检查网络或稍后重新发起请求
A029998 网关非法参数 检查请求参数，修改后重新发起请求
B020100 参数校验错误 检查请求参数，修改后重新发起请求
B021100 前置系统参数验证错误 检查请求参数，修改后重新发起请求
B023003 商户号错误 检查商户号数据。
B023008 订单不允许支付 订单状态不允许支付，检查订单号对应订单状态

results matching ""

    No results matching ""