支付2.0接口

更新日志：

日期	章节	内容
2022-07-11	所有章节	所有章节增加java sdk使用说明
2022-07-12	4.1付款码支付 4.4小程序支付接口 4.5支付查询 4.10回调通知	pay_ver增加202版本，该版本支持支付成功后返回优惠字段
2022-07-12	4.3公众号支付接口 4.4小程序支付接口	补充接口文字描述
2022-07-14	一、接入必看二、接入指南	增加接入必看章节，优化 2.4签名算法文字说明增加2.5支付流图章节
2022-07-29	4.1付款码支付 4.2扫码支付（预支付） 4.3公众号支付接口 4.4小程序支付接口 4.14刷脸支付	新增terminal_ip字段，实时交易终端IP(银联侧风控主要依据，请真实填写)
2025-06-26	4.1付款码支付（B扫C） 4.3公众号支付接口 4.4小程序支付接口 4.16获取服务商公众号下openid	新增090抖音支付

一、接入必看

请仔细阅读第二章接入指南，尤其是2.3判断逻辑、2.4签名算法

测试地址：http://test.lcsw.cn:8045/lcsw+接口url 或 http://test2.lcsw.cn:8117/lcsw +接口url

二、接入指南

2.1协议规则

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

提交方式：采用POST方法提交

2.2数据格式

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

统一采用UTF-8字符编码

2.3判断逻辑

1.先判断协议字段（return_code）返回，再判断业务（result_code）返回，最后判断交易状态。

2.小程序和公众号支付时，当return_code和result_code两个值都返回01时，才能取值去请求微信支付。否则会由于取不到参数，微信支付报缺少参数错误。

2.4签名算法

注意：
1.使用java SDK对接的接口，不需要做签名，SDK会自动处理。
2.httpclient方式发起的接口请求，请求和接收数据均需要校验签名。

拼接串说明：

接口中每一个字段(key_sign字段除外),以字典顺序(字母顺序)排序之后,按照a=value1&attach=&b=value2.....&z=value3的顺序进行拼接。对得到的字符串进行MD5签名/验签（赋值的空字符串也参与签名）。

示例请求参数：

{
  "pay_ver": "201",
  "pay_type": "010",
  "service_id": "010",
  "merchant_no": "839305812000286",
  "terminal_id": "30616969",
  "device_no":"202011261843460000",
  "terminal_trace": "201811231154130000",
  "terminal_time": "20181123115413",
  "auth_no": "xxxxxxxx",
  "total_fee": "1",
  "order_body": "",
  "attach": "",
  "goods_detail": "",
  "key_sign": ""
}

对应签名串：

string1="attach=&auth_no=xxxxxxxx&device_no=202011261843460000&goods_detail=&merchant_no=839305812000286&order_body=&pay_type=010&pay_ver=201&service_id=010&terminal_id=30616969&terminal_time=20181123115413&terminal_trace=201811231154130000&total_fee=1".

待签名字符串:

string2=string1+"&access_token=xxxxxxxx";

通过MD5取得签名值:

key_sign=md5(string2);

2.5支付流图

三、支付接口SDK

3.1 SDK下载

❗特殊说明：

目前只提供java语言的SDK，其它开发语言请使用API请求的方式调用api接口，http请求方式不受开发语言限制，可跨平台调用

更新时间	java sdk文件	版本说明
2022-03-30	java-sdk-1.1.4	部分支付接口新增par_ver为202时返回优惠信息字段
2022-08-10	java-sdk-1.1.5	部分支付接口新增terminal_ip字段
2022-10-31	java-sdk-1.1.6	增加退款申请和退款查询接口中pay_ver为202时返回的几个参数
2022-11-18	java-sdk-1.1.7	优化网络超时时，result_code返回支付中
2022-12-22	java-sdk-1.1.8	公众号预支付增加云闪付返回字段
2023-12-15	java-sdk-1.1.9	优化网络请求，增加4.17付款码查询openid接口
2024-07-09	java-sdk-1.2.0	4.12wap收银台接口增加传递产业支付相关字段
2025-04-14	java-sdk-1.2.1	4.4小程序支付接口、4.14聚合码接口，增加timeout_express字段。

3.1.1 SDK引入方式参考

方式一：IDEA或者Eclipse引入本地jar包的方式。具体操作可网上搜索对应开发工具添加jar包的步骤。
方式二：使用maven的方式，将jar包安装到本地仓库后，通过pom引入，具体步骤和maven命令请自行网上搜寻。

//请自行根据电脑系统类型修改-Dfile指定的jar包所在路径格式，注意将命令中的-Dversion指定的jar包版本换成所下载的版本
mvn install:install-file -Dfile=D:\saobei-open-sdk-1.2.1.jar -DgroupId=com.lcsw.opensdk -DartifactId=saobei-open-sdk -Dversion=1.2.1 -Dpackaging=jar
//安装到本地仓库后，在pom中添加如下引入，注意version修改成所安装的版本号
<dependency>
    <groupId>com.lcsw.opensdk</groupId>
    <artifactId>saobei-open-sdk</artifactId>
    <version>1.2.1</version>
</dependency>

方式三：在pom.xml文件中，你可以使用dependency标签的systemPath属性来指定本地JAR包的路径，maven具体操作可自行网上搜索。

//version注意换成所使用的版本，systemPath换成jar所在目录
<dependencies>
  <dependency>
    <groupId>com.lcsw.opensdk</groupId>
    <artifactId>saobei-open-sdk</artifactId>
    <version>1.2.1</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/saobei-open-sdk-1.2.1.jar</systemPath>
  </dependency>
</dependencies>

3.2 SDK使用说明

SDK内默认使用的是正式环境，对接需要使用测试环境地址，在方法前对地址重新赋值：

ApiConstants.service_url_pay="技术人员邮件内发送的测试环境地址";

若未重新赋值，会报"终端信息不存在或已关闭!".

切换到正式环境时，删除修改地址的这行代码。

创建对应接口的client，每个接口上有对应的client创建方法。

SaobeiApiClient<SaobeiBarcodePayRequest, SaobeiBarcodePayResponse> client = new DefaultSaobeiApiClient<>(ACCESS_TOKEN);

创建对应接口请求的对象实体，并按照接口传参要求，给属性赋值（若接口中的属性在sdk的对象实体中没有，请自己创建实体类新增属性，并继承sdk内原实体类）

//实体类可使用自己创建的子类（需继承原实体类）
SaobeiBarcodePayRequest requst = new SaobeiBarcodePayRequest();
requst.setPay_ver("202");
......

引用execute方法

SaobeiBarcodePayResponse response = client.execute(requst);

3.2.1 demo使用示例

完整demo示例：TestMain下载对应接口请查阅demo示例里对应的方法，demo内各接口的字段值请按各自接口要求修改。

四、支付相关API

4.1付款码支付（B扫C）

应用场景

收银员使用扫码设备读取微信用户付款码以后，二维码或条码信息会传送至商户收银台，由商户收银台或者商户后台调用该接口发起支付。

❗特殊说明：

付款码没有回调通知接口，如果返回订单状态为支付中，请调用4.5支付查询接口确认订单状态。

Java-SDK工具

client：SaobeiApiClient<SaobeiBarcodePayRequest, SaobeiBarcodePayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/barcodepay
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式， `010` 微信， `020` 支付宝， `060` qq钱包， `090` 抖音支付， `100` 翼支付， `110` 银联二维码， `120` 龙支付（建行通道可用）， `140` 和包支付（和包通道可用）， `160` 数字人民币， `170` 招行APP（招行通道可用）， `000` 自动识别类型
service_id	String	3	Y	接口类型，当前类型 `010`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_ip	String	16	Y	收银机、POS机等收款设备的公网IP 特殊说明：IPV4格式，人行侧风控主要依据，请真实填写。有网络的设备都会有ip，服务端可以从网络请求中获取到交互设备的ip
terminal_location	String	128	N	受理终端设备实时经纬度信息，格式为（纬度/经度）：+31.2579921/-120.729388 +表示北纬、东经， -表示南纬、西经。经度是向东到180°或向西到180° 纬度是0至90度之间
`device_no`	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号（扫呗不做该值的验重，若多次请求使用同一个值，会导致一个单号有多条订单记录）。该值可对应用在4.5支付查询、4.6退款申请、4.7撤销交易接口的pay_trace字段。
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式。该值可对应用在4.5支付查询、4.6退款申请、4.7撤销交易接口的pay_time字段。
auth_no	String	128	Y	微信、支付宝等支付方式里的付款码（条形码或者二维码对应的数字）
total_fee	String	10	Y	金额，单位分，小于2147483647
sub_appid	String	16	N	微信侧商户主体一致的公众号或小程序appid，（有支付后通过返回的用户标识，匹配会员信息需求的可传）
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息，`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`
attach	String	128	N	附加数据,原样返回
goods_detail	String	2048	N	订单包含的商品列表信息，Json数组格式。`pay_type`为`010`、`020`、`110`时，可选填此字段《字段说明》
goods_tag	String	32	N	微信侧订单优惠标记（需提前配置），代金券或立减优惠功能的参数
custom_store_id	String	32	N	微信门店编号和支付宝外部自定义门店编号,透传。微信对应scene_info(场景信息)中的门店id。 `支付宝自定义门店编号不能随便传，在确认门店编号存在的情况下传值，否则影响支付`
official_store_id	String	32	N	支付宝官方门店编号，透传
food_order_type	String	32	N	点餐场景类型： `qr_order`（店内扫码点餐）、 `pre_order`（预点到店自提）、 `home_delivery` （外送到家）、 `direct_payment`（直接付款）、 `other`（其他）
`coupon_no`	String	128	N	优惠券串码
coupon_credential	String	255	N	优惠券凭证
sence_no	String	64	N	支付宝外部业务号，用于标识这笔解码请求。若使用了支付宝付款码查询过用户标识，该参数必传。若付款码没有查询过用户标识，请勿传递该参数，否则会导致提示付款码需刷新。
timeout_express	String	3	N	订单交易关闭时间，单位分。默认120min，上限：360min。该字段只有部分通道和部分支付方式支持，若设置后不生效，即为通道侧或者支付方式不支持，可自行调用4.7撤销交易接口。
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

