银联商务大华捷通综合支付支付宝口令支付下单接口文档
专业的综合支付与信息服务提供商,提供丰富的支付+行业解决方案,满足各合作伙伴对支付服务的多样场景化需求。
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 |
|
| 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 | 是 | 签名规则(鼠标单击查看说明) |