昊天数据V4
  1. 支付网关接口
昊天数据V4
  • 扫码POS接口
    • 获取设备支付参数
    • 公共参数&签名
    • 交易记录查询
    • 汇总查询
    • 退款订单查询
    • 支付订单查询
    • 发起退款
    • 设备初始化
    • 设备支付
  • 支付网关接口
    • 签名规则
    • 统一下单
    • 统一退款
    • 发起转账
    • 分账业务
    • 线上支付说明
  1. 支付网关接口

统一下单

商户业务系统通过统一下单接口发起支付收款订单,昊天支付网关会根据商户配置的支付通道路由支付通道完成支付下单。支付网关根据不同的支付方式返回对应的支付参数,业务系统使用支付参数发起收款。
接口说明#
适用对象:普通商户 特约商户
请求URL:https://pay.haotiandate.com/api/pay/unifiedOrder
请求方式:POST
请求类型:application/json 或 application/x-www-form-urlencoded
请求参数#
字段名变量名必填类型示例值描述
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号
支付方式wayCode是String(30)WX_LITE支付方式,如微信小程序WX_LITE
支付金额amount是int100支付金额,单位分
货币代码currency是String(3)cny三位货币代码,人民币:cny
客户端IPclientIp否String(32)210.73.10.148客户端IPV4地址
商品标题subject是String(64)商品标题测试商品标题
商品描述body是String(256)商品描述测试商品描述
门店编号storeId否int10010商户的门店ID
码牌IDqrcId否long10010432445333商户的码牌ID
终端设备信息deviceInfo否String(256){“deviceType”:“auto_pos”,“deviceNo” :“abcde12345”}智能POS、收银插件下单必填,json格式字符串,详见终端设备信息说明
异步通知地址notifyUrl否String(128)https://pay.haotiandate.com/notify.htm支付结果异步回调URL,只有传了该值才会发起回调
跳转通知地址returnUrl否String(128)https://pay.haotiandate.com/return.htm支付结果同步跳转通知URL
失效时间expiredTime否int3600订单失效时间,单位秒,默认2小时.订单在(创建时间+失效时间)后失效
渠道参数channelExtra否String(256{"auth_code":"13920933111042"}特定渠道发起的额外参数,json格式字符串.详见渠道参数说明
分账模式divisionMode否int0分账模式:
0-该笔订单不允许分账[默认],
1-支付成功按配置自动完成分账支付完成自动分账【需包含自动分账接收方,否则自动更新为0(V3.0.0新增)】 ,
2-商户手动分账(解冻商户金额)
扩展参数extParam否String(512)134586944573118714商户扩展参数,回调时会原样返回
请求时间reqTime是long1622016572190请求接口时间,13位时间戳
接口版本version是String(3)1.0接口版本号,固定:1.0
签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值,详见签名算法
签名类型signType是String(32)MD5签名类型,目前只支持MD5方式
终端设备信息说明
字段名变量名必填类型示例值描述
设备类型deviceType是String(20)auto_pos智能POS:auto_pos,收银插件:cash_plugin
设备号deviceNo是String(128)abcde12345设备号必填。设备类型为收银插件时传激活码;其他传设备号
设备厂商provider否String(20)abc除智能POS外的其他设备类型,设备厂商必填
请求示例数据#
{ "amount": 8, "extParam": "", "mchOrderNo": "mho1624005107281", "subject": "商品标题", "wayCode": "ALI_BAR", "sign": "84F606FA25A6EC4783BECC08D4FDC681", "reqTime": "1624005107", "body": "商品描述", "version": "1.0", "channelExtra": "{\"authCode\":\"280812820366966512\"}", "appId": "60cc09bce4b0f1c0b83761c9", "clientIp": "192.166.1.132", "notifyUrl": "https://www.haotiandate.com", "signType": "MD5", "currency": "cny", "returnUrl": "", "mchNo": "M1623984572", "divisionMode": 1 }
返回参数
字段名变量名必填类型示例值描述
返回状态code是int00-处理成功,其他-处理有误,详见错误码
返回信息msg否String(128)签名失败具体错误原因,例如:签名失败、参数格式校验错误
签名信息sign否String(32)CCD9083A6DAD9A2DA9F668C3D4517A84对data内数据签名,如data为空则不返回
返回数据data否String(512){}返回下单数据,json格式数据
data数据格式
字段名变量名必填类型示例值描述
支付订单号payOrderId是String(30)U12021022311124442600返回支付系统订单号
商户订单号mchOrderNo是String(30)20160427210604000490返回商户传入的订单号
订单状态orderState是int2支付订单状态
0-订单生成
1-支付中
2-支付成功
3-支付失败
4-已撤销
5-已退款
6-订单关闭
支付数据类型payDataType是StringpayUrl支付参数类型
payUrl-跳转链接的方式
form-表单方式
wxapp-微信支付参数(微信公众号,小程序,app支付时)
aliapp-支付宝app支付参数
ysfapp-云闪付app支付参数
codeUrl-二维码地址
codeImgUrl-二维码图片地址
none-空支付参数
支付数据payData否Stringhttp://www.jeequan.com/pay.html发起支付用到的支付参数,如果微信公众号支付等
订单信息数据payOrderInfo否String{}订单信息, 当直接支付成功时会返回此数据
渠道错误码errCode否StringACQ.PAYMENT_AUTH_CODE_INVALID上游渠道返回的错误码
渠道错误描述errMsg否StringBusiness Failed 失败上游渠道返回的错误描述
返回示例数据#
`{
  "code": 0,
  "data": {
    "errCode": "ACQ.PAYMENT_AUTH_CODE_INVALID",
    "errMsg": "Business Failed【支付失败,获取顾客账户信息失败,请顾客刷新付款码后重新收款,如再次收款失败,请联系管理员处理。[SOUNDWAVE_PARSER_FAIL]】",
    "mchOrderNo": "mho1624005752661",
    "orderState": 3,
    "payOrderId": "P202106181642329900002"
  },
  "msg": "SUCCESS",
  "sign": "F4DA202C516D1F33A12F1E547C5004FD"
}`

支付方式#

WayCode支付方式
WEB_CASHIERWEB收银台
QR_CASHIER聚合扫码(用户扫商家)
AUTO_BAR聚合条码(商家扫用户)
ALI_BAR支付宝条码
ALI_JSAPI支付宝生活号
ALI_APP支付宝APP
ALI_WAP支付宝WAP
ALI_PC支付宝PC网站
ALI_QR支付宝二维码
WX_BAR微信条码
WX_JSAPI微信公众号
WX_LITE微信小程序
WX_APP微信APP
WX_H5微信H5
WX_NATIVE微信扫码
YSF_BAR云闪付条码
YSF_JSAPI云闪付jsapi
AUTO_POS智能POS
DCEP_BAR数字人民币条码
DCEP_QR数字人民币二维码
channelExtra参数说明
当 wayCode=AUTO_BAR 或 wayCode=ALI_BAR 或 wayCode=WX_BAR 或 wayCode=YSF_BAR 时,channelExtra必须传auth_code,为用户的付款码值,channelExtra示例数据如:
{"authCode": "13920933111042"}
当 wayCode=ALI_JSAPI或 wayCode=ALI_LITE 时,channelExtra必须传buyerUserId,为支付宝用户ID,channelExtra示例数据如:
{"buyerUserId": "2088702585070844"}
当 wayCode=WX_JSAPI 或 wayCode=WX_LITE 时,channelExtra必须传openid,为微信OpenId, channelExtra示例数据如:
{"openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}
注意: 若当前为特约商户,并且商户使用的自己的公众号或者小程序获取到的openId时:
需要:
商户自己的公众号或者小程序的AppId需要在服务商里进行关联, 请联系运营平台进行配置;
channelExtra参数中添加 subAppId 参数,该参数为商户的公众号或小程序的AppId,示例:
{ "openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI", "subAppId":"wx08b5a41f7a27abf1" }
当 wayCode=ALI_QR 或 wayCode=WX_NATIVE 时,channelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为:codeUrl-二维码地址,codeImgUrl-二维码图片地址,不传payDataType默认返回codeUrl类型, channelExtra示例数据如:
{"payDataType": "codeImgUrl"}
当 wayCode=QR_CASHIER 时,channelExtra可以传payDataType和entryPageType。
entryPageType指定聚合码扫码时进入H5或小程序页面,默认为H5页面。h5-h5页面,lite-小程序页面。
payDataType设置返回支付数据支付类型,此时payDataType可以为:codeUrl-二维码地址,codeImgUrl-二维码图片地址,不传payDataType默认返回codeUrl类型, channelExtra示例数据如:
{"entryPageType": "lite", "payDataType": "codeImgUrl"}
当 wayCode=ALI_WAP 时,channelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为:form-返回自动跳转的支付表单,codeImgUrl-返回一个二维码图片URL,payUrl-返回支付链接,不传payDataType默认返回payUrl类型, channelExtra示例数据如:
{"payDataType": "form"}
当 wayCode=ALI_PC 时,channelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为:form-返回自动跳转的支付表单,payUrl-返回支付链接,不传payDataType默认返回payUrl类型, channelExtra示例数据如:
{"payDataType": "form"}

查询订单#

商户通过该接口查询订单,支付网关会返回订单最新的数据

>接口说明#

适用对象:普通商户 特约商户
请求URL:https://pay.haotiandate.com/api/pay/query
请求方式:POST
请求类型:application/json 或 application/x-www-form-urlencoded
> 请求参数#
字段名变量名必填类型示例值描述
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
支付订单号payOrderId是String(30)P20160427210604000490支付中心生成的订单号,与mchOrderNo二者传一即可
商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号,与payOrderId二者传一即可
请求时间reqTime是long1622016572190请求接口时间,13位时间戳
接口版本version是String(3)1.0接口版本号,固定:1.0
签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值,详见签名算法
签名类型signType是String(32)MD5签名类型,目前只支持MD5方式
请求示例数据#
{
  "payOrderId": "P202106181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}
字段名变量名必填类型示例值描述
返回状态code是int00-处理成功,其他-处理有误,详见错误码
返回信息msg否String(128)签名失败具体错误原因,例如:签名失败、参数格式校验错误
签名信息sign否String(32)CCD9083A6DAD9A2DA9F668C3D4517A84对data内数据签名,如data为空则不返回
返回数据data否String(512){}返回下单数据,json格式数据
data数据格式
字段名变量名必填类型示例值描述
支付订单号payOrderId是String(30)P12021022311124442600返回支付系统订单号
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
商户订单号mchOrderNo是String(30)20160427210604000490返回商户传入的订单号
支付接口ifCode是String(30)wxpay支付接口编码
支付方式wayCode是String(30)WX_LITE支付方式,如微信小程序WX_LITE
支付金额amount是int100支付金额,单位分
货币代码currency是String(3)cny三位货币代码,人民币:cny
订单状态state是int2支付订单状态
0-订单生成
1-支付中
2-支付成功
3-支付失败
4-已撤销
5-已退款
6-订单关闭
客户端IPclientIp否String(32)210.73.10.148客户端IPV4地址
商品标题subject是String(64)Jeepay商品标题测试商品标题
商品描述body是String(256)Jeepay商品描述测试商品描述
渠道订单号channelOrderNo否String20160427210604000490对应渠道的订单号
渠道错误码errCode否String1002渠道下单返回错误码
渠道错误描述errMsg否String134586944573118714渠道下单返回错误描述
扩展参数extParam否String(512)134586944573118714商户扩展参数,回调时会原样返回
创建时间createdAt是long1622016572190订单创建时间,13位时间戳
成功时间successTime否long1622016572190订单支付成功时间,13位时间戳
返回示例数据
{
  "code": 0,
  "data": {
    "amount": 58,
    "appId": "60cc09bce4b0f1c0b83761c9",
    "body": "商品描述",
    "channelOrderNo": "2021061822001423031419593035",
    "clientIp": "192.166.1.132",
    "createdAt": 1623985457705,
    "currency": "cny",
    "extParam": "",
    "ifCode": "alipay",
    "mchNo": "M1623984572",
    "mchOrderNo": "mho1623985457320",
    "payOrderId": "P202106181104177050002",
    "state": 2,
    "subject": "商品标题",
    "successTime": 1623985459000,
    "wayCode": "ALI_BAR"
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

关闭订单#

商户通过该接口关闭订单,支付网关会对订单完成关闭处理。
接口说明#
适用对象:普通商户 特约商户
请求URL:https://pay.haotiandate.com/api/pay/close
请求方式:POST
请求类型:application/json 或 application/x-www-form-urlencoded
> 请求参数#
字段名变量名必填类型示例值描述
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
支付订单号payOrderId是String(30)P20160427210604000490支付中心生成的订单号,与mchOrderNo二者传一即可
商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号,与payOrderId二者传一即可
请求时间reqTime是long1622016572190请求接口时间,13位时间戳
接口版本version是String(3)1.0接口版本号,固定:1.0
签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值,详见签名算法
签名类型signType是String(32)MD5签名类型,目前只支持MD5方式
请求示例数据#
{
  "payOrderId": "P202106181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}
字段名变量名必填类型示例值描述
返回状态code是int00-处理成功,其他-处理有误,详见错误码
返回信息msg否String(128)签名失败具体错误原因,例如:签名失败、参数格式校验错误
签名信息sign否String(32)CCD9083A6DAD9A2DA9F668C3D4517A84对data内数据签名,如data为空则不返回
返回数据data否String(512){}返回下单数据,json格式数据
data数据格式
字段名变量名必填类型示例值描述
渠道错误码errCode否String1002渠道关单返回错误码
渠道错误描述errMsg否String关闭异常渠道关单返回错误描述
返回示例数据#
{
  "code": 0,
  "data": {
    "errCode": '',
    "errMsg": ''
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}
条码换取openId
商户通过该接口上送刷卡条码值, 换取到微信openId。
接口说明#
适用对象:普通商户`` 特约商户
请求URL:https://pay.haotiandate.com/api/pay/queryOpenIdByBarcode
请求方式:POST
请求类型:application/json 或 application/x-www-form-urlencoded
请求参数#
字段名变量名必填类型示例值描述
商户号mchNo是String(64)M1621873433953商户号
应用IDappId是String(64)60cc09bce4b0f1c0b83761c9应用ID
条码数据barCode是String(60)20160427210604000490条码值
subAppIdsubAppId 否 String(30)20160427210604000490若传入则透传到三方支付
请求时间reqTime是long1622016572190请求接口时间,13位时间戳
接口版本version是String(3)1.0接口版本号,固定:1.0
签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值,详见签名算法
签名类型signType是String(32)MD5签名类型,目前只支持MD5或RSA2方式
请求示例数据#
{
  "barCode": "202106181104177050002",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}
字段名变量名必填类型示例值描述
返回状态code是int00-处理成功,其他-处理有误,详见错误码
返回信息msg否String(128)签名失败具体错误原因,例如:签名失败、参数格式校验错误
签名信息sign否String(32)CCD9083A6DAD9A2DA9F668C3D4517A84对data内数据签名,如data为空则不返回
返回数据data否String(512){}返回下单数据,json格式数据
data数据格式#
字段名变量名必填类型示例值描述
openIdopenId否String1002openId
subOpenIdsubOpenId否String1002subOpenId
返回示例数据#
{
  "code": 0,
  "data": {
    "openId": '',
    "subOpenId": ''
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

支付通知#

当订单支付成功时,支付网关会向商户系统发起回调通知。如果商户系统没有正确返回,支付网关会延迟再次通知。
接口说明
适用对象:普通商户 特约商户
请求URL:该链接是通过统一下单接口提交的参数notifyUrl设置,如果无法访问链接,商户系统将无法接收到支付中心的通知。
请求方式:POST
请求类型:application/x-www-form-urlencoded
通知参数
字段名变量名必填类型示例值描述
支付订单号payOrderId是String(30)P12021022311124442600返回支付系统订单号
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
商户订单号mchOrderNo是String(30)20160427210604000490返回商户传入的订单号
支付接口ifCode是String(30)wxpay支付接口编码
支付方式wayCode是String(30)WX_LITE支付方式,微信小程序WX_LITE
支付金额amount是int100支付金额,单位分
货币代码currency是String(3)cny三位货币代码,人民币:cny
订单状态state是int2支付订单状态
0-订单生成
1-支付中
2-支付成功
3-支付失败
4-已撤销
5-已退款
6-订单关闭
客户端IPclientIp否String(32)210.73.10.148客户端IPV4地址
商品标题subject是String(64)商品标题测试商品标题
商品描述body是String(256)商品描述测试商品描述
渠道订单号channelOrderNo否String20160427210604000490对应渠道的订单号
渠道错误码errCode否String1002渠道下单返回错误码
渠道错误描述errMsg否String134586944573118714渠道下单返回错误描述
扩展参数extParam否String(512)134586944573118714商户扩展参数
支付成功时间successTime否long1622016572190订单支付成功时间,13位时间戳
创建时间createdAt是long1622016572190订单创建时间,13位时间戳
通知请求时间reqTime是String(30)1622016572190通知请求时间,,13位时间戳
签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值,详见签名算法
以下扩展参数如需同步传递需在商户后台配置
字段名变量名必填类型示例值描述
商户门店IDstoreId否int商户门店ID
经度lng否String商户门店ID
纬度lat否String商户门店ID
码牌IDqrcId否int商户门店ID
支付方式代码分类wayCodeType否String商户门店ID
商户手续费费率mchFeeRate否String商户门店ID
商户手续费mchFeeAmount否int商户手续费,单位分
渠道用户标识channelUser否String渠道用户标识,如微信openId,支付宝账号
订单分账模式divisionMode否int订单分账模式:0-该笔订单不允许分账, 1-支付成功按配置自动完成分账, 2-商户手动分账(解冻商户金额)
买家备注buyerRemark否String买家备注
卖家备注sellerRemark否String卖家备注
订单失效时间expiredTime否long订单失效时间
支付凭证交易单号platformOrderNo否String支付凭证交易单号
支付凭证商户单号platformMchOrderNo否String支付凭证商户单号
> 返回结果
业务系统处理后同步返回给支付中心,返回字符串 success 则表示成功,返回非success则表示处理失败,支付中心会再次通知业务系统。(通知频率为0/30/60/90/120/150,单位:秒)
注意:返回的字符串不区分大小写,字符串前后不能有空格和换行符。
通知示例数据
{
    "amount": 5,
    "body": "商品描述",
    "clientIp": "192.166.1.132",
    "createdAt": "1622016572190",
    "currency": "cny",
    "extParam": "",
    "ifCode": "wxpay",
    "mchNo": "M1621873433953",
    "appId": "60cc09bce4b0f1c0b83761c9",
    "mchOrderNo": "mho1621934803068",
    "payOrderId": "20210525172643357010",
    "state": 3,
    "subject": "商品标题",
    "wayCode": "WX_BAR",
    "sign": "C380B***BFD727A***8451***19F3AD6"
}

获取渠道用户ID#

商户通过该接口获取渠道的用户ID,如微信的openID,支付宝的userId。该接口通过跳转获取到用户ID后,会跳转到商户上传的redirectUrl地址,并传递用户ID参数
接口说明
适用对象:普通商户`` 特约商户
请求URL:https://pay.haotiandate.com/api/channelUserId/jump
请求方式:GET
请求类型:application/x-www-form-urlencoded
请求参数
字段名变量名必填类型示例值描述
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
支付接口ifCode是String(30)AUTO目前只支持传 AUTO
跳转地址redirectUrl是Stringhttps://www.haotiandate.com获取到用户ID后,会携带用户ID参数跳转到该地址
请求时间reqTime是long1622016572190请求接口时间,13位时间戳
接口版本version是String(3)1.0接口版本号,固定:1.0
签名sign是String(32)C380BEC2BFD727A4B6845133519F3AD6签名值,详见签名算法
签名类型signType是String(32)MD5签名类型,目前只支持MD5方式
请求示例数据#
{
  "mchNo": "M1621873433953",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "ifCode": "wxpay",
  "redirectUrl": "https://www.haotiandate.com",
  "sign": "A5C93D50743126ED91AA6ED96CDEEEF8",
  "signType": "MD5",
  "reqTime": "1622011236571",
  "version": "1.0"
}
当获取到渠道用户ID后,会301重定向到跳转地址,传递参数如下
字段名变量名必填类型示例值描述
渠道用户IDchannelUserId是Stringo6BcIwvSiRpfS8e_UyfQNrYuk2LI渠道用户ID,微信openId或支付宝userId
完整跳转URL示例#
https://www.haotiandate.com/toU?channelUserId=o6BcIwvSiRpfS8e_UyfQNrYuk2LI

返回码#

code描述
0成功
9999异常,具体错误详见msg字段
修改于 2025-05-07 11:17:23
上一页
签名规则
下一页
统一退款
Built with