goods_detail的内容说明:称重商品数量请传1或其它整数，价格传重量*单价后的总价

参数名称	类型	必填	说明
goods_id	String	Y	商品编号(若要匹配单品活动，需与发布的活动商品编号一致)
goods_name	String	Y	商品名称
quantity	String	Y	商品数量，需为整数，不要带小数点
price	String	Y	商品单价，单位为分

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“支付成功”，“支付中”，“请求受限”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果： `01`成功 `02`失败， `03`支付中， `99`该条码暂不支持支付类型自动匹配
pay_type	String	3	N	支付方式： `010`微信， `020` 支付宝， `060`qq钱包， `100`翼支付， `110`银联二维码
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
`device_no`	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号，商户系统的支付订单号，系统原样返回
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式，系统原样返回
total_fee	String	10	N	金额，单位分
buyer_pay_fee	String	12	N	买家实付金额（分）pay_ver为`202`时返回
platform_discount_fee	String	12	N	平台优惠金额（分）pay_ver为`202`时返回
merchant_discount_fee	String	12	N	商家优惠金额（分）pay_ver为`202`时返回
end_time	String	14	N	支付完成时间，yyyyMMddHHmmss，全局统一时间格式
out_trade_no	String	32	N	扫呗订单号
channel_trade_no	String	32	Y	微信订单号、支付宝订单号等
channel_order_no	String	32	N	收单通道侧订单号
user_id	String	32	N	付款方用户id，服务商appid下的“微信openid”、“支付宝账户”
attach	String	128	N	附加数据,原样返回
receipt_fee	String	12	N	商家应结算金额,单位分
bank_type	String	16	N	银行类型，采用字符串类型的银行标识。微信官方提供：银行类型对照表
promotion_detail	String	255	N	官方营销详情,pay_ver为`202`时返回. 本交易支付时使用的所有优惠券信息，单品优惠功能字段，详情见《优惠字段说明》
order_body	String	128	N	订单描述
sub_openid	String	32	N	微信子商户sub_appid对应的用户标识

4.2扫码预支付（已停用）

❗注意：

因微信政策调整【微信间联服务商关闭APP支付和Native支付通知】，部分通道不支持该接口的调用，或不支持通过微信扫本接口返回的链接进行支付。

该接口返回的链接为指定支付方式（指定了微信支付方式就只能用微信扫），需使用指定的支付方式扫码支付。

本接口已停止维护，请移步到4..11聚合码支付接口，实现C扫B的支付场景。

API请求

URL：请移步到4.11聚合码支付接口
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`201`
pay_type	String	3	Y	支付方式， `010`微信， `020` 支付宝， `060`qq钱包， `100`翼支付
service_id	String	3	Y	接口类型，当前类型`011`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_ip	String	16	N	收银机、POS机等设备的公网IP(IPV4格式，人行侧风控主要依据，请真实填写)
`device_no`	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号（扫呗不做该值的验重，若多次请求使用同一个值，会导致一个单号有多条订单记录）
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee	String	10	Y	金额，单位分，小于2147483647
sub_appid	String	16	N	微信侧商户公众号appid
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`
notify_url	String	255	N	支付结果接收地址，外部系统通知地址4.10回调通知注：该字段若不传递，需要通过4.5支付查询接口确认订单支付状态
attach	String	128	N	附加数据，原样返回
goods_detail	String	2048	N	订单包含的商品列表信息，Json数组格式。`pay_type`为`010`，`020`，可选填此字段
goods_tag	String	32	N	微信订单优惠标记（需提前配置），代金券或立减优惠功能的参数
custom_store_id	String	32	N	微信门店编号和支付宝外部自定义门店编号,透传。微信对应scene_info(场景信息)中的门店id。 `支付宝自定义门店编号不能随便传，在确认门店编号存在的情况下传值，否则影响支付`
official_store_id	String	32	N	支付宝官方门店编号，透传
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

goods_detail的内容说明:称重商品数量请传1或其它整数，价格传重量*单价后的总价

参数名称	类型	长度	必填	说明
goods_id	String	32	Y	商品编号
goods_name	String	128	Y	商品名称
quantity	String	11	Y	商品数量，需为整数，不要带小数点
price	String	11	Y	商品单价，单位为分(注:`pay_type`为`010`时，此字段类型为int)

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“预支付请求成功”，“预支付请求失败”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果：`01`成功，`02`失败
pay_type	String	3	N	支付方式， `010`微信， `020` 支付宝， `060`qq钱包， `100`翼支付
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
`device_no`	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号，商户系统的订单号，系统原样返回
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式，系统原样返回
total_fee	String	12	N	金额，单位分
out_trade_no	String	32	N	扫呗订单号
qr_code	String	128	N	二维码码串

4.3公众号下单接口

应用场景

商户系统先调用该接口，在支付服务后台生成预支付交易单，返回正确的预支付交易参数后，再按官方JSAPI场景生成交易串调起支付。

❗注意：

只有当result_code返回值为01时，才可取接口返回的参数，去调微信/支付宝的JSAPI收银台。

调用微信和支付宝JSAPI收银台时，该接口返回的参数不能修改，否则会报“支付验证签名失败”等问题。

该接口只支持微信和支付宝内的H5页面调用，不支持浏览器端H5页面调用。

若公众号内的页面是商城形式的H5（多商户入驻收款，商户主体与公众号主体不一致时），可使用扫呗服务商appid代发起支付申请。即：先调用4.16获取服务商公众号下openid接口，得到服务商appid下的openid，再调用该4.3公众号支付接口，调用时sub_appid可不传（会默认取服务商appid），open_id传4.16获取服务商公众号下openid接口中获取的openid。

获取用户标识及调起js支付的官方参考文档：
微信

获取openid: https://developers.weixin.qq.com/doc/service/guide/h5/auth.html
调jsapi支付：https://pay.weixin.qq.com/doc/v3/partner/4012069855

支付宝

获取userid: https://opendocs.alipay.com/mini/02xtl8?pathHash=253bc790 具体获取方式可在支付宝官网搜索。
调jsapi支付：https://alipay.open.taobao.com/docs/doc.htm?&docType=1&articleId=105591

Java-SDK工具

client：SaobeiApiClient<SaobeiJsPayRequest, SaobeiJsPayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/jspay
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式， `010`微信， `020`支付宝， `060`qq钱包， `090` 抖音支付， `100`翼支付, `110`银联云闪付
service_id	String	3	Y	接口类型，当前类型`012`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_ip	String	16	N	用户手机端IP(IPV4格式，人行侧风控主要依据，请真实填写)
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号（扫呗不做该值的验重，若多次请求使用同一个值，会导致一个单号有多条订单记录）。该值可对应用在4.5支付查询、4.6退款申请、4.8关闭订单接口的pay_trace字段。
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式。该值可对应用在4.5支付查询、4.6退款申请、4.8关闭订单接口的pay_time字段。
total_fee	String	10	Y	金额，单位分，小于2147483647
sub_appid	String	16	Y	`传商户自己的微信公众号appid，或支付宝生活号appid。`（即获取open_id所使用的appid）。 `pay_type`为`010`及`020`时必填
open_id	String	128	Y	用户标识（微信openid，支付宝userid），`pay_type`为`010`及`020`时必填
timeout_express	String	3	N	订单交易关闭时间（单位分，不传默认120）。 `如果公众号有设置订单失效时间的，建议和订单失效时间设置一致`。该字段部分收单通道支持，若遇到不生效的情况，即为收单通道不支持。
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`
notify_url	String	255	N	支付结果接收地址，外部系统通知地址4.10回调通知注：该字段若不传递，需要通过4.5支付查询接口确认订单支付状态
attach	String	128	N	附加数据，原样返回
goods_detail	String	2048	N	订单包含的商品列表信息，Json数组格式。`pay_type`为`010`，`020`，可选填此字段
goods_tag	String	32	N	订单优惠标记（需提前配置），代金券或立减优惠功能的参数
custom_store_id	String	32	N	微信门店编号和支付宝外部自定义门店编号,透传。微信对应scene_info(场景信息)中的门店id。 `支付宝自定义门店编号不能随便传，在确认门店编号存在的情况下传值，否则影响支付`
official_store_id	String	32	N	支付宝官方门店编号，透传
food_order_type	String	32	N	点餐场景类型： `qr_order`（店内扫码点餐）、 `pre_order`（预点到店自提）、 `home_delivery` （外送到家）、 `direct_payment`（直接付款）、 `other`（其他）
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

