零付通聚合支付系统联调文档2.0版本
9个月前更新18709

引言以及开发规范



编写目的
本文档针对于使用零付通聚合支付接口文档的客户，方便各位商家快速接入我司聚合支付接口。系统支持银联、支付宝、微信端开发。
1.2 开发规范
1、接口采用HTTP或者HTTPS传输协议，采用UTF-8编码。用POST方式提交数据。
2、字段命名必须字母加下划线方式，所有字段命名全部小写。
3、接口中各字段限制标识是Y时必填，N非必填

安全要求

安全要求
1、我公司支持使用MD5（不推荐）、SHA1（不推荐）、RSA2、国密签名算法
2、将数据内的非空参数值的参数按照参数名ASCII码从小到大排序（字典序）;
3、假设数据为空，则此字段不加入签名。
4、传送的res_body字段请加入签名前做排序处理（ASCII码从小到大排序（字典序））
5、参数值 sign_type 需加入签名中。
6、res_body 应为String数据，如php方式为json_encode
7、所有参数加入签名时为原报文内容（不剔除空格及特殊字符）进行签名

交互方式：
统一为 POST：application/x-www-form-urlencoded;charset=utf-8
参考资料
MD5、SHA1签名算法：
1、将发送或接收到的数据内的非空参数值的参数按照参数名ASCII码从小到大排序，（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA;
2、假设您的数据为key1=value1&key2=value2，那么拼接参数最后拼接您的秘钥，如key1=&key2=value2F5S1AD0G54AGGADE
3、传送的MD5、SHA1加密后SIGN参数为小写请注意；签名内容非大写

RSA2(SHA256)签名算法（推荐）：
1、使用支付宝工具生成RSA2#PKCS8密钥，上传公钥至商户后台。
2、签名时将数组转为JSON格式（例如php为 json_encode ）
3、使用RSA2算法签名（请签名原字段不去除空格及特殊字符，可参考Demo）
4、验签使用我司公钥进行，PHP Demo有完整示例签名（其他语言联系我司获取公钥）

若有收获，就点个赞吧

支付接口

🎄统一下单接口

1、修订记录

版本号日期说明作者
2.0.02023年5月3日2.0版本初稿（初定版）张学林
2.2.02023年7月11日全新API接口（第二版）张学林
2.3.02023年8月23日支持QQ钱包支付以及更新兼容JAVA签名张学林
2.6.02023年9月8日全新前端UI便于客户操作张学林

2、网关地址

环境HTTPS请求地址
正式环境https://apiv2.0fi.cn/api/network/unified

3、请求参数

3.1、公共参数说明
参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
res_bodyStringY业务参数集合(JSON字符串)
serviceString(255)Y网关接口名（固定值：gateway.unified.pay）
versionString(255)N固定值 2.0 不传可能有兼容性问题
sign_typeString(255)Y签名方式，固定值RSA2
signStringY签名

注 : 2.0 版本以上不需要做任何的转义和反斜杠与编码

