Skip to main content

对接文档

接口协议规则

  • 传输方式：采用HTTP传输(生产环境建议HTTPS)
  • 提交方式：POST
  • 内容类型：application/json
  • 字符编码：UTF-8
  • 签名算法：MD5

参数规范

  • 交易金额：默认为人民币交易，单位为元，支持小数点两位.

签名算法

签名生成的通用步骤如下

第一步： 设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。 特别注意以下重要规则：

  • 参数名ASCII码从小到大排序(字典序)
  • 如果参数的值为空不参与签名
  • 参数名区分大小写
  • 验证调用返回或支付中心主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验

第二步： 在stringA最后拼接上key[即 StringA +"&key=" + 密钥 ] 得到stringSignTemp字符串，并对stringSignTemp进行MD5运算( 取32位小写)，得到sign值。

如请求支付系统参数如下(下面数据仅仅示例数据格式，签名并不正确)：

Map signMap = new HashMap<>();
signMap.put("mchId", "zvyegj1mftgw75hf");
signMap.put("mchOrderNo", "1723867817122");
signMap.put("mchMoney", 1);
signMap.put("mchPayType", 1001);
signMap.put("mchNotifyUrl", "http://192.168.0.90:8092/test/notify);
signMap.put("mchReqTime", 1723867809960);

待签名值

mchId=zvyegj1mftgw75hf&mchMoney=1&mchNotifyUrl=http://192.168.0.90:8092/test/notify&mchOrderNo=1723867817122&mchPayType=1001&mchReqTime=1723867809960&key=n601dya8lv8oja9hqjul5jurn43fgdre

签名结果

b614b991bcb6ba8d32384b5f00d3eee6

最终请求支付系统参数

mchId=zvyegj1mftgw75hf&mchMoney=1&mchNotifyUrl=http://192.168.0.90:8092/test/notify&mchOrderNo=1723867817122&mchPayType=1001&mchReqTime=1723867809960&mchSign=b614b991bcb6ba8d32384b5f00d3eee6

支付类型编码

支付类型 编码
tb代付 1001
支付宝金条 1000
支付宝AA 1002
微信银联扫码 1003
闲鱼直付 1004
支付宝收款 1005
支付宝放心充 1006
支付宝uid手动 1007
淘宝直付 1008
支付宝小荷包 1009
支付宝LS 1010
淘宝游戏 1011
抖音 1018
虚拟货币 1013
支付宝当面付 1014
支付宝当面付养号 1015
支付宝当面付-分账 1016
支付宝当面付-分账-养号 1017
支付宝手机网站 1019
支付宝手机网站-养号 1020
支付宝手机网站-分账 1021
支付宝手机网站-分账-养号 1022
完美 1023
支付宝订单码 1024
支付宝订单码-养号 1025
售货机 1027
礼品卡 1028
现金红包 1029
抖音转账 1030
交易猫 1035
云创 1036
中吉 1037
京东 1038
支付宝App 1039
直付通第三方 1040
盛马售货机 1041
代付2.0 1043
支付宝App-养号 1044
巨量 1045
京东代付码 1046
微信手动 1047
dyy 1048
微信协议 1049
支付宝收款单 1050
瀑布 1051
微店手动 1052
微店自动 1053
经营收款单 1054
微信群红包手动 1055
经营收款单手动 1056
直付通 1057
支付宝小程序 1058
字店通 1059
瀑布圈子-自动产码 1060
支付宝小程序-养号模式 1061
顺卡 1062
新TB代付2.0 1063
赞付 1064
汇花 1065
众驰 1066
xxy 1067
lx 1068
洞窝 1069
金条2.0 1070
tbqhb 1071
支付宝金条小额 1075
支付宝金条混合 1076
支付宝金条混合小额 1077
自助侠 1079
现金红包-新 1080
虾米 1081
微信协议新 1083
拼多多代付 1084
洞窝协议 1085
多点 1086
微信支付 1087
惠云 1088
大润发 1101

下单接口

商户业务系统通过统一下单接口发起支付收款订单，支付平台会根据商户配置的支付通道路由支付通道完成支付下单。 支付平台根据不同的支付方式返回对应的支付参数，业务系统使用支付参数发起收款。

接口说明

  • 下单接口地址：(最新域名请看具体的对接信息)

  • 提交类型为POST：Content-Type: application/json

  • 请提交json数据，不要提交表单数据!

  • 请提交json数据，不要提交表单数据!

  • 请提交json数据，不要提交表单数据!

请求参数

字段名 参数名 类型 是否必填 最大长度 描述 示例
商户号 mchId String 是 16 商户号 zvyegj1mftgwfeuu
下单金额 mchMoney String/Integer 是 下单金额(支持小数点两位） 100
订单号 mchOrderNo String 是 50 订单号 no1697455590863
支付类型编号 mchPayType Integer 是 支付类型参数 1001
异步回调地址 mchNotifyUrl String 是 255 异步回调地址 https://api.test.com/notify
请求时间 mchReqTime Long 是 13 13位的时间戳 1622016572190
签名 mchSign String 是 32 签名,根据签名方法生成的小写32位字符串 83ff788d0ecd5f479c0d703183910146
扩展参数 mchAttach String 否 255 扩展参数
用户ip userIp String 否 255 用户ip，用来控制下单次数 127.0.0.1

请求示例数据

{
    "mchId": "zvyegj1mftgw75hf",
    "mchMoney": 1,
    "mchOrderNo": "1723867817122",
    "mchNotifyUrl": "http://192.168.0.90:8092/test/notify",
    "mchPayType": 1001,
    "mchReqTime":1723867809960
    "mchSign": "b614b991bcb6ba8d32384b5f00d3eee6"
}

返回参数

字段名 参数名 类型 是否必填 描述 示例
响应代码 code Integer 是 响应代码(0是成功，-1是失败) 0
提示消息 msg String 是 提示消息 创建订单成功
数据 data String 否 json数据，里面的参数(payUrl)为用户付款URL，如果是大润发通道则返回app拉起的字符串 {"payUrl": "http://api.test.com/alipay?no=2023071488475886"}

返回示例数据

//下单不成功示例：
{
    "msg": "商户不存在",
    "code": -1
}
//下单成功
{
    "msg": "创建订单成功",
    "code": 0,
    "data":{
        "payUrl":"http://api.test.com/alipay?no=2023071488475886"
    }
}

支付完成通知回调

当订单支付成功时，支付网关会向商户系统发起回调通知。如果商户系统没有正确返回，支付网关会延迟再次通知。

接口说明

请求URL：该链接是通过统一下单接口提交的参数mchNotifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。

请求方式：POST

请求类型：application/json

通知参数

字段名 参数名 类型 是否必填 最大长度 描述 示例
商户订单号 mchOrderNo String 是 50 商户订单号 20240303100000868
支付类型编码 mchPayType Integer 是 16 支付类型编码 1001
金额 mchMoney Integer 是 13 付款金额，单位元 1000
扩展参数 attach String 否 255 扩展参数 备注
支付状态 state String 是 32 只有大写OOK才是支付成功，其他为未支付 OOK
签名 mchSign String 是 32 签名,根据签名方法生成的小写32位字符串 83ff788d0ecd5f479c0d703183910146

注意

可能会有state的值为WAIT的情况，四方要判断好state的值为OOK才算订单完成

返回结果

业务系统处理后同步返回给支付中心，返回小写字符串 ok 则表示成功，其他为未成功，支付中心会再次通知业务系统。（通知频率为0, 30, 60, 180, 600,单位：秒）

  • 注意：返回的字符串区分大小写，字符串前后不能有空格和换行符。

订单查询接口

商户提交订单号等参数获取订单状态，查询是否支付成功等信息

接口说明

  • 查单接口地址：(最新域名请看具体的对接信息)

  • 提交类型为POST：Content-Type: application/json

请求参数

字段名 参数名 类型 是否必填 最大长度 描述 示例
商户号 mchId String 是 16 商户号 zvyegj1mftgwfeuu
订单号 mchOrderNo String 是 50 订单号 no1697455590863
请求时间 mchReqTime Long 是 13 13位的时间戳 1622016572190
签名 mchSign String 是 32 签名,根据签名方法生成的小写32位字符串 83ff788d0ecd5f479c0d703183910146

请求示例数据

{
    
    "mchId":"zvyegj1mftgwfeuu",
    "mchOrderNo":"no1697455590863",
    "mchReqTime":"1622016572190",
    "mchSign":"83ff788d0ecd5f479c0d703183910146"
}

返回参数

字段名 参数名 类型 是否必填 描述 示例
响应代码 code Integer 是 响应代码(0是成功，-1是失败) 0
提示消息 msg String 是 提示消息 创建订单成功
数据 data String 否 json数据

返回示例数据

//查询不成功示例：
{
    "msg": "订单不存在",
    "code": -1
}
//查询成功
{
    "msg": "操作成功",
    "code": 0,
    "data": {
        "mchOrderNo": "1704955620530",//商户订单号
        "platOrderNo": "LD2024011114470013945704",//平台订单号
        "createdAt": "2024-01-11 14:47:00",//平台创建订单时间
        "payTime": null,//支付时间
        "state": "NOMATCH",//订单状态,详细见下方说明
        "amount": 1,//订单金额
        "payAmount": 0.00//用户实际付款金额
    }
}

订单状态字段(state)说明

  • OOK 已支付，订单完成可以回调
  • NOMATCH 未支付，没有可用的收款码
  • WAIT 未支付，等待支付
  • TIMEOUT 未支付，订单超时
  • ...可能还有其他未支付类型

注意⚠️： 仅OOK时才是支付成功，其余类型均为未支付

Back to top