goods_detail的内容说明:称重商品数量请传1或其它整数，价格传重量*单价后的总价

参数名称	类型	长度	必填	说明
goods_id	String	32	Y	商品编号
goods_name	String	128	Y	商品名称
quantity	String	11	Y	商品数量，需为整数，不要带小数点
price	String	11	Y	商品单价，单位为分(注:`pay_type`为`010`时，此字段类型为int)

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“预支付请求成功”，“预支付请求失败”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果：`01`成功，`02`失败
pay_type	String	3	N	支付方式： `010`微信， `020`支付宝， `060`qq钱包， `100`翼支付
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号，商户系统的支付订单号，系统原样返回
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee	String	12	N	金额，单位分
out_trade_no	String	32	N	扫呗订单号
appId	String	16	N	微信公众号支付返回字段，公众号id
timeStamp	String	32	N	微信公众号支付返回字段，时间戳，示例：1414561699，标准北京时间，时区为东八区，自1970年1月1日 0点0分0秒以来的秒数。注意：部分系统取到的值为毫秒级，需要转换成秒(10位数字)。
nonceStr	String	32	N	微信公众号支付返回字段，随机字符串
package_str	String	128	N	微信公众号支付返回字段，订单详情扩展字符串，示例：prepay_id=123456789，统一下单接口返回的prepay_id参数值，提交格式如：prepay_id=
signType	String	32	N	微信公众号支付返回字段，签名方式，示例：MD5,RSA
paySign	String	512	N	微信公众号支付返回字段，签名
ali_trade_no	String	32	N	支付宝JSAPI支付返回字段用于调起支付宝JSAPI
redirect_uri	String	512	N	云闪付支付或一些银行通道会返回。若该字段有值，请取该字段的链接做重定向跳转，不需要按照正常jsapi方式调用。
token_id	String	32	N	qq钱包公众号支付

4.4小程序下单接口

应用场景

商户在小程序中先调用该接口，在支付服务后台生成预支付交易单，返回正确的预支付交易参数后，再按官方JSAPI场景生成交易串调起支付。

❗注意：

只有当result_code返回值为01时，才可取接口返回的参数，去调微信小程序/支付宝小程序的JSAPI收银台。

请求完这个接口得到的返回参数直接去调微信小程序/支付宝小程序的JSAPI收银台发起支付，接口返回的参数值一个都不能修改，否则会报“支付验证签名失败”、“商户传入的appid参数不正确”等问题

若报“预支付失败sub_mch_id与sub_appid不匹配”，请联系运营同事，并提供小程序appid，在正式商户的对应通道关注配置里添加appid，appid主体需与商户主体一致，否则无法配置。

该接口为预支付接口，还未进行支付，故该接口不返回优惠字段。优惠字段会在支付完成后，通过回调接口返回，或者通过查询接口获取。

获取用户标识及调起js支付文档：
微信小程序

获取openid: https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/login.html
调jsapi支付：https://pay.weixin.qq.com/doc/v3/partner/4012085827

支付宝小程序

获取userid: https://opendocs.alipay.com/mini/05dxgc?pathHash=1a3ecb13
调jsapi支付： https://opendocs.alipay.com/mini/api/openapi-pay

Java-SDK工具