3.2、业务参数
参数必填参数说明
sub_mch_id二选一指定子商户交易（代理商必传）
sub_type以上如需系统轮训时传：”SYSTEM“ 大写（不含引号空格）
如果您为代理商，请传输 sub_mch_id 不支持自动轮训此功能
channel_typeY支付通道（参考支付通道枚举）
total_feeY支付金额，单位为元，取两位小数如：0.01
pay_nameY订单商品名称（上送微信支付及支付宝支付订单中）
pay_bodyY订单交易描述，保留我司不上送
notify_urlY异步回调通知地址
out_trade_noY商户订单号（不建议重复）
user_ipY付款用户IP地址，如 152.33.40.28
server_urlY商家网站地址（实际购物的域名URL）
appidN小程序支付必传，微信小程序APPID
openidN小程序支付必传，微信用户OPENID
3.3、接口公共返回参数
参数类型(字节长度）必须参数说明
rsp_codeString(255)Y响应状态码，成功 0000
rsp_msgStringY响应描述
request_arrayArrayN响应成功的附加参数
3.4、接口响应附加参数
参数类型(字节长度）必须参数说明
pay_urlStringN非小程序支付时返回
wechat_redirectStringN小程序唤醒地址（H5浏览器可唤醒）
约束：使用系统小程序，不传appid
wechat_appidStringN小程序支付时返回
wechat_pay_infoArrayN指定小程序时返回，微信支付参数
system_order_idStringY系统订单流水号
3.5、接口返回示例
{
  "rsp_code":"0000",
  "rsp_msg":"success",
  "request_array":{
    "pay_url":"https://order.payment.com/Network/jump_pay/por/2022102219051044955958139/",
    "system_order_id":"20221022190510449559581399"
  }
}

4、支付通道枚举

枚举名称枚举说明
ALIPAY支付宝扫码/APP支付
WECHAT_MP微信扫码支付
WECHT_H5微信小程序支付/H5支付通用
WECHAT_APP微信APP支付（作废，请使用小程序支付）
UNIONPAY_QR银联扫码支付（云闪付）
UNIONPAY中国银联（快捷支付）
QQPAYQQ钱包支付（扫码支付/H5）

🙋‍♂️异步通知回调接口

1、通知参数（无请求头）

参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
out_trade_noStringY商户订单编号
system_order_idStringY系统订单编号（系统流水号）
pay_external_idStringY银行订单号（支付宝微信商户单号）
signStringY签名（签名方式同下单时一致）

2、收到通知返回要求

收到通知后需要返回大写>收到通知后需要返回大写 SUCCESS
如未返回，我公司将在1小时内随机时间重复回调10次。

另外，如回调失败我公司将按照如下固定频率进行回调，最多回调15次(自2023/04/20日起)
频率为：首次回调失败后 5s / 第二次 30s / 第三次 60s / 第四次 600s(10分钟) / 第五次与后续 3600s(1小时)

📖订单支付状态查询

1、修订记录

版本号日期说明作者
2.0.02023年 5 月 3 日初稿（初定版）张学林
2.0.12023年08月18日更新V2.0兼容性张学林

2、网关地址

环境HTTPS请求地址
正式环境https://apiv2.0fi.cn.cn/api/network/unified

3、请求参数

3.1、公共参数说明

参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
res_bodyStringY业务参数集合(JSON字符串)
serviceString(255)Y网关接口名（固定值：gateway.unified.pay）
versionString(255)N固定值 2.0 不传可能有兼容性问题
sign_typeString(255)Y签名方式，固定值RSA2
signStringY签名

3.2、业务参数

参数必填参数说明
sub_mch_id二选一指定子商户交易（代理商必传）
sub_type以上如需系统轮训时传：”SYSTEM“ 大写（不含引号空格）
如果您为代理商，请传输 sub_mch_id 不支持自动轮训此功能
channel_typeY支付通道（参考支付通道枚举）
total_feeY支付金额，单位为元，取两位小数如：0.01
pay_nameY订单商品名称（上送微信支付及支付宝支付订单中）
pay_bodyY订单交易描述，保留我司不上送
notify_urlY异步回调通知地址
out_trade_noY商户订单号（不建议重复）
user_ipY付款用户IP地址，如 152.33.40.28
server_urlY商家网站地址（实际购物的域名URL）
appidN小程序支付必传，微信小程序APPID
openidN小程序支付必传，微信用户OPENID

3.3、接口公共返回参数

参数类型(字节长度）必须参数说明
rsp_codeString(255)Y响应状态码，成功 0000
rsp_msgStringY响应描述
request_arrayArrayN响应成功的附加参数

3.4、接口响应附加参数

参数类型(字节长度）必须参数说明
pay_urlStringN非小程序支付时返回
wechat_redirectStringN小程序唤醒地址（H5浏览器可唤醒）
约束：使用系统小程序，不传appid
wechat_appidStringN小程序支付时返回
wechat_pay_infoArrayN指定小程序时返回，微信支付参数
system_order_idStringY系统订单流水号

3.5、接口返回示例

{
  "rsp_code":"0000",
  "rsp_msg":"success",
  "request_array":{
    "pay_url":"https://order.payment.com/Network/jump_pay/por/2022102219051044955958139/",
    "system_order_id":"20221022190510449559581399"
  }
}

4、支付通道枚举

枚举名称枚举说明
0创建成功，等待付款
1订单支付成功

⚙️订单纠纷退款

1、修订记录

版本号日期说明作者
2.0.02023年 5 月 3 日初稿（初定版）张学林
2.0.12023年08月18日更新V2.0兼容性张学林

2、网关地址

环境HTTPS请求地址
正式环境https://apiv2.0fi.cn.cn/api/network/unified

3、请求参数

3.1、公共参数说明

参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
res_bodyStringY业务参数集合(JSON字符串)
serviceString(255)Y网关接口名（固定值：gateway.unified.pay）
versionString(255)N固定值 2.0 不传可能有兼容性问题
sign_typeString(255)Y签名方式，固定值RSA2
signStringY签名

3.2、业务参数

参数必填参数说明
sub_mch_id二选一指定子商户交易（代理商必传）
sub_type以上如需系统轮训时传：”SYSTEM“ 大写（不含引号空格）
如果您为代理商，请传输 sub_mch_id 不支持自动轮训此功能
channel_typeY支付通道（参考支付通道枚举）
total_feeY支付金额，单位为元，取两位小数如：0.01
pay_nameY订单商品名称（上送微信支付及支付宝支付订单中）
pay_bodyY订单交易描述，保留我司不上送
notify_urlY异步回调通知地址
out_trade_noY商户订单号（不建议重复）
user_ipY付款用户IP地址，如 152.33.40.28
server_urlY商家网站地址（实际购物的域名URL）
appidN小程序支付必传，微信小程序APPID
openidN小程序支付必传，微信用户OPENID

3.3、接口公共返回参数

参数类型(字节长度）必须参数说明
rsp_codeString(255)Y响应状态码，成功 0000
rsp_msgStringY响应描述
request_arrayArrayN响应成功的附加参数

3.4、接口响应附加参数

参数类型(字节长度）必须参数说明
pay_urlStringN非小程序支付时返回
wechat_redirectStringN小程序唤醒地址（H5浏览器可唤醒）
约束：使用系统小程序，不传appid
wechat_appidStringN小程序支付时返回
wechat_pay_infoArrayN指定小程序时返回，微信支付参数
system_order_idStringY系统订单流水号

3.5、接口返回示例

{
  "rsp_code":"0000",
  "rsp_msg":"success",
  "request_array":[]
}

3.6、注意事项

接口退款以 rsp_code 状态为准，request_array 无返回参数

4、支付通道枚举

枚举名称枚举说明
0创建成功，等待付款
1订单支付成功

场景说明


1、微信正扫（微信公众号/小程序） 通过微信公众号封装微信静态/动态收款二维码,适用于PC网站、实体店单品或订单、媒体广告支付等场景
用户扫描商户展示在各种场景的二维码进行支付。
2、微信内支付（微信公众号/小程序）
商户已有H5商城网站或微信小程序，用户通过微信消息或扫描二维码在微信内打开网页或微信小程序时，可以调用微信支付完成下单购买的流程。
3、微信外H5支付（微信小程序）
可以通过微信urlscheme从外部浏览器拉起微信小程序进行支付，适用于服务商开发自己的手机H5收银台。
4、微信app支付（微信小程序）
通过微信SDK拉起微信小程序进行支付，适用于在移动端APP中集成微信支付功能的场景。商户APP调用微信提供的SDK调用微信支付模块，商户APP会跳转到微信中完成支付，最后展示支付结果。
5、支付宝聚合支付（支付宝扫码/APP）

微信支付步骤

步骤一：根据公众号H5页面url生成收款二维码（静态聚合码需要先展示收银台，让用户输入金额）；
步骤二：用户使用微信“扫一扫”扫描二维码后，获取商品支付信息，引导用户完成支付；
步骤三：用户确认支付，输入支付密码；
步骤四：支付完成后会提示用户支付成功，商户后台得到支付成功的通知，然后进行发货处理。

API进件接口

获取渠道拓展字段

1、修订记录

版本号日期说明作者
1.0.02023/09/09初稿（初定版）学林

2、网关地址

环境HTTPS请求地址
正式环境https://merchant.0fi.cn

3、请求参数


3.1、公共参数说明

参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
res_bodyStringY业务参数集合(JSON字符串)
serviceString(255)Y网关接口名（固定值：supplement ）
versionString(255)Y固定值 2.0
sign_typeString(255)Y签名方式，固定 RSA2
signStringY签名
  • 注 : 2.0 版本以上不需要做任何的转义和反斜杠与编码


3.2、业务参数

参数必填参数说明
idY渠道ID，联系我司运营获取

3.3、接口公共返回参数

参数类型(字节长度）必须参数说明
rsp_codeString(255)Y响应状态码，成功 0000
rsp_msgStringY响应描述
request_arrayArrayN响应成功的附加参数

3.4、接口响应附加参数

参数类型(字节长度）必须参数说明
dataStringY拓展数据

商户进件

1、修订记录

版本号日期说明作者
1.0.02023/09/09初稿（初定版）学林

2、网关地址

环境HTTPS请求地址
正式环境https://merchant.0fi.cn

3、请求参数

3.1、公共参数说明
参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
res_bodyStringY业务参数集合(JSON字符串)
serviceString(255)Y网关接口名（固定值：agent.submch.register ）
versionString(255)Y固定值 2.0
sign_typeString(255)Y签名方式，固定 RSA2
signStringY签名

注 : 2.0 版本以上不需要做任何的转义和反斜杠与编码

3.2、业务参数
参数必填参数说明
channel_idY渠道ID，联系我司运营获取
type_idY渠道ID，联系我司运营获取
typeY渠道ID，联系我司运营获取
r_typeY报备类型；1:支付宝，2:微信支付，3:支付宝+微信支付
abbreviationY小票名称（支付宝微信银联简称）
phoneY法人手机号码
qy_countyY企业注册区县 (如天心区、长沙县) 仅需填写县或区即可；不需要填写其他参数，否则无法识别注册地址
bank_typeY清分类型（也称结算类型）1:对私结算，2:对公结算，3:非法人结算
bank_countyY银行卡或对公户开户城市所在区县名称；与qy_county相似，填写区或县名称
bank_nameY银行名称 (xxxxx 银行股份有限公司)
bank_zhihangY银行支行(xxx 银行股份有限公司 xxx 支行)
account_idY法人结算银行卡号（对公填写公司卡号）
bank_idY银行开户联行号
sfz_imgzY法人身份证正面
sfz_imgfY法人身份证反面
qy_imgY营业执照照片URL
account_imgY银行卡或开户许可证照片
shop_mtY门头照片
shop_njY内景照片
supplementY获取渠道拓展字段
ipYip

3.3、接口公共返回参数

参数类型(字节长度）必须参数说明
rsp_codeString(255)Y响应状态码，成功 0000
rsp_msgStringY响应描述
request_arrayArrayN响应成功的附加参数

3.4、接口响应附加参数

参数类型(字节长度）必须参数说明
sub_mch_idStringY子商户编号

3.5、接口返回示例

{
  "rsp_code":"0000",
  "rsp_msg":"success",
  "request_array":[
    "sub_mch_id": "6015667113210"
  ]
}

子商户入网状态查询

1、修订记录

版本号日期说明作者
1.0.02022/10/22初稿（初定版）秋

2、网关地址

环境HTTPS请求地址
正式环境https://merchant.0fi.cn

3、请求参数

3.1、公共参数说明

参数类型(字节长度）必填参数说明
open_useridString(255)Y由我司分配的唯一用户编号（代理通用）
res_bodyStringY业务参数集合(JSON字符串)
serviceString(255)Y网关接口名（Service）固定值 uni.mer.query
sign_typeString(255)Y签名方式，固定值RSA2
signStringY签名

3.2、业务参数

参数必填参数说明
sub_mch_idY子商户编号

3.3、接口公共返回参数

参数类型(字节长度）必须参数说明
rsp_codeString(255)Y响应状态码，成功 0000
rsp_msgStringY响应描述
request_arrayArrayN响应成功的附加参数

3.4、接口响应附加参数

参数类型(字节长度）必须参数说明
statusStringY入网商户审核状态0:待系统处理中，1:审核已通过，2:审核失败，3:系统处理中，500:待风控初审。其他代码则表示正在审核中
error_msgStringNstatus为2时返回，审核失败原因
infoArrayN入网信息数据（中文数组，此处不详细说明）
© 版权声明
文章版权归作者所有，未经允许请勿转载。
评论 抢沙发
头像
欢迎您留下宝贵的见解！
提交
头像

昵称

取消
昵称

请填写用户信息：

  • 昵称(必填)
  • 邮箱(必填)
表情
[aoman][baiyan][bishi][bizui][cahan][ciya][dabing][daku][deyi][doge][fadai][fanu][fendou][ganga][guzhang][haixiu][hanxiao][zuohengheng][zhuakuang][zhouma][zhemo][zhayanjian][zaijian][yun][youhengheng][yiwen][yinxian][xu][xieyanxiao][xiaoku][xiaojiujie][xia][wunai][wozuimei][weixiao][weiqu][tuosai][tu][touxiao][tiaopi][shui][se][saorao][qiudale][qinqin][qiaoda][piezui][penxue][nanguo][liulei][liuhan][lenghan][leiben][kun][kuaikule][ku][koubi][kelian][keai][jingya][jingxi][jingkong][jie][huaixiao][haqian][aini][OK][qiang][quantou][shengli][woshou][gouyin][baoquan][aixin][bangbangtang][xiaoyanger][xigua][hexie][pijiu][lanqiu][juhua][hecai][haobang][caidao][baojin][chi][dan][kulou][shuai][shouqiang][yangtuo][youling]
代码

请输入代码：

确认
图片

    暂无评论内容

搜索产品教程
产品教程
搜索产品教程
主题文档