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

专业的综合支付与信息服务提供商,提供丰富的支付+行业解决方案,满足各合作伙伴对支付服务的多样场景化需求。
1.本文档下述每个接口的应答报文里errCode字段为系统应答码,status字段为交易状态码
2.商户需自行生成merOrderId。此时merOrderId需要符合银商规范,以银商分配的4位系统编号作为订单号的前4位,且在商户系统中此订单号保证唯一。总长度需大于6位,小于32位。银商的推荐规则为(无特殊情况下,建议遵守此规则):{来源编号(4位)}{时间(yyyyMMddmmHHssSSS)(17位)}{7位随机数}
3.测试环境接口地址:https://dhjt-uat.chinaums.com/queryService/UmsWebPayPlugins
4.生产环境接口地址:https://生产域名/queryService/UmsWebPayPlugins (交易请在测试环境验收完成后,再调用生产环境)
5.下单请求对接,商户后台发起http get/post请求,Content-Type设置为application/x-www-form-urlencoded,字符编码格式使用UTF-8
6.请求参数使用URLEncode进行URL编码后再进行传递,防止出现乱码问题

支付下单接口

参数名称 参数说明 参数类型 长度 是否必须 备注
version 版本号 字符串 8 是 固定值:20191031
msgId 消息ID 字符串 4 是 固定值:4217
msgType 消息类型 字符串 1..64 是 微信: wx.unifiedOrder
微信(app跳转小程序支付) :wx.appPreOrder
支付宝: trade.precreate
支付宝(支付宝跳转小程序支付): trade.appPreOrder
ApplePay支付: applepay.order
银联云闪付: uac.appOrder
requestTimestamp 时间戳 字符串 19 是 报文请求时间,格式yyyy-MM-dd HH:mm:ss
expireTime 订单过期时间 字符串 19 否 格式:yyyy-MM-dd HH:mm:ss
orderType 订单类型 字符串 2 否 02快速签单05拆分支付订单
merOrderId 商户订单号 字符串 6..32 是 商户自行生成(鼠标单击查看说明)
busiOrderId 商户业务订单号 字符串 32 否
mid 商户号 字符串 15 是
tid 终端号 字符串 8 是
subAppId 微信支付的appid 字符串 8 否 微信支付必传,用于调起微信小程序
instMid 业务类型 字符串 1..32 是 固定值:APPDEFAULT
attachedData 商户附加数据 字符串 200 否
orderDesc 账单描述 字符串 200 否
employeeNo 操作员工号 字符串 30 否
originalAmount 订单原始金额,单位分 数字 10 前端系统打折前的金额
totalAmount 支付总金额,单位分 数字 10 是
installmentNumber 花呗分期数 String 10 否 仅支持支付宝,可分为6或12期
notifyUrl 支付结果通知地址 字符串 200 否 异步往该地址发送支付结果通知
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
tradeType 交易类型 字符串 30 否 微信必传:APP
merchantUserId 商户用户号 字符串 32 否 applepay下单时 必传
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 否
limitCreditCard 是否需要限制信用卡支付 Boolean 5 否 取值:true或false,默认false
secureTransaction 标识是否是担保交易 Boolean 5 否 取值:true或false,默认false
若上送为true,则交易的金额将会被暂缓结算。
调用担保完成接口后,完成部分金额会在t+1日结算给商户,剩余部分金额退还用户。
调用担保撤销接口,则全部资金退还给用户。
30天后 没有主动调用担保完成 且 没有主动调用担保撤销的交易
将会自动按撤销处 理。
asynDivisionFlag 异步分账标记 Boolean 5 否 取值:true或false,默认false
若为true,则goods字段和subOrders字段不能同时为空;
且secureTransaction字段上送false或不上送。
退货订单不允许做子订单操作
已确认的子订单,不允许隔天再确认
limitCreditCard 是否需要限制信用卡支付 字符串 5 否 取值:true或false,默认false
supportBank 支持的银行 字符串 40 否 仅支持云闪付支付
支持直接拉起特定银行APP,目前支持:
CCB(中国建设银行)、
CNCB(中信银行手机银行)、CEB(光大银行手机银行)、
PAB(平安口袋银行)
invokeType 调起方式 字符串 16 否 仅支持云闪付支付
在统一收银台直通模式业务下,商户调起银行APP的方式
APP_H5:APP+H5
APP:APP
H5:H5
默认取值APP_H5。
若上送此字段,则必须上送supportBank字段,否则将拒绝交易。
issueInvoice 开具发票 字符串 4000 否
普通开票的需求(鼠标单击查看说明)
开票文档地址:银联商务发票服务平台标准接口文档v6.4