client：SaobeiApiClient<SaobeiMiniPayRequest, SaobeiMiniPayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/minipay
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式， `010`微信， `020`支付宝， `090` 抖音支付
service_id	String	3	Y	接口类型，当前类型`015`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_ip	String	16	N	用户手机端IP(IPV4格式，人行侧风控主要依据，请真实填写)
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号（扫呗不做该值的验重，若多次请求使用同一个值，会导致一个单号有多条订单记录）。该值可对应用在4.5支付查询、4.6退款申请、4.8关闭订单接口的pay_trace字段。
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式。该值可对应用在4.5支付查询、4.6退款申请、4.8关闭订单接口的pay_time字段。
total_fee	String	10	Y	金额，单位分，小于2147483647
sub_appid	String	16	Y	`传商户自己的小程序appid`。（即获取open_id所使用的appid）。`pay_type`为`010`及`020`时必填
open_id	String	128	Y	用户标识（微信openid，支付宝userid），`pay_type`为`010`及`020`时必填
timeout_express	String	3	N	订单交易关闭时间（单位分，不传默认120）。 `如果小程序有设置订单失效时间的，建议和订单失效时间设置一致`。该字段部分收单通道支持，若遇到不生效的情况，即为收单通道不支持。
goods_detail	String	2048	N	订单包含的商品列表信息，Json数组格式。`pay_type`为`010`，`020`时，可选填此字段，详情见《字段说明》
goods_tag	String	32	N	订单优惠标记（需提前配置），代金券或立减优惠功能的参数
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`
notify_url	String	255	N	支付结果接收地址，外部系统通知地址4.10回调通知注：该字段若不传递，需要通过4.5支付查询接口确认订单支付状态
attach	String	128	N	附加数据，原样返回
coupon_no	String	128	N	优惠券串码
coupon_credential	String	255	N	优惠券凭证
custom_store_id	String	32	N	微信门店编号和支付宝外部自定义门店编号,透传。微信对应scene_info(场景信息)中的门店id。 `支付宝自定义门店编号不能随便传，在确认门店编号存在的情况下传值，否则影响支付`
official_store_id	String	32	N	支付宝官方门店编号，透传
food_order_type	String	32	N	微信点餐场景类型： qr_order（店内扫码点餐）、 pre_order（预点到店自提）、home_delivery （外送到家）、direct_payment（直接付款）、 other（其他）支付宝点餐场景类型： QR_FOOD_ORDER（点餐先付）、 P_QR_FOOD_ORDER（点餐后付）、 SELF_PICK（门店自提）、 TAKE_OUT（餐饮外卖）
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

goods_detail的内容说明:称重商品数量请传1或其它整数，价格传重量*单价后的总价

参数名称	类型	长度	必填	说明
goods_id	String	32	Y	商品编号
goods_name	String	128	Y	商品名称
quantity	String	11	Y	商品数量，需为整数，不要带小数点
price	String	11	Y	商品单价，单位为分(注:`pay_type`为`010`时，此字段类型为`int`)

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“预支付请求成功”，“预支付请求失败”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果：`01`成功，`02`失败
pay_type	String	3	N	支付方式，`010`微信，`020`支付宝
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号，商户系统的支付订单号，系统原样返回
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式，系统原样返回
total_fee	String	12	N	金额，单位分
out_trade_no	String	32	N	扫呗订单号
appId	String	16	N	微信小程序支付返回字段，公众号id
timeStamp	String	32	N	微信小程序支付返回字段，时间戳，示例：1414561699，标准北京时间，时区为东八区，自1970年1月1日 0点0分0秒以来的秒数。注意：部分系统取到的值为毫秒级，需要转换成秒(10位数字)。
nonceStr	String	32	N	微信小程序支付返回字段，随机字符串
package_str	String	128	N	微信小程序支付返回字段，订单详情扩展字符串，示例：prepay_id=123456789，统一下单接口返回的prepay_id参数值，提交格式如：prepay_id=
signType	String	32	N	微信小程序支付返回字段，签名方式，示例：MD5,RSA
paySign	String	512	N	微信小程序支付返回字段，签名
ali_trade_no	String	32	N	支付宝交易号，用于调用my.tradePay

4.5支付查询

应用场景

该接口提供所有微信支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。需要调用查询接口的情况：

当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；
调用支付接口后，返回系统错误或未知交易状态情况；
调用被扫支付API，返回USERPAYING的状态；
调用关单或撤销接口API之前，需确认支付状态；

查询方式

方式一：使用利楚订单号进行查询：用支付下单接口返回的out_trade_no值，传在支付查询接口的out_trade_no字段。若没有获取到该字段的值，请使用方式二查询。
方式二：使用商户自己订单号进行查询：把支付下单请求接口里的terminal_trace字段值传在支付查询接口的pay_trace字段，和支付下单请求接口里的terminal_time字段值传在支付查询接口的pay_time字段。使用该方式时，out_trade_no不需要传值。

推荐优先方式一，拿不到out_trade_no时用方式二。

❗注意：

建议每次查询间隔3-5s。付款码支付的情况下，若查询多次还是支付中，可在确定没有资金损失的情况下调用4.7撤销交易接口（支付成功的会退款），关闭订单。

若支付接口或者查询接口返回了终态的（如支付成功、支付失败、已退款、已关闭），无需继续查询。

若出现网络超时，拿不到out_trade_no时，可使用方式二进行查询。

Java-SDK工具

client：SaobeiApiClient<SaobeiTradeQueryRequest, SaobeiTradeQueryResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/query
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式：`000`自动识别类型
service_id	String	3	Y	接口类型，当前类型`020`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	查询请求流水号，每次请求新生成（不要传支付流水号）
terminal_time	String	14	Y	查询请求发起的实时时间，yyyyMMddHHmmss，全局统一时间格式，每次请求新生成
pay_trace	String	32	可选	需要查询的`支付请求里的`终端流水号（terminal_trace），与pay_time同时传递
pay_time	String	14	可选	需要查询的`支付请求里的`终端交易时间（terminal_time），yyyyMMddHHmmss，全局统一时间格式，与pay_trace同时传递
out_trade_no	String	64	可选	扫呗订单号，传支付请求里返回的out_trade_no（使用方式二查询订单时，该字段需赋值为""空）
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“支付成功”，“支付中”，“请求受限”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果：`01`成功，`02`失败（无需继续查询），`03`支付中。`支付失败`和`退款成功`状态均返回`02`，具体状态和原因会在`return_msg`中给出解释
pay_type	String	3	N	支付方式： `010`微信， `020` 支付宝， `060`qq钱包， `100`翼支付， `110`银联二维码
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号，商户系统的查询流水号，系统原样返回
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee	String	12	N	金额，单位分
buyer_pay_fee	String	12	N	买家实付金额（分）pay_ver为`202`时返回
platform_discount_fee	String	12	N	平台优惠金额（分）pay_ver为`202`时返回
merchant_discount_fee	String	12	N	商家优惠金额（分）pay_ver为`202`时返回
sub_openid	String	32	N	子商户appid下用户唯一标识，如需返回则请求时需要传sub_appid。pay_ver为`202`时返回
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。pay_ver为`202`时返回
end_time	String	14	N	支付完成时间，yyyyMMddHHmmss，全局统一时间格式
out_trade_no	String	32	N	扫呗订单号
trade_state	String	10	N	交易订单状态， `SUCCESS`支付成功，（无需继续查询） `REFUND`转入退款，（无需继续查询） `NOTPAY`未支付， `CLOSED`已关闭，（无需继续查询） `USERPAYING`用户支付中， `REVOKED`已撤销，（无需继续查询） `NOPAY`未支付支付超时， `PAYERROR`支付失败（无需继续查询）
channel_trade_no	String	32	Y	微信订单号、支付宝订单号等
channel_order_no	String	32	N	收单通道侧订单号
user_id	String	32	N	付款方用户id，“微信openid”、“支付宝账户”、“qq号”等
attach	String	128	N	附加数据，原样返回
receipt_fee	String	12	N	商家应结算金额,单位分
pay_trace	String	32	N	当前支付终端流水号
pay_time	String	14	N	当前支付终端交易时间，yyyyMMddHHmmss，全局统一时间格式
bank_type	String	16	N	银行类型，采用字符串类型的银行标识。微信官方提供：银行类型对照表
promotion_detail	String	6000	N	本交易支付时使用的所有优惠券信息，单品优惠功能字段，详情见《优惠字段说明》pay_ver为`202`时返回

4.6退款申请

应用场景

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，支付机构将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。退款有一定延时，用零钱支付的退款可实时到账，银行卡支付的退款一般3个工作日内到账。

退款方式

方式一：使用利楚订单号进行退款：用支付下单接口返回的out_trade_no值，传在退款申请接口的out_trade_no字段。
方式二：使用商户自己订单号进行退款：把支付下单请求接口里的terminal_trace字段值传在退款申请接口里的pay_trace字段，和支付下单请求里的terminal_time字段值传在退款申请接口的pay_time字段。使用该方式时，out_trade_no不需要传值。

推荐优先方式一，拿不到out_trade_no时用方式二。

❗注意：

需要商户当天有收单，或者商户账户内有大于退款金额的余额，否则会造成余额不足，退款失败；

退款接口实时返回结果，没有回调通知。退款到账情况，以各钱包或者银行卡到账时效为准。

Java-SDK工具

client：SaobeiApiClient<SaobeiTradeRefundRequest, SaobeiTradeRefundResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/refund
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式：`000`自动识别类型
service_id	String	3	Y	接口类型，当前类型`030`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	退款流水号(`不要和支付单号或者要退款的单号用一样的值`)，可填写商户系统的退款流水号，每次请求需新生成。该值可对应用在4.9退款订单查询接口的pay_trace字段。
terminal_time	String	14	Y	请求发生时的实时时间，yyyyMMddHHmmss，全局统一时间格式，每次请求新生成。该值可对应用在4.9退款订单查询接口的pay_time字段。
repeated_trace	String	1	N	是否允许订单重复,传1：不允许terminal_trace重复。传2：不允许terminal_trace+terminal_time重复，传0或不传:允许重复
refund_fee	String	10	Y	退款金额，单位分，小于2147483647
out_trade_no	String	64	O	扫呗订单号，传支付请求里返回的out_trade_no （也可使用支付接口返回的channel_trade_no或channel_order_no）
pay_trace	String	32	O	需要退款的`支付请求里的`终端流水号，与pay_time同时传递
pay_time	String	14	O	需要退款的`支付请求里的`终端交易时间，yyyyMMddHHmmss，全局统一时间格式，与pay_trace同时传递
order_body	String	80	N	退款订单备注
attach	String	128	N	附加数据
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“退款成功”、“订单不存在”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果：`01`成功，`02`失败
pay_type	String	3	N	支付方式： `010`微信， `020` 支付宝， `060`qq钱包， `100`翼支付， `110`银联二维码
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	N	终端流水号，商户系统的退款流水号，系统原样返回
terminal_time	String	14	N	终端退款时间，yyyyMMddHHmmss，全局统一时间格式
refund_fee	String	12	N	退款金额，单位分
refund_receipt_fee	String	12	N	退商家应结算金额（分）pay_ver为`202`时返回
refund_buyer_pay_fee	String	12	N	退买家实付金额（分）pay_ver为`202`时返回
refund_platform_discount_fee	String	12	N	退平台优惠金额（分）pay_ver为`202`时返回
refund_merchant_discount_fee	String	12	N	退商家优惠金额（分）pay_ver为`202`时返回
refund_promotion_detail	String	6000	N	退优惠明细，详情见《优惠字段说明》pay_ver为`202`时返回
end_time	String	14	N	退款完成时间，yyyyMMddHHmmss，全局统一时间格式
out_trade_no	String	32	N	扫呗原支付订单号
out_refund_no	String	32	N	扫呗侧退款单号
channel_refund_no	String	32	N	通道侧退款单号

4.7撤销交易

应用场景

付款码支付交易返回失败或支付系统超时，调用该接口撤销交易。如果此订单用户支付失败，支付系统会将此订单关闭；如果用户支付成功，支付系统会将此订单资金退还给用户。

撤销方式

方式一：用支付下单接口返回的out_trade_no值，传在撤销交易接口的out_trade_no字段。
方式二：把支付下单请求接口里的terminal_trace字段值传在撤销交易接口的pay_trace字段，和支付下单请求里的terminal_time字段值传在撤销交易接口的pay_time字段。使用该方式时，out_trade_no不需要传值。

推荐优先方式一，拿不到out_trade_no时用方式二。

❗注意：

撤销接口只适用于B扫C的付款码支付场景。

撤销接口会对已经支付的订单进行退款，程序要在不会有资金损失的情况下调用撤销接口；或者由人工确认确实可撤销后，再手动调用撤销接口。

请勿在没有收银员确认的情况下自动调用撤销接口，这样可能会出现资损。

Java-SDK工具

client：SaobeiApiClient<SaobeiTradeCancelRequest, SaobeiTradeCancelResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/cancel
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`201`
pay_type	String	3	Y	支付方式：`000`自动识别类型
service_id	String	3	Y	接口类型，当前类型`040`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	请求流水号(`不要和支付单号或者要撤销的单号用一样的值`)，每次请求新生成，需唯一
terminal_time	String	14	Y	请求发起时的实时时间，yyyyMMddHHmmss，全局统一时间格式，每次请求新生成
out_trade_no	String	32	N	扫呗订单号，传支付请求里返回的out_trade_no
pay_trace	String	32	N	支付请求里的terminal_trace终端流水号，与pay_time同时传递
pay_time	String	14	N	支付请求里的terminal_time终端交易时间，与pay_trace同时传递
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“退款成功”、“订单不存在”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	"业务结果，“01”成功，表示撤销成功，此笔订单不能再发起支付；若已支付完成，则会发起退款；“02”失败，表示撤销接口异常
pay_type	String	3	N	支付方式： `010`微信， `020`支付宝， `040`现金， `060`qq钱包， `100`翼支付， `110`银联二维码
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号（socket协议：长度为6位，Http协议：长度为32位）
terminal_time	String	14	N	终端撤销时间，yyyyMMddHHmmss，全局统一时间格式
recall	String	1	N	废弃字段
merchant_name	String	40	N	商户名称

4.8关闭订单

应用场景

商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时或未支付，系统退出不再受理后，避免用户继续支付。

关单方式

方式一：使用利楚订单号进行关单：用支付下单接口返回的out_trade_no值，传在关闭订单接口的out_trade_no字段。
方式二：使用商户自己订单号进行关单：把支付下单请求接口里的terminal_trace字段值传在关闭订单接口的pay_trace字段，和支付下单请求里的terminal_time字段值传在关闭订单接口的pay_time字段。使用该方式时，out_trade_no不需要传值。

推荐优先方式一，拿不到out_trade_no时用方式二。

❗注意：

使用聚合码、公众号和小程序支付接口发起的订单，可以通过该接口关闭。

Java-SDK工具

client：SaobeiApiClient<SaobeiTradeCloseRequest, SaobeiTradeCloseResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/close
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`201`
pay_type	String	3	Y	支付方式：`000`自动识别类型产业支付关单时，需指定支付方式 `180`微企付 `190`支付宝商转
service_id	String	3	Y	接口类型，当前类型`041`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	请求流水号(`不要和支付单号或者要关闭的单号用一样的值`)，每次请求新生成，需唯一
terminal_time	String	14	Y	请求发起时的实时时间，yyyyMMddHHmmss，全局统一时间格式，每次请求新生成
out_trade_no	String	32	N	扫呗订单号，传支付请求里返回的out_trade_no
pay_trace	String	32	N	支付请求里的terminal_trace终端流水号，与pay_time同时传递
pay_time	String	14	N	支付请求里的terminal_time终端交易时间，与pay_trace同时传递
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“关单成功”、“订单不存在”等
key_sign	String	32	Y	签名串
result_code	String	2	N	业务结果， `01`成功，表示关单成功，此笔订单不能再发起支付； `02`失败，表示关单失败
pay_type	String	3	N	支付方式：`010`微信
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	终端流水号（socket协议：长度为6位，Http协议：长度为32位）
terminal_time	String	14	N	终端撤销时间，yyyyMMddHHmmss，全局统一时间格式

4.9退款订单查询

应用场景

提交退款申请后，通过调用该接口查询退款状态。

退款方式

方式一：用退款申请接口返回的out_refund_no值，传在退款订单查询接口的out_refund_no字段。
方式二：把退款申请请求接口里的terminal_trace字段值传在退款订单查询接口里的pay_trace字段，和退款申请请求里的terminal_time字段值传在退款订单查询接口的pay_time字段。使用该方式时，out_trade_no不需要传值。

推荐优先方式一，拿不到out_trade_no时用方式二。

Java-SDK工具

client：SaobeiApiClient<SaobeiTradeQueryRefundRequest, SaobeiTradeQueryRefundResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/queryrefund
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式：`000`自动识别类型
service_id	String	3	Y	接口类型，当前类型`031`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
device_no	String	32	N	商户侧门店或者终端编号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	退款查询流水号，每次请求新生成，需唯一
terminal_time	String	14	Y	退款查询时间，yyyyMMddHHmmss，全局统一时间格式
out_refund_no	String	32	可选	平台唯一退款订单号，退款请求里返回的out_refund_no
pay_trace	String	32	可选	退款申请接口里的终端退款流水号（ terminal_trace），与pay_time同时传递
pay_time	String	14	可选	退款申请接口里的终端交易时间（ terminal_time），与pay_trace同时传递
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息, 返回错误原因
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果：`01`成功，`02`失败
pay_type	String	3	N	支付方式： `010`微信， `020` 支付宝， `060`qq钱包， `100`翼支付， `110`银联二维码
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户终端设备号(商户自定义，如门店编号),必须在平台已配置过
terminal_trace	String	32	N	当前终端退款查询流水号，扫呗系统原样返回
terminal_time	String	14	N	当前终端退款查询时间，扫呗系统原样返回
refund_fee	String	12	N	退款金额，单位分
refund_receipt_fee	String	12	N	退商家应结算金额,单位分
refund_buyer_pay_fee	String	12	N	退买家实付金额（分）
refund_platform_discount_fee	String	12	N	退平台优惠金额（分）
refund_merchant_discount_fee	String	12	N	退商家优惠金额（分）
refund_promotion_detail	String	6000	N	退优惠明细，详情见《优惠字段说明》
end_time	String	14	N	退款完成时间，yyyyMMddHHmmss，全局统一时间格式
out_refund_no	String	32	N	扫呗退款订单号
out_trade_no	String	32	N	原支付扫呗订单号
trade_state	String	10	N	退款订单状态： `SUCCESS`退款成功， `FAIL`退款失败， `REFUNDING`退款中， `NOREFUND`退款超时等
channel_trade_no	String	32	Y	微信订单号、支付宝订单号等
channel_order_no	String	32	N	收单通道侧订单号
user_id	String	32	N	退款方用户id，“微信openid”、“支付宝账户”、“qq号”等
attach	String	128	N	附加数据，原样返回
pay_trace	String	32	N	退款终端流水号
pay_time	String	14	N	退款终端交易时间

4.10回调通知

应用场景
支付完成后，将该笔订单的变更信息，沿着商户调用预下单请求时所传入的异步通知地址 notify_url，通过 POST 请求的形式将支付结果作为参数通知到商户系统，商户需要接收处理，并按文档规范返回应答，返回格式：{"return_code":"01","return_msg":"success"}。

❗注意：

1、只有支付成功才有回调。支付失败和退款是接口实时返回结果，没有回调。
2、接收到推送报文后，需在3s内返回响应结果。若不返回，或返回报文格式错误，不进行重推。
3、当回调地址访问超时或者地址请求异常时，会重推3次，若还失败，不再重推。建议商户主动调用【4.5支付查询】确认订单状态。

协议要求

Method：POST
Content-type：application/json
URL：下单传入的notify_url

推送参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，返回值`201`、`202`
return_code	String	2	Y	响应码：`01`成功，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“支付成功”
result_code	String	2	Y	业务结果：`01`成功
pay_type	String	3	Y	支付方式： `010`微信， `020` 支付宝， `060`qq钱包， `090` 抖音支付， `100`翼支付， `110`云闪付， `180` 微企付， `190` 支付宝商转
user_id	String	32	Y	服务商appid下的付款方用户id，“微信openid”、“支付宝账户”、“qq号”等
merchant_name	String	40	Y	商户名称
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
device_info	String	32	N	商户侧门店或者终端编号,`支付请求传递了device_no时返回。`
terminal_trace	String	32	Y	终端流水号，此处传商户发起预支付或公众号支付时所传入的交易流水号
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式（01时参与拼接）
pay_trace	String	32	N	当前支付终端流水号，与pay_time同时传递
pay_time	String	14	N	当前支付终端交易时间，yyyyMMddHHmmss，全局统一时间格式，与pay_trace同时传递
total_fee	String	12	Y	金额，单位分
end_time	String	14	Y	支付完成时间，yyyyMMddHHmmss，全局统一时间格式
out_trade_no	String	32	Y	扫呗订单号
channel_trade_no	String	32	Y	微信订单号、支付宝订单号等
channel_order_no	String	32	N	收单通道侧订单号，pay_ver为`202`时返回
attach	String	128	Y	附加数据，原样返回
receipt_fee	String	12	N	商家应结算金额,单位分
sub_openid	String	32	Y	子商户appid(对应sub_appid字段)下的付款方用户id，“微信openid”、“支付宝账户”、“qq号”等 pay_ver为`202`时返回
buyer_pay_fee	String	12	N	买家实付金额（分）pay_ver为`202`时返回
platform_discount_fee	String	12	N	平台优惠金额（分）pay_ver为`202`时返回
merchant_discount_fee	String	12	N	商家优惠金额（分）pay_ver为`202`时返回
bank_type	String	16	N	银行类型，采用字符串类型的银行标识。微信官方提供：银行类型对照表
promotion_detail	String	6000	N	本交易支付时使用的所有优惠券信息，单品优惠功能字段，详情见《优惠字段说明》
order_body	String	128	N	订单标题描述
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

需返回参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01` 成功
return_msg	String	128	Y	返回信息提示

