银联商务大华捷通综合支付H5支付下单接口文档

专业的综合支付与信息服务提供商,提供丰富的支付+行业解决方案,满足各合作伙伴对支付服务的多样场景化需求。
1.本文档下述每个接口的应答报文里errCode字段为系统应答码,status字段为交易状态码
2.商户需自行生成merOrderId。此时merOrderId需要符合银商规范,以银商分配的4位系统编号作为订单号的前4位,且在商户系统中此订单号保证唯一。总长度需大于6位,小于32位。
3.测试环境接口地址:https://dhjt-uat.chinaums.com/queryService/UmsWebPayPlugins
4.生产环境接口地址:https://生产域名/queryService/UmsWebPayPlugins (交易请在测试环境验收完成后,再调用生产环境)
5.本接口为商户的订单H5页面向银商系统发起的支付跳转
6.请求参数使用URLEncode进行URL编码后再进行传递,防止出现乱码问题

支付下单接口

参数名称 参数说明 参数类型 长度 是否必须 备注
version 版本号 字符串 8 固定值:20191031
msgId 消息ID 字符串 4 固定值:4217
msgType 消息类型 字符串 1..64 支付宝H5支付:trade.h5Pay
银联云闪付(走银联全渠道):uac.order
requestTimestamp 时间戳 字符串 19 报文请求时间,格式yyyy-MM-dd HH:mm:ss
merOrderId 商户订单号 字符串 6..32 商户自行生成(鼠标单击查看说明)
busiOrderId 商户业务订单号 字符串 32
expireTime 订单过期时间 字符串 19 格式:yyyy-MM-dd HH:mm:ss
orderType 订单类型 字符串 2 02快速签单05拆分支付订单
mid 商户号 字符串 15
tid 终端号 字符串 8
instMid 业务类型 字符串 1..32 固定值:H5DEFAULT
attachedData 商户附加数据 字符串 200
orderDesc 账单描述 字符串 200
employeeNo 操作员工号 字符串 30
originalAmount 订单原始金额,单位分 数字 10 前端系统打折前的金额
totalAmount 支付总金额,单位分 数字 10
notifyUrl 支付结果通知地址 字符串 200 异步往该地址发送支付结果通知
returnUrl 回跳地址 字符串 200 支付完成后将回跳该地址
installmentNumber 花呗分期数 String 10 仅支持支付宝,可分为6或12期
asynDivisionFlag 异步分账标记 Boolean 50 取值:true或false,默认false
若为true,则goods字段和subOrders字段不能同时为空;
且secureTransaction字段上送false或不上送。
退货订单不允许做子订单操作
已确认的子订单,不允许隔天再确认
sceneType 业务应用类型 String 16 微信H5支付必填。
用于苹app应用里值为IOS_SDK ;
用于安卓app 应用里值为AND_SDK;
用于手机网站,值为IOS_WAP 或AND_WAP
merAppName 应用名称 String 64 微信H5支付必填。
用于苹或安卓app 应用中,传分别 对应在 AppStore和安卓分发市场中的应用名(如:全民付);
用于手机网站,传对应的网站名(如:银联商务官网)
merAppId 应用标识 String 128 微信H5支付必填。
用于苹果或安卓 app 应用中,苹果传 IOS 应用唯一标识(如: com.tencent.wzryIOS )
安卓传包名 (如: com.tencent.tmgp.sgame)
如果是用于手机网站 ,传首页 URL 地址 , (如: https://m.jd.com ) ,支付宝H5支付参数无效
divisionFlag 分账标记 Boolean 5 若为true,subOrders和platformAmount字段不能为空;
goods goodsId 商品ID 字符串 商品对象集合转成的json格式数据:List转成JSONArray
goodsName 商品名称 字符串
quantity 商品数量 字符串
price 商品单价(分) 字符串
goodsCategory 商品分类 字符串
body 商品说明 字符串
subMerchantId 子商户号 字符串
merOrderId 商户子订单号,规则与商户订单号一致:msgId开头,不得超过30位 字符串 30
subOrderAmount 子商户商品总额 字符串
subOrders mid 子商户号 字符串 15 没有分账交易。不需要传递(鼠标单击查看说明)
totalAmount 子商户号所得金额(分) 数字 10
platformAmount 平台商户分账金额 数字 10 与subOrders配合使用
signType 签名算法 字符串 10 支持SM3(推荐),SHA256,不传默认SM3
limitCreditCard 是否需要限制信用卡支付 Boolean 5 取值:true或false,默认false
secureTransaction 标识是否是担保交易 Boolean 5 取值:true或false,默认false
若上送为true,则交易的金额将会被暂缓结算。
调用担保完成接口后,完成部分金额会在t+1日结算给商户,剩余部分金额退还用户。
调用担保撤销接口,则全部资金退还给用户。
30天后 没有主动调用担保完成 且 没有主动调用担保撤销的交易
将会自动按撤销处 理。
issueInvoice 开具发票 字符串 4000 如有开具发票的需求(鼠标单击查看说明)
开票文档地址:银联商务发票服务平台标准接口文档v6.4
fixBuyer 是否需要实名认证 字符串 0..32 如果需要生成实名认证,才需要传递
微信必传name、certNo和fixBuyer=T;
支付宝必传name、certType、certNo和fixBuyer=T。
注意证件类型:微信暂时只支持身份证IDENTITY_CARD,
支付宝支持身份证IDENTITY_CARD、 护照PASSPORT、
军官证OFFICER_CARD、士兵证SOLDIER_CARD、
户口本HOKOU"
敏感信息 如姓名、证件号和手机号信息需要 Base64进行加密传输。
(鼠标单击查看说明)
name 实名认证姓名 字符串 0..32
mobile 实名认证手机号 字符串 0..20
certType 实名认证证件类型 字符串 0..32
certNo 实名认证证件号 字符串 0..32
extend1 扩展字段1 字符串 50
extend2 扩展字段2 字符串 50
extend3 扩展字段3 字符串 50
extend4 扩展字段4 字符串 50
instalFlag 分期标识 布尔型 取值:true或false,仅支持云闪付支付 false:不强制分期true:强制分期 默认false
sign 签名 字符串 64 签名规则(鼠标单击查看说明)
公众号支付前台跳转模式对接,注意:此处get请求,所有的请求参数都需要使用URLEncoder.encode进行编码,字符编码格式是UTF-8,签名时参数值是没有编码的,发送请求时参数值都需要进行编码
商户订单号merOrderId生成规则
商户需自行生成merOrderId。此时merOrderId需要符合银商规范,以银商分配的4位来源编号(msgId的值)作为订单号的前4位,且在商户系统中此订单号保证唯一。总长度需大于6位,小于32位
如有分账需求
需要传subOrders,分账信息则严格按subOrders里的分账方案生成。 subOrders的子商户号,子商户分账金额必传,即subOrders每个元素的mid和totalAmount非 空 且 mid不超过20个。(分账方案subOrders里子商户分账总额+platformAmount要与支付 总额totalAmount相等)
如果需要实名认证(只支持扫码支付和公众号支付)
微信必传姓名name和证件号certNo,强制校验位fixBuyer=T;支付宝必传姓名name,证 件类型certType,证件号certNo,强制校验位fixBuyer=T。 注意:微信实名认证暂时只支持身份证,支付宝支持的证件类型包括:身份证IDENTITY_CARD、 护照PASSPORT、军官证OFFICER_CARD、士兵证SOLDIER_CARD、户口本HOKOU。敏感信息 如姓名、证件号和手机号信息需要 base64进行加密传输
签名规则
1.签名支持SM3(推荐)和SHA256方式(不上送signType字段时,SM3),计算sign的输入数据为待签名字符串加上key(即:签名密钥),key由大华捷通平台分配。
2.在请求参数列表中,除去sign和空值的参数外,其他需要使用到的参数均为要签名的参数

生成待签名字符串
第一步:设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。

特别注意以下重要规则:
(1).参数名ASCII码从小到大排序(字典序);
(2).如果参数的值为空不参与签名;
(3).参数名区分大小写;
(4).验证调用返回时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。
(5).大华捷通平台接口可能增加字段,验证签名时必须支持增加的扩展字段
第二步:在stringA最后拼接上key得到stringSignTemp字符串,并对stringSignTemp进行SHA256运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。

同步返回商户系统

H5支付是基于浏览器跳转的,提交下单参数成功后,会直接重定向到渠道的h5支付页面。如果商户下单参数中传入了returnUrl,支付完成后或者支付前验证失败,将会跳转到商户的returnUrl接口上。如果没有传入returnUrl,无需关注此处
参数名称 参数说明 参数类型 长度 是否必须 备注
version 版本号 字符串 8 固定值:20191031
msgId 消息ID 字符串 4 固定值:4217
responseTimestamp 时间戳 字符串 19 响应时间,格式yyyy-MM-dd HH:mm:ss
instMid 业务类型 字符串 1..32 固定值:YUEDANDEFAULT
status 订单状态 字符串 30 参考取值说明(鼠标单击查看取值说明)
bankCardNo 支付银行信息 字符串 50
billFunds 资金渠道 字符串 50
billFundsDesc 资金渠道说明 字符串 50
buyerId 买家ID 字符串 50
buyerUsername 买家用户名 字符串 50
couponAmount 网付计算的优惠金额 数字(单位:分) 10
buyerPayAmount 实付金额 数字(单位:分) 10
invoiceAmount 开票金额 数字(单位:分) 10
receiptAmount 实收金额 数字(单位:分) 10
payTime 支付时间 字符串 19 格式yyyy-MM-dd HH:mm:ss
refId 支付银行卡参考号 字符串 19 格式yyyy-MM-dd HH:mm:ss
refundAmount 退款金额 数字(单位:分) 10
refundDesc 退款说明 字符串 19
seqId 系统交易流水号 字符串 30
settleDate 结算日期 字符串 10 格式yyyy-MM-dd
subBuyerId 卖家子ID 字符串 30
targetOrderId 渠道订单号 字符串 50
targetSys 支付渠道 字符串 30
orderDesc 订单详情 字符串 30
queryId 银联商务大华捷通系统流水号 字符串 30
msgType 消息类型 字符串 1..64 原样返回
merOrderId 商户订单号 字符串 6..32 原样返回
mid 商户号 字符串 15 原样返回
tid 终端号 字符串 8 原样返回
employeeNo 操作员工号 字符串 30 原样返回
attachedData 商户附加数据 字符串 200 原样返回
originalAmount 订单原始金额,单位分 数字 10 原样返回
totalAmount 支付总金额,单位分 数字 10 原样返回
platformAmount 平台商户分账金额 数字 10 原样返回
subOrders 分账明细 字符串 10 原样返回
signType 签名算法 字符串 10 原样返回
extend1 扩展字段1 字符串 50 原样返回
extend2 扩展字段2 字符串 50 原样返回
extend3 扩展字段3 字符串 50 原样返回
extend4 扩展字段4 字符串 50 原样返回
sign 签名 字符串 64 签名规则(鼠标单击查看说明)
1.公众号支付前台跳转模式对接,同步跳转到商户系统,采用get方式跳转(方便vue等前后分离项目获取参数),商户收到跳转请求后,验证签名的规则与支付下单一致,获取全部非空值的参数参与签名,获取到参数需要使用URLDecoder.decode进行解码,字符编码格式是UTF-8,验签时的参数值是解码之后的值
2.根据status参数值判断是否支付成功(此处status并不能作为是否支付的标准,具体支付结果以后台通知为准,商户可以在此处收到status是TRADE_SUCCESS时,使用查询交易结果接口查询交易状态),

status的取值:
(1).NEW_ORDER新订单
(2).TRADE_CLOSED 在指定时间段内未支付时关闭的交易;在交易完成全额退款成功时关闭的交易;支付失败的交易。 TRADE_CLOSED的交易不允许进行任何操作。
(3).WAIT_BUYER_PAY 交易创建,等待买家付款。
(4).TRADE_SUCCESS 支付成功
(5).TRADE_REFUND 订单转入退货流程 退货可能是部分也可能是全部。
(6).UNKNOWN 不明确的交易状态

异步推送支付通知

异步推送是服务器端对接时,支付完成后,大华捷通服务器收到渠道方返回的支付通知后,会进行通知给商户,商户收到响应后,需要在超时时间内做出应答,大华捷通再未收到应答或者应答不是SUCCESS时,会多次进行推送, 商户需要做好同一个订单可能会推送多次情况的处理。为了安全,在推送的参数中,可能会随机添加新的参数,商户端接口必须要支持新增参数,不能因为新增参数而导致通知失败
异步推送签名信息进行验证,验证规则如下:
1.签名支持SM3(推荐)和SHA256方式(不上送signType字段时,SM3),计算sign的输入数据为待签名字符串加上key(即:签名密钥),key由大华捷通平台分配。
2.在请求参数列表中,除去sign和空值的参数外,其他需要使用到的参数均为要签名的参数

生成待签名字符串
第一步:设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。

特别注意以下重要规则:
(1).参数名ASCII码从小到大排序(字典序);
(2).如果参数的值为空不参与签名;
(3).参数名区分大小写;
(4).验证调用返回时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。
(5).大华捷通平台接口可能增加字段,验证签名时必须支持增加的扩展字段
第二步:在stringA最后拼接上key得到stringSignTemp字符串,并对stringSignTemp进行SHA256运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。
参数名称 参数说明 参数类型 长度 是否必须 备注
version 版本号 字符串 8 固定值:20191031
msgId 消息ID 字符串 4 固定值:4217
responseTimestamp 时间戳 字符串 19 响应时间,格式yyyy-MM-dd HH:mm:ss
instMid 业务类型 字符串 1..32 固定值:YUEDANDEFAULT
status 订单状态 字符串 30 参考取值说明(鼠标单击查看取值说明)
bankCardNo 支付银行信息 字符串 50
bankInfo 支付银行 字符串 50
billFunds 资金渠道 字符串 50
billFundsDesc 资金渠道说明 字符串 50
buyerId 买家ID 字符串 50
buyerUsername 买家用户名 字符串 50
couponAmount 网付计算的优惠金额 数字(单位:分) 10
buyerPayAmount 实付金额 数字(单位:分) 10
invoiceAmount 开票金额 数字(单位:分) 10
receiptAmount 实收金额 数字(单位:分) 10
payTime 支付时间 字符串 19 格式yyyy-MM-dd HH:mm:ss
refId 支付银行卡参考号 字符串 19 格式yyyy-MM-dd HH:mm:ss
refundAmount 退款金额 数字(单位:分) 10
refundDesc 退款说明 字符串 19
seqId 系统交易流水号 字符串 30
settleDate 结算日期 字符串 10 格式yyyy-MM-dd
subBuyerId 卖家子ID 字符串 30
targetOrderId 渠道订单号 字符串 50
targetSys 支付渠道 字符串 30
orderDesc 订单详情 字符串 30
queryId 银联商务大华捷通系统流水号 字符串 30
msgType 消息类型 字符串 1..64 原样返回
merOrderId 商户订单号 字符串 6..32 原样返回
mid 商户号 字符串 15 原样返回
tid 终端号 字符串 8 原样返回
employeeNo 操作员工号 字符串 30 原样返回
attachedData 商户附加数据 字符串 200 原样返回
originalAmount 订单原始金额,单位分 数字 10 原样返回
totalAmount 支付总金额,单位分 数字 10 原样返回
platformAmount 平台商户分账金额 数字 10 原样返回
subOrders 分账明细 字符串 10 原样返回
signType 签名算法 字符串 10 原样返回
subOpenId 付款人openid 字符串 30 原样返回
subAppId 商户微信appId 字符串 30 原样返回
extend1 扩展字段1 字符串 50 原样返回
extend2 扩展字段2 字符串 50 原样返回
extend3 扩展字段3 字符串 50 原样返回
extend4 扩展字段4 字符串 50 原样返回
sign 签名 字符串 64 签名规则(鼠标单击查看说明)