产业支付

文档编号	LC-DEP-240315001	保密等级	普通
作者	郝龙潘、陈江勇	最后修改日期	2024-03-20
审核人	林道银	最后审批日期	2024-03-25
批准人	林喆	最后批准日期	2024-03-25

修订记录

日期	修订说明	修订人
2024-04-15	新增产业支付预下单，查询，退款，退款查询，通知回调等api	郝龙潘
2024-05-25	增加产业支付小程序支付方式	陈江勇
2024-10-12	4.2产业支付小程序支付接口增加微信B2b支付方式。pay_type=200	艾青松

一、系统接入对象

具有研发能力的经营服务商或者系统商
具有研发能力的商户

二、协议规则

调用API必须遵循以下规则：

1.1传输方式

为保证交易安全性，采用HTTPS传输,Content-type均为application/json

1.2提交方式

采用POST方法提交

1.3提交方式

提交和返回数据都为JSON格式

1.4字符编码

统一采用UTF-8字符编码

1.5判断逻辑

先判断协议字段返回，再判断业务返回，最后判断交易状态

1.6签名算法

MD5

1.7支付流图

三、签名算法

接口中每一个字段(key_sign字段除外),以字典顺序排序之后,按照key1=value1&key2=value2.....&access_token="令牌"的顺序,进行拼接。对得到的字符串进行MD5签名/验签；

备注：无值null不参与签名，赋值的空字符串参与签名；

示例请求参数：
{
"pay_ver": "201",
"pay_type": "020",
"service_id": "018",
"merchant_no": "839305812000286",
"terminal_id": "30616969",
"terminal_trace": "201811231154130000",
"terminal_time": "20181123115413",
"user_id": "2088002405630000",
"total_fee": "1",
"order_body": "",
"attach": "",
"payer_acct_name": "某某科技有限公司",
"key_sign": ""
}
对应签名串：
string1="attach=&merchant_no=839305812000286&order_body=&pay_type=020&pay_ver=201&payer_acct_name=***科技有限公司&service_id=018&terminal_id=30616969&terminal_time=20181123115413&

terminal_trace=201811231154130000&total_fee=1&user_id=2088002405630000" ；

待签名字符串: string2=string1+"&access_token=xxxxxxxx";

通过摘要算法取得签名字符串: key_sign=md5(string2)

四、支付相关API

4.1产业支付预下单

该接口返回的redirect_url字段地址，用于下方场景内执行地址跳转

使用场景：

场景一：微信和支付宝内的H5页面或者公众号场景。

场景二：app支付场景。

app内选微信场景下，app内先调用该接口，用户点击该接口返回的链接，授权同意跳转后，可直接跳转到微信的付款页面；
app内选支付宝场景下，根据开发能力，可选择以下两种方式：
1. 若app可开发跳转到支付宝页面的能力（如app跳支付宝小程序），可在支付宝页面内静默获取用户userid后，再调用此接口。
2. 若app无法实现跳转到支付宝，并获取用户userid的能力，可使用扫呗已封装好的4.12WAP收银台，来完成app产业支付的能力，需在app内使用支付宝热链（alipays://platformapi/startapp?saId=10000007&qrcode=4.12WAP收银台接口返回的收银台链接）跳转到支付宝。