4.11聚合码接口（C扫B）

应用场景

该接口调用完后只是返回了一个收银台链接，并未产生支付订单。使用方式有两种：

方式一：把链接转换成二维码后，用户扫码打开收银台页面，发起支付。
方式二：在微信、支付宝内的H5页面中，使用页面跳转的方式打开链接，发起支付。

❗注意：

码失效和订单失效的区别：该接口请求后只是生成了一个收银台链接，并不是支付请求，故调用该接口设置的timeout_express失效时间，只是链接的失效时间，并不是订单的失效时间，该接口无法控制订单的失效时间。若消费者在链接即将失效的时候，扫了码（扫码后才生成待支付订单），链接失效后，订单仍然可以支付。

如何查询订单：该接口因不是支付请求，所以没有返回out_trade_no订单号，但可以通过端流水号+终端交易时间做为查询值（支付查询接口的方式二），调用4.5支付查询接口发起订单查询。

如何判断用户是否扫码：设置auto_pay值为1，扫码时会自动生成订单，并拉起JSAPI支付。通过订单查询接口进行订单状态查询，若返回"订单信息不存在！"，说明用户没有扫码。

如何关闭订单：扫码后没有完成支付的订单，当查询请求返回订单信息后，可使用查询接口返回的out_trade_no或终端流水号+终端交易时间，调用4.8关闭订单接口发起订单关闭。

