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

专业的综合支付与信息服务提供商,提供丰富的支付+行业解决方案,满足各合作伙伴对支付服务的多样场景化需求。
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 post请求,Content-Type设置为application/x-www-form-urlencoded,字符编码格式使用UTF-8
6.请求参数使用URLEncode进行URL编码后再进行传递,防止出现乱码问题

预下单接口

参数名称 参数说明 参数类型 长度 是否必须 备注
version 版本号 字符串 8 固定值:20191031
msgId 消息ID 字符串 4 固定值:115W
requestTimestamp 时间戳 字符串 19 报文请求时间,格式yyyy-MM-dd HH:mm:ss
orderType 订单类型 字符串 2 02快速签单05拆分支付订单
merOrderId 商户订单号 字符串 6..32 商户自行生成(鼠标单击查看说明)
busiOrderId 商户业务订单号 字符串 32
mid 商户号 字符串 15
tid 终端号 字符串 8
instMid 业务类型 字符串 1..32 固定值:KLDEFAULT
goods goodsId 商品ID 字符串 商品对象集合转成的json格式数据:List转成JSONArray
goodsName 商品名称 字符串
quantity 商品数量 字符串
price 商品单价(分) 字符串
goodsCategory 商品分类 字符串
body 商品说明 字符串
subMerchantId 子商户号 字符串
merOrderId 商户子订单号,规则与商户订单号一致:msgId开头,不得超过30位 字符串 30
subOrderAmount 子商户商品总额 字符串
attachedData 商户附加数据 字符串 200
goodsTag 商品标记 字符串 200 用于优惠活动
orderDesc 账单描述 字符串 200
employeeNo 操作员工号 字符串 30
originalAmount 订单原始金额,单位分 数字 10 前端系统打折前的金额
totalAmount 支付总金额,单位分 数字 10
divisionFlag 分账标记 Boolean 5 若为true,subOrders和platformAmount字段不能为空;
asynDivisionFlag 异步分账标记 Boolean 5 取值:true或false,默认false
若为true,则goods字段和subOrders字段不能同时为空;
且secureTransaction字段上送false或不上送。
退货订单不允许做子订单操作
已确认的子订单,不允许隔天再确认
platformAmount 平台商户分账金额 数字 10 与subOrders配合使用
subOrders mid 子商户号 字符串 15 没有分账交易。不需要传递(鼠标单击查看说明)
totalAmount 子商户号所得金额(分) 数字 10
notifyUrl 支付结果通知地址 字符串 200 异步往该地址发送支付结果通知
secureTransaction 标识是否是担保交易 Boolean 5 取值:true或false,默认false
若上送为true,则交易的金额将会被暂缓结算。
调用担保完成接口后,完成部分金额会在t+1日结算给商户,剩余部分金额退还用户。
调用担保撤销接口,则全部资金退还给用户。
30天后 没有主动调用担保完成 且 没有主动调用担保撤销的交易
将会自动按撤销处 理。
placeOrderScene 下单场景 String 200
limitCreditCard 是否需要限制信用卡支付 Boolean 5 取值:true或false,默认false
installmentNumber 花呗分期数 String 10 仅支持支付宝,可分为6或12期
signType 签名算法 字符串 10 支持SM3(推荐),SHA256,不传默认SM3
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
retCommParams foodOrderType 扫码点餐类型 取值: qr_order:店内扫码点餐
pre_order:预点到店自提
home_delivery:外送到家
direct_payment:直接付款
other:其他
字符串 32 扫码点餐信息, 支付宝只需上送扫码foodOrderType字段
云闪付只需上送brandId、storeId、tableNo字段
提醒: 1.请求报文中retCommParams字段示例如
{"brandId":"MY_STYLE","storeId":"S001","tableNo":"T001"}
2.二级字段foodOrderType最大长度为32位。
brandId 品牌标识 字符串 32
storeId 门店标识 字符串 32
tableNo 桌号 字符串 32
thirdPartyInstalSubsFlag 是否开启第三方分期交易贴息 字符串 50 true为本笔交易启用第三方贴息,false或者不传为本笔交易不启用第三方贴息,目前只针对花呗分期交易商户贴息的场景。
clientIp 客户端IP 字符串 50 用户客户端的ip地址
feeRatio 借记卡手续费比例 字符串 50 目前提供给yry的特殊字段,手续费比例,需要按照产品提供的规则上送
creditFeeRatio 贷记卡手续费比例 字符串 50 目前提供给yry的特殊字段,手续费比例,需要按照产品提供的规则上送
costSubsidy 是否成本补贴 字符串 50 yry使用,配合设置手续费比例的配置
,true为不判断手续费比例,false按正常判断,默认false
systemId 系统ID 字符串 50
rstMipPay 是否限制未成年人支付 boolean 50 true
chnlInfo 渠道信息 字符串 50 渠道摘要信息
openId 用户id boolean 50 由商户自定义,保证用户唯一性
extend1 扩展字段1 字符串 50
extend2 扩展字段2 字符串 50
extend3 扩展字段3 字符串 50
extend4 扩展字段4 字符串 50
sign 签名 字符串 64 签名规则(鼠标单击查看说明)
商户订单号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
targetSys 目标平台代码 字符串 30
targetSys 字符串
shareToken 吱口令码值 字符串 1、口令有效期默认最长5分钟。 2、即使旧口令获取时效仍在5分钟内,商户获取了新口令后,旧口令也会默认失效
guideText1 分享引导文案1 字符串 例:#吱口令# 长按复制此条消息即可分享,fj5Vmb00aI,赶紧去分享吧
guideText2 字符串
targetSys 分享引导文案2 字符串 例:#吱口令# 长按复制此条消息即可分享,fj5Vmb00aI,赶紧去分享吧
operationList 营销模型 字符串
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 固定值:KLDEFAULT
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
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 签名规则(鼠标单击查看说明)