URL：/pay/open/pretransfer
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口业务版本号，可用值201
service_id	String	3	Y	接口类型，当前类型 018
pay_type	String	3	Y	支付方式： `010` 微企付 `020` 支付宝商转
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号，多次请求时不可使用同一个值
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss ，全局统一时间格式
total_fee	String	12	Y	金额，单位分
order_confirm	String	1	N	是否需要订单确认,传0：不需要确认订单。传1：需要确认订单，即需要确认后才会进行清算。不传默认不需要确认订单,pay_type=020时可用。
payer_acct_name	String	100	O	限制付款人账户名称，传入则校验实际付款人和传入的一致性（ pay_type=020时，若user_id传支付宝登录账号，此字段必传）
user_id	String	32	O	支付宝付款人标识, pay_type=020时必传。模式1：传支付宝登录账号时（支持邮箱和手机号格式），配合payer_acct_name字段，可指定人员支付。模式2：传支付宝user_id。适用于用户在支付宝内打开H5或者公众号后，获取用户user_id后发起支付。支付宝获取用户userid：https://opendocs.alipay.com/fw/api/105942
scene_type	String	32	O	支付场景 APP：APP场景
timeout_express	String	4	N	订单交易关闭时间，默认5分钟，需在规定时间内完成支付，超时支付的银行会进行退回。上限：360min
order_body	String	128	N	订单描述（官方账单里显示为商品名称），禁止使用+，空格，/，?，%，#，&，=这几类特殊符号
notify_url	String	256	N	外部系统通知地址。4.5产业支付回调通知
attach	String	128	N	附加数据，原样返回
key_sign	String	32	Y	签名字符串,拼装所有非空参数(字典序)+令牌，UTF-8编码，32位md5加密转换。签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：01成功，02失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“预支付请求成功”，“预支付请求失败”等
key_sign	String	32	Y	签名串签名测试页
result_code	String	2	N	业务结果：01成功，02失败
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
terminal_trace	String	32	N	终端流水号，商户系统的订单号，系统原样返回
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式，系统原样返回
total_fee	String	12	N	金额，单位分
order_status	String	4	N	状态:0-未转账 1-成功 2-失败 3-支付中 4-撤销 5-退款成功 6-退款失败 7-超时 8-退款中
order_send_time	String	14	N	订单发送时间，yyyyMMddHHmmss
out_trade_no	String	32	N	平台唯一订单号
channel_order_no	String	64	N	渠道订单号
attach	String	128	N	附加数据,原样返回
redirect_url	String	1024	N	微信企业付和支付宝企业付返回链接路径，可重定向

4.2产业支付小程序支付

http请求

URL：/pay/open/minipretransfer
Method：POST

微企付支付场景说明：取接口返回的mini_program参数，用于调用微信小程序跳转功能。

jump() {//按钮点击跳转方法，可自定义方法名
  wx.navigateToMiniProgram({
    appId: '接口返回的mp_appid',
    path: '接口返回的mp_path地址',
    envVersion: '接口返回的mp_version值',
    success(res) {
      // 打开成功，可修改成自己的业务逻辑
    }
  })
}

官方参考地址：https://developers.weixin.qq.com/miniprogram/dev/api/navigate/wx.navigateToMiniProgram.html

支付宝场景说明：取接口返回的mini_program参数，用于调用支付宝的小程序跳转功能。

因用户第一次在商户使用支付宝的产业付时，需要进行签约授权，后续在商户再次支付时不用在签约，可直接进行付款，故此接口会根据用户是否是第一次支付而返回不同的参数。当path_type字段返回是1时，代表需要用户进行授权，当path_type字段返回是2时，代表需要跳转到支付页面。具体操作方式如下：

当path_type字段返回1时，操作方式：打开mp_path字段返回的授权链接

1、引入支付宝小程序基础库

2、支付宝开放平台控制台 开发设置 >openURL 配置，申请添加https://ur.alipay.com白名单

3、小程序内编写下方代码进行授权链接跳转

my.ap.openURL({
  url: '接口返回的mp_path字段地址', //url地址
  success: (res) => {
    console.log('openURL success', res)
  },
  fail: (err) => {
    console.log('openURL success', err)
  }
});

官方参考地址：https://opendocs.alipay.com/mini/04iy2y

当path_type字段返回2时，操作方式：跳转到mp_path字段返回的小程序地址

jump() {//按钮点击跳转方法，可自定义方法名
    my.navigateToMiniProgram({
      appId:'接口返回的mp_appid',  //固定值，请勿修改
      path:'接口返回的mp_path地址',
      success: (res) => {
        console.log(JSON.stringify(res))//可修改成自己的业务逻辑
      },
     fail: (res) => {
        console.log(JSON.stringify(res))//可修改成自己的业务逻辑
      }
    });
  },

官方参考地址：https://opendocs.alipay.com/mini/api/yz6gnx

微信B2b支付场景说明：取接口返回的mini_program参数，用于调用微信官方接口。

调用微信官方接口：wx.requestCommonPayment(Object object)

官方接口文档：https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestCommonPayment.html