若报“当前页面的URL未注册: http://wxpay.lcsw.cn/test/pay_sdk.html ”或其它地址未注册，请联系运营同事，在正式商户上对应通道的关注配置里，添加支付授权目录地址：http://wxpay.lcsw.cn/test/ 或对应提示的地址。

Java-SDK工具

client：SaobeiApiClient<SaobeiQrPayRequest, SaobeiQrPayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/qrpay
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，当前版本`202`
pay_type	String	3	Y	请求类型：`000`
service_id	String	3	Y	接口类型，当前类型`016`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号特殊说明： 1.若repeated_trace设置1，多次请求时不可使用同一个值）。 2.该值可对应用在4.5支付查询、4.6退款申请、4.8关闭订单接口的pay_trace字段。
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式。该值可对应用在4.5支付查询、4.6退款申请、4.8关闭订单接口的pay_time字段。
total_fee	String	12	Y	金额，单位分
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`
notify_url	String	255	N	支付结果接收地址，外部系统通知地址4.10回调通知注：该字段若不传递，需要通过4.5支付查询接口确认订单支付状态
attach	String	128	N	附加数据，原样返回
timeout_express	String	4	N	链接失效时间，该字段无法控制订单失效时间，具体请看注意事项。单位s。取值范围：1～7200的整数，不传默认7200s。
repeated_trace	String	2	N	是否允许重复扫码或支付 `0`或不传:允许重复扫码或支付。（同一终端流水号和终端交易时间会出现多笔交易） `1`:不允许重复扫码或支付。(取消支付后也不可重新支付) `2`:允许terminal_trace值不变，但terminal_time值变化时，多次请求该接口生成收款码（用于订单重新发起收款或者一个单号分不同时间多次收款）
auto_pay	String	1	N	扫码后是否自动生成订单 `1`：自动拉起支付并生成订单， `0`或不传：手动点击页面支付按钮后生成订单
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码：`01`成功，`02`失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“预支付请求成功”，“预支付请求失败”等
result_code	String	2	Y	业务结果：`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	金额，单位分
qr_url	String	128	N	短链接，需调用方自己转换成二维码或直接在微信和支付宝、云闪付内打开链接
key_sign	String	32	N	签名验证串《2.4签名算法》签名测试页

4.12WAP收银台

应用场景

微信、支付宝、云闪付、QQ钱包、翼支付内直接访问拼接后的url，不支持浏览器、三方应用或小程序内打开。

❗注意：

该接口为请求链接的拼接，故没有返回参数，拼接后的链接可转换成二维码，或者在页面内直接访问。

当repeated_trace字段传1时，会同时根据传递的terminal_time来限制此链接有效时间为两小时，例如链接传递terminal_time=20190510101409，那么20190510121409以后访问此链接会返回链接失效，此时需要重新生成wapsdk链接。

Java-SDK工具

client：SaobeiApiClient<SaobeiWapPayRequest, String> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

拼接地址

URL：/open/wap/110/pay
Method：GET
拼接格式：http://接口域名/open/wap/110/pay?auto_pay=0&merchant_no=&notify_url=&其它参数=key_sign=签名验证串

拼接参数