乐企联用开票的需求(鼠标单击查看说明)
乐企联用开票文档地址:银联商务发票(乐企)服务平台标准接口文档v4.0
issueType 开具发票渠道 字符串 5 否 普通开票,此处不传值
乐企联用开票,此处传lq
issueServiceName 乐企开票业务类型 字符串 50 否 此处是配合乐企开票使用,普通开票无需关注此处
不传默认是lqpt.jointIssue
乐企联用开票,5.3开具发票(乐企联用),此处传lqpt.jointIssue
乐企联用开票,6.2生成开票二维码,此处传lqpt.getQrCode
areaRoute 地区码 字符串 50 否
extend1 扩展字段1 字符串 50 否
extend2 扩展字段2 字符串 50 否
extend3 扩展字段3 字符串 50 否
extend4 扩展字段4 字符串 50 否
sign 签名 字符串 64 是 签名规则(鼠标单击查看说明)
APP支付下单接口属于后台模式对接,同步响应json格式字符串,商户前端使用返回的支付要素,调用插件,唤醒第三方app进行支付。注意:所有的请求参数都需要使用URLEncoder.encode进行编码,字符编码格式是UTF-8,签名时参数值是没有编码的,发送请求时参数值都需要进行编码
商户订单号merOrderId生成规则
商户需自行生成merOrderId。此时merOrderId需要符合银商规范,以银商分配的4位来源编号(msgId的值)作为订单号的前4位,且在商户系统中此订单号保证唯一。总长度需大于6位,小于32位银商的推荐规则为(无特殊情况下,建议遵守此规则):{来源编号(4位)}{时间(yyyyMMddmmHHssSSS)(17位)}{7位随机数}
如有分账需求
需要传subOrders,分账信息则严格按subOrders里的分账方案生成。 subOrders的子商户号,子商户分账金额必传,即subOrders每个元素的mid和totalAmount非 空 且 mid不超过20个。(分账方案subOrders里子商户分账总额+platformAmount要与支付 总额totalAmount相等)
签名规则
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。

同步响应参数

1.同步应答为JSON格式的字符串
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 不明确的交易状态
参数名称 参数说明 参数类型 长度 是否必须 备注
version 版本号 字符串 10 是 固定值:20191031
errCode 平台错误码 字符串 64 是 取值参考下面说明
errMsg 平台错误描述 字符串 255 是
responseTimestamp 时间戳 字符串 19 是 响应时间,格式yyyy-MM-dd HH:mm:ss
seqId 平台流水号 字符串 30 否 类似检索参考号
settleRefId 清分 字符串 30 否 如果来源方传了bankRefId就等于bankRefId,否则等于seqId
status 交易状态 字符串 30 否 取值参考说明
targetOrderId 第三方订单号 字符串 50 否
targetSys 目标平台代码 字符串 30 否
targetStatus 目标平台的状态 字符串 30 否
appPayRequest APP支付用的请求报文,带有签名信息 字符串 500 否 支付插件需要使用它进行调用支付
msgType 消息类型 字符串 1..64 是 原样返回
merOrderId 商户订单号 字符串 6..32 是 原样返回
mid 商户号 字符串 15 是 原样返回
tid 终端号 字符串 8 是 原样返回
employeeNo 操作员工号 字符串 30 否 原样返回
attachedData 商户附加数据 字符串 200 否 原样返回
originalAmount 订单原始金额,单位分 数字 10 否 原样返回
totalAmount 支付总金额,单位分 数字 10 是 原样返回
platformAmount 平台商户分账金额 数字 10 否 原样返回
subOrders 分账明细 字符串 10 否 原样返回
signType 签名算法 字符串 10 是 原样返回
subAppId 商户微信appId 字符串 30 否 原样返回
extend1 扩展字段1 字符串 50 否原样返回
extend2 扩展字段2 字符串 50 否原样返回
extend3 扩展字段3 字符串 50 否原样返回
extend4 扩展字段4 字符串 50 否原样返回
sign 签名 字符串 64 是 签名规则(鼠标单击查看说明)

异步推送支付通知

异步推送是服务器端对接时,支付完成后,大华捷通服务器收到渠道方返回的支付通知后,会进行通知给商户,商户收到响应后,需要在超时时间内做出应答,大华捷通再未收到应答或者应答不是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 是 固定值:APPDEFAULT
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 否
refundAmount 退款金额 数字(单位:分) 10 否
refundDesc 退款说明 字符串 50 否
refundTargetOrderId 退货渠道订单号 字符串 30 否
refundPayTime 退货时间 字符串 否
refundSettleDate 退货结算日期 字符串 否
seqId 系统交易流水号 字符串 30 否
settleDate 结算日期 字符串 10 否 格式yyyy-MM-dd
subBuyerId 卖家子ID 字符串 30 否
targetOrderId 渠道订单号 字符串 50 否
targetSys 支付渠道 字符串 30 否
orderDesc 订单详情 字符串 30 否
queryId 银联商务大华捷通系统流水号 字符串 30 是
qrCodeUrl 开票二维码地址 字符串 256 否 乐企联动开票,此处会返回6.2生成开票二维码的开票地址
msgType 消息类型 字符串 1..64 是 原样返回
merOrderId 商户订单号 字符串 6..32 是 原样返回
mid 商户号 字符串 15 是 原样返回
tid 终端号 字符串 8 是 原样返回
employeeNo 操作员工号 字符串 30 否 原样返回
attachedData 商户附加数据 字符串 200 否 原样返回
originalAmount 订单原始金额,单位分 数字 10 否 原样返回
totalAmount 支付总金额,单位分 数字 10 是 原样返回
platformAmount 平台商户分账金额 数字 10 否 原样返回
subOrders 分账明细 字符串 10 否 原样返回
signType 签名算法 字符串 10 是 原样返回
subAppId 商户微信appId 字符串 30 否 原样返回
extend1 扩展字段1 字符串 50 否原样返回
extend2 扩展字段2 字符串 50 否原样返回
extend3 扩展字段3 字符串 50 否原样返回
extend4 扩展字段4 字符串 50 否原样返回
sign 签名 字符串 64 是 签名规则(鼠标单击查看说明)