参数名称	类型	长度	必填	说明
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
company_flag	String	2	N	是否使用产业付产品: 0：否（默认0） 1：产业付和普通支付混合 2：只能产业付（即pay_type只能使用180或者190）
pay_type	String	4	N	支付类型 000 自动判断（不填默认000） 010 微信 020 支付宝 110 银联云闪付 180 微企付 190 支付宝商转 `company_flag 为2时，设置180、190可限制只能使用产业付。或者传000可实现自动识别` `注意: 此字段不参与签名`
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号（若repeated_trace设置1，多次请求时不可使用同一个值）
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee	String	12	Y	金额，单位分
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`，`中文需要urlencode，签名拼接不需要urlencode`
notify_url	String	255	N	支付结果接收地址，通知数据请查看4.10回调通知接口，支付宝商转不支持回调。注：该字段若不传递，需要通过4.5支付查询接口确认订单支付状态（get请求拼接需要urlencode，签名拼接不需要urlencode）
auto_pay	String	1	N	扫码后是否自动生成订单 `1`：自动拉起支付并生成订单， `0`或不传：手动点击页面支付按钮后生成订单（若设置为1，需要联系业务运营同事关闭商户的分期功能，否则不生效）
attach	String	128	N	附加数据，原样返回，`中文需要urlencode，签名拼接不需要urlencode`
repeated_trace	String	2	N	是否允许重复扫码或支付 `0`或不传:允许重复扫码或支付。 `1`:不允许重复扫码或支付。(取消支付后也不可重新支付) `2`:允许terminal_trace值不变，但terminal_time值变化时，多次请求该接口生成收款码（用于订单重新发起收款或者一个单号分不同时间多次收款）
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

4.13(刷脸)自助收银SDK调用凭证获取接口

微信刷脸说明：

https://pay.weixin.qq.com/wiki/doc/wxfacepay/develop/android/facepay.html#微信刷脸支付场景说明

第一步：使用官方流程中的第一步和第二步中的获取数据接口，得到rawdata。

第二步：拿着获取到的rawdata调用本文档的“自助收银sdk调用凭证获取”接口可获取到SDK调用凭证authinfo（该接口替代官方流程中第二步中的“获取SDK调用凭证”接口）。

第三步：使用上一步接口获取到的authinfo、 sub_serv_no（对应官方接口mch_id字段）、sub_serv_appid（对应官方接口的appid字段）再去调用官方流程中的“5、进行人脸识别”接口，得到返回值face_code。

第四步：使用上一步中获取的face_code值，调用本文档中“(刷脸)自助收银支付接口”传递在auth_no字段或者使用“付款码支付”接口传在auth_no字段。这样就可以完成刷脸支付。

支付宝刷脸说明：

https://opendocs.alipay.com/open/20180402104715814204/cgxcze#支付宝刷脸支付场景说明

按照官方流程：

第一步：使用官方“1.2.1获取刷脸所需的设备信息”接口（接口所需值由设备提供），得到返回结果。

第二步：将第一步返回结果对象转换成json传入到本文档的“4.13自助收银sdk调用凭证获取”接口的rawdata字段，从而得到authinfo值（对应的是支付宝返回的zim_id的值）；当上游通道不支持这一步时，可使用第一步接口返回的参数，自行调用官方“1.2.2刷脸初始化”接口，得到zim_id。

第三步：调用官方“1.2.3唤起人脸识别”接口，将上一步返回的authinfo字段或zim_id（自行调用官方接口获得）的值传入到接口所需的zimId字段，得到返回值ftoken。

第四步：使用上一步返回的ftoken字段，调用本文档中的“4.14(刷脸)自助收银支付接口”传在auth_no字段，这样就可以完成刷脸支付。

两个刷脸支付流程均为四步，第一和第三步调用官方接口，第二步和第四步调用扫呗。支付宝刷脸时的第二步也可自行调用官方接口。

Java-SDK工具

client：SaobeiApiClient<SaobeiFaceInfoRequest, SaobeiFaceInfoResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/faceinfo
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`201`
pay_type	String	3	Y	支付方式， `010` 微信， `020` 支付宝
sub_appid	String	16	N	子商户绑定的公众号/小程序 appid(服务商模式)
merchant_no	String	15	Y	商户号
terminal_no	String	8	Y	终端号
rawdata	String	2048	Y	微信、支付宝人脸识别SDK初始化数据
trace_no	String	32	Y	请求流水号，不可重复
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码： `01` 成功， `02` 失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“凭证获取成功”，“凭证获取失败”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果： `01` 成功， `02` 失败
pay_type	String	3	N	支付方式， `010` 微信， `020` 支付宝
merchant_no	String	15	N	商户号
terminal_no	String	8	N	终端号
authinfo	String	4096	N	微信、支付宝人脸识别SDK调用凭证
trace_no	String	32	N	请求流水号
out_trade_no	String	32	N	扫呗订单号，用于调起微信刷脸SDK
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
expires_in	int	14	N	微信人脸识别返回有效时间，单位：秒
zim_init	String	4096	N	支付宝ZimInitClientData
auth_no_type	String	2	N	支付预下单支持的授权码类型：1纯数字形式，2非纯数字形式(版本号为`120`时返回)
sub_mchid_info	String	512	N	商户信息 (版本号为`120`时返回)

sub_mchid_info参数：

参数名称	类型	长度	必填	说明
type	String	3	N	支付方式， `010` 微信
sub_mchid	String	15	N	子商户号
sub_serv_no	String	18	N	服务商商户号，对应传在微信官方`getWxpayfaceCode接口的 mch_id 字段`
sub_serv_appid	String	18	N	服务商应用appid，对应传在微信官方`getWxpayfaceCode接口的 appid 字段`
sub_appid	String	18	N	微信子商户号appid

4.14(刷脸)自助收银支付接口

Java-SDK工具

client：SaobeiApiClient<SaobeiFacePayRequest, SaobeiFacePayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/facepay
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`202`
pay_type	String	3	Y	支付方式， `010` 微信 `020` 支付宝
service_id	String	3	Y	接口类型，当前类型`016`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_ip	String	16	Y	交易终端公网IP(IPV4格式，人行侧风控主要依据，请真实填写)
device_no	String	32	N	商户侧门店编号或者终端设备号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	Y	终端流水号，可填写商户系统的业务订单号，多次请求时不可使用同一个值
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
auth_no	String	4096	Y	微信、支付宝人脸凭证（微信为 face_code值，支付宝为ftoken值）
out_trade_no	String	32	N	扫呗订单号，来自 `自助收银SDK调用凭证获取接口` ，仅微信刷脸支付必传。
open_id	String	128	N	用户标识（微信openid），用于调起微信刷脸SDK
total_fee	String	12	Y	金额，单位分
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。`禁止使用+，空格，/，?，%，#，&，=，【这几类特殊符号`
attach	String	128	N	附加数据，原样返回
custom_store_id	String	32	N	外部自定义门店编号,透传
official_store_id	String	32	N	支付宝和微信系统官方门店编号，透传
device_type	String	2	N	新增字段，解决不同刷脸设备不需要传产品协议问题设备类型，1支付宝自助收银设备【传协议】、2微信自助收银设备、3支付宝蜻蜓设备、 4微信青蛙刷脸设备 5银联刷脸设备6.支付宝海马S1离线刷脸
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码： `01` 成功， `02` 失败，响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“预支付请求成功”，“预支付请求失败”等
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页
result_code	String	2	N	业务结果： `01` 成功， `02` 失败, `03` 支付中
pay_type	String	3	N	支付方式， `010` 微信， `020` 支付宝
merchant_name	String	40	N	商户名称
merchant_no	String	15	N	商户号
terminal_id	String	8	N	终端号
device_no	String	32	N	商户侧门店编号或者终端设备号,`请先与运营同事确认是否在扫呗平台配置过映射，若没有配置映射，请勿传值，否则支付会报错。`
terminal_trace	String	32	N	终端流水号，填写商户系统的订单号
terminal_time	String	14	N	终端交易时间，yyyyMMddHHmmss，全局统一时间格式
total_fee	String	12	N	金额，单位分
receipt_fee	String	12	N	商家应结算金额,单位分
buyer_pay_fee	String	12	N	买家实付金额（分）
platform_discount_fee	String	12	N	平台优惠金额（分）
merchant_discount_fee	String	12	N	商家优惠金额（分）
end_time	String	128	N	支付完成时间
out_trade_no	String	32	N	扫呗订单号
order_body	String	128	N	订单描述（官方账单里显示为商品名称）
attach	String	128	N	附加数据，原样返回
user_id	String	32	N	付款方用户id，“微信openid”、“支付宝账户”、“qq号”等，返回时不参与签名
sub_openid	String	32	N	子商户appid下用户唯一标识，如需返回则请求时需要传sub_appid
channel_trade_no	String	32	N	通道订单号，微信订单号、支付宝订单号等
channel_order_no	String	64	N	银行渠道订单号，微信支付时显示在支付成功页面的条码，可用作扫
bank_type	String	16	N	银行类型，采用字符串类型的银行标识。微信官方提供：银行类型对照表
promotion_detail	String	6000	N	本交易支付时使用的所有优惠券信息，单品优惠功能字段，详情见《优惠字段说明》

4.15交易实时同步

应用场景

当商户使用我们的产品（如台卡、pos等硬件设备），但不走我们的支付接口时，如果想要在设备完成收款后，使用方得到交易数据，可按照该接口要求，编写接收回调地址，提供给扫呗侧配置（需运营同事提邮件配置申请）。设备收款后，扫呗侧会根据配置的推送内容，将支付结果作为参数推送到商户提供的回调地址上，商户需要接收处理，并按规范返回应答，返回格式：{"return_code":"01","return_msg":"success"}。

❗注意：

交易实时同步是基于代理商配置，会推送代理商下所有商户的所有交易和退款。

接收到推送报文后，需在3s内返回响应结果。

在订单状态不明或者没有收到支付结果通知的情况下，建议商户主动调用【查询接口】确认订单状态。

接口开发完后，可将地址提供给技术支持人员，由技术人员配合进行联调验证，并告知运营同事提交配置申请邮件，需提供代理商名称以及交易实时同步地址。

扫呗聚合支付平台第三方回调通知接口目前仅支持 HTTPs 1.1 通信协议 TLSv1.2 加密套件，非必要情况下可使用http地址接收

协议要求

Method：POST
Content-Type：application/json(文本格式的json)

通知参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值240
card_type	String	2	N	用户银联卡类型 0 储蓄卡， 1 信用卡， 2 未知
merchant_no	String	15	Y	商户号
merchant_name	String	40	Y	商户名称
terminal_id	String	8	Y	终端号
terminal_time	String	14	Y	终端交易时间，yyyyMMddHHmmss，全局统一时间格式（01时参与拼接）
terminal_trace	String	32	Y	终端流水号，此处传商户发起预支付或公众号支付时所传入的交易流水号
out_trade_no	String	32	Y	扫呗订单号
out_refund_no	String	32	Y	退款订单号
total_fee	String	12	Y	订单金额，单位分
pay_type	String	3	Y	支付方式： 010 微信， 020 支付宝， 030 刷银行卡， 060 qq钱包， 080 京东钱包， 090 口碑， 100 翼支付， 110 银联二维码
end_time	String	14	Y	支付完成时间，yyyyMMddHHmmss，全局统一时间格式
attach	String	128	Y	附加数据，原样返回
user_id	String	32	Y	付款方用户id，“微信openid”、“支付宝账户”、“qq号”等
channel_trade_no	String	32	Y	微信订单号、支付宝订单号等
channel_order_no	String	32	N	收单通道侧订单号。推送版本配置240时返回
pay_status_code	int	2	Y	支付状态， 1 支付成功， 2 支付失败， 3 支付中， 4 已撤销， 5 退款成功， 6 退款失败
~~sub_openid~~	~~String~~	32	N	~~子商户appid下用户唯一标识，如需返回则请求时需要传sub_appid~~
order_body	String	128	N	订单描述,显示在消费者账单详情页面的商品信息。
receipt_fee	String	12	N	商家应结算金额,单位分
buyer_pay_fee	String	12	N	买家实付金额（分）
platform_discount_fee	String	12	N	平台优惠金额（分）
merchant_discount_fee	String	12	N	商家优惠金额（分）
bank_type	String	16	N	银行类型，采用字符串类型的银行标识。微信官方提供：银行类型对照表
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

4.16收单对帐单下载

应用场景：

商户可以通过该接口下载前一天的交易明细，进行核单或者数据分析筛选。比如掉单、系统错误等导致商户侧和微信侧数据不一致，通过对账单核对后可校正支付状态。

❗注意：

对账单只能获取生产环境数据，测试环境测试数据无法获取。

有对账单下载需求的机构，请先联系利楚商务开通机构号，并开启对账单下载功能。

只能下载“对账单下载”功能开启后的对账单，无法下载未开启功能之前的对账单。

未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中，跟原支付单订单号一致；

接口不能下载当天的对账单，在次日9点启动生成前一天的对账单，建议商户10点后再获取；只能下载三个月以内的账单。

目前只允许以机构为单位的对账单下载，从对账单中解析单个商户的对账单。

下载地址

格式：https://example.com/order/day/inst_no/key_sign/inst_no_day.txt
Method：GET

请求路径中example.com只是个示例，请联系对接人员获取真实域名(请勿使用支付接口或者商户接口域名)。请求路径中除了/、order和.txt，其它全部是变量名，在实际请求中需要替换成变量的值，示例如下：

https://example.com/order/20170208/00000001/a988b4b22559754ffe5c32e227872a7a/00000001_20170208.txt

签名算法

MD5加密，utf-8格式转小写,加密后得到key_sign的值，并替换url中的key_sign。
String key_sign = MD5.encode(day=日期值&inst_no=机构号值&key=机构密钥值);

签名参数：

参数名称	说明
day	日期，yyyyMMdd，例如：`20170208`
inst_no	机构号
key	机构号对应的令牌

若返回以上内容，并不是说密钥不对，提示是未找到对账单文件，请检查是否开启对账单下载功能，或者检查拼接的地址是否正确。

示例数据：

852105399000001,34336428,2021-12-14 19:45:13,,1,0,0,1,1,6,1,343364289921621121419450800017,,2905925869105,154553154,2021-12-14,o12Tt4h_4jwghavcSYoN5VjLWNDE,0,3,0,1,1,0,微信小程序订单支付,,OTHERS,测试门店,1

请求结果中，每一行表示一条交易记录，记录中各参数以,号分隔。各参数含义如下所示：

商户号，终端号，交易时间，退款完成时间，交易金额（分），手续费金额（分），退款金额（分），结余金额（分），支付方式，支付类型，交易状态，交易单号，退款原单号，终端流水号，渠道订单号，交易日期，用户标识，银行卡类型，附加数据，商家优惠金额（分），商家实收金额（分），用户实付金额（分），平台优惠金额（分）,订单备注，自定义设备编号，支付银行标识，门店名称，通道类型

以下为参数解释：

参数名称	说明
支付方式	1微信 2支付宝 3银行卡 4 现金 5无卡支付 6qq钱包 7百度钱包 8京东钱包 10翼支付 11云闪付 12龙支付 16数字人民币 17招行支付 18微企付 19支付宝商转 20微信B2b
交易金额	下单传入的订单金额，单位分
支付类型	1付款码支付（或银行卡刷卡），2扫码支付，3公众号支付，4wap支付， 5app支付，6小程序支付，7刷脸支付
交易状态	支付状态，支付成功1，已撤销4, 退款成功5
手续费	支付成功为正值退款为负值，单位分
结余金额	到账金额：商家实收-手续费，单位分
银行卡类型	0储蓄卡，1信用卡
商家优惠优惠金额	订单金额-到账金额+手续费金额，单位分,特指商户出资的
用户实付金额	消费者实际支付金额，若无优惠，默认是订单金额；单位分；
平台优惠优惠金额	平台活动补贴金额，支付宝红包，立减金，预充值类营销活动补贴金额，商家正常到账。单位分；
订单备注	客户交易上送的订单order_body信息,未上传平台会有默认值
自定义设备编号	自定义设备编号device_no字段
支付银行标识	消费者交易的银行卡标识，如ICBC_DEBIT、PAB_DEBIT。微信官方提供：银行类型对照表
门店名称	交易门店名称
通道类型	通道类型， 1：利楚直连， 2：富友，4：随行付，6：乐刷，其它值对应通道，可联系技术人员获取。

4.17获取服务商公众号下openid

应用场景

商户没有自己的公众号，需要使用公众号支付时，使用该接口可以获取服务商公众号appid下的用户标识，并调用公众号支付接口

❗注意：

该接口用于服务商模式的公众号支付，即4.3公众号支付接口不传appid，默认使用服务商appid时，4.3公众号支付接口中所需的open_id通过该接口获取。

使用说明

该接口的key_sign参数生成规则为：
key_sign=md5(merchant_no=xxxxxx&redirect_uri=xxxxxx&terminal_no=xxxxxx&access_token=xxxxxx);
redirect_uri若有参数，需要在url地址后面+?+参数名+参数值(避免格式不对无法解析)，若跳转时报错403forbidden，请提供收银台的具体URL（不包含GET参数）给对接人员配置白名单，否则将无法正常进入收银台
请求授权的示例链接为：
https://xxxxxx/wx/jsapi/authAccessToken?merchant_no=xxxxxx&terminal_no=xxxxxx&redirect_uri=https%3A%2F%2Fwww.example.com%2Fpay.html%3Fa%3D123&key_sign=xxxxxx
成功授权后回到收银台时的地址：
https://www.example.com/pay.html?openid=xxxxxxxxxxxxxxxxxxxx

API请求

URL：/wx/jsapi/authAccessToken
Method：GET

请求参数

参数名称	类型	长度	必填	说明
merchant_no	String	15	Y	商户号
terminal_no	String	8	Y	终端号
redirect_uri	String	255	Y	您的收银台的完整路径，并urlEncode（get请求拼接需要urlEncode，签名拼接不需要urlEncode），带参数则会原样返回
pay_type	String	3	N	支付方式，不传默认获取微信 `010` 微信 `110` 云闪付 `090` 抖音支付
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
openid	String	64	Y	微信（云闪付）公众号用户唯一标识，成功授权后取得，用于微信支付JSAPI接口统一下单
access_token	String	512	Y	access_token是公众号的全局唯一接口调用凭据

4.18付款码查询 OPENID 接口

应用场景

通过付款码查询用户标识后，使用标识在自有会员系统内查询会员信息，实现无感会员支付。

❗注意：

通过授权码查询用户openid后，该授权码只能由此商户号发起扣款，直至授权码更新。

Java-SDK工具

client：SaobeiApiClient<SaobeiAuthCodeOpenidRequest, SaobeiAuthCodeOpenidResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
方法：client.execute方法
使用说明：3.2 SDK使用说明

API请求

URL：/pay/open/authcodetoopenid
Method：POST

请求参数

参数名称	类型	长度	必填	说明
pay_ver	String	3	Y	接口内业务逻辑兼容号，可用值`201`
pay_type	String	3	Y	支付方式: `010` 微信， `020` 支付宝， `000` 自动识别
service_id	String	3	Y	接口类型，当前类型`080`
merchant_no	String	15	Y	商户号
terminal_id	String	8	Y	终端号
terminal_trace	String	32	Y	终端流水号，填写商户系统的订单号
terminal_time	String	14	Y	终端发起时间，yyyyMMddHHmmss，全局统一时间格式
auth_no	String	128	Y	微信、支付宝等支付方式里的付款码（条形码或者二维码对应的数字）
sub_appid	String	32	N	微信子商户appid（可返回appid下对应的用户标识），支付宝不需要传。
sence_no	String	128	N	支付宝条码解码时必填，用于标识这笔解码请求，且需要与付款码支付接口中的sence_no保持一致，否则支付时会提示需刷新条码
attach	String	128	N	附加数据,原样返回
key_sign	String	32	Y	签名验证串《2.4签名算法》签名测试页

响应参数

参数名称	类型	长度	必填	说明
return_code	String	2	Y	响应码： `01` 成功， `02` 失败。响应码仅代表通信状态，不代表业务结果
return_msg	String	128	Y	返回信息提示，“查询成功”，“请求受限”等
result_code	String	2	N	业务结果： `01` 成功 `02` 失败
pay_type	String	3	N	支付方式， `010` 微信，`020` 支付宝
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，全局统一时间格式
appid	String	32	N	服务商的公众账号ID
sub_appid	String	32	N	子商户的appid
openid	String	128	N	用户在服务商appid下的唯一标识，或支付宝下的唯一标识user_id
sub_openid	String	128	N	用户在子商户appid下的唯一标识
attach	String	128	N	附加数据,原样返回
key_sign	String	32	N	签名验证串《2.4签名算法》签名测试页

开发指引

API

一、接入必看

二、接入指南

2.1协议规则

2.2数据格式

2.3判断逻辑

2.4签名算法

2.5支付流图

三、支付接口SDK

3.1 SDK下载

3.1.1 SDK引入方式参考

3.2 SDK使用说明

3.2.1 demo使用示例

四、支付相关API

4.1付款码支付（B扫C）

4.2扫码预支付（已停用）

4.3公众号下单接口

4.4小程序下单接口

4.5支付查询

4.6退款申请

4.7撤销交易

4.8关闭订单

4.9退款订单查询

4.10回调通知

4.11聚合码接口（C扫B）

4.12WAP收银台

4.13(刷脸)自助收银SDK调用凭证获取接口

4.14(刷脸)自助收银支付接口

4.15交易实时同步

4.16收单对帐单下载

4.17获取服务商公众号下openid

4.18付款码查询 OPENID 接口