支付2.0接口

更新时间:2024-04-18 09:17:17

更新日志:

日期 章节 内容
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(银联侧风控主要依据,请真实填写)

一、接入必看

请仔细阅读第二章接入指南,尤其是2.3判断逻辑2.4签名算法
测试环境域名:http://test.lcsw.cn:8045/lcsw+urlhttp://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签名算法

httpclient方式发起的接口请求,请求和接收数据均需要校验签名。签名测试工具
**注意:使用java SDK对接的接口,不需要做签名,SDK会自动处理。**
拼接串说明
接口中每一个字段(key_sign字段除外),以字典顺序(字母顺序)排序之后,按照a=value1&b=value2.....&access_token="密钥token"的顺序,进行拼接。对得到的字符串进行MD5签名/验签;
备注:赋值的空字符串参与签名;如"attach": "",需要拼接&attach=&

示例请求参数

{
"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支付流图

image.pngimage.png

三、扫呗SDK

3.1 java SDK

更新时间 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接口

注意:

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

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

    若未重新赋值,会报"终端信息不存在或已关闭!".
    切换到正式环境时,删除这行代码。

  • 2、其它语言建议使用http请求的方式调用api接口,该方式不受语言限制,可跨平台调用

    3.1.1 测试demo

    TestMain

3.2 SDK支核一体接口

如果有核销支付券和商家券需求的合作方,再使用SDK对接条码支付接口时,建议使用以下方法,支持自动核销支付券和商家券。
SaobeiBarcodePayResponse response = client.executePayUseCoupon(requst,true);

3.2.1 SDK快速示例

package com.saobei;

import com.alibaba.fastjson.JSON;
import com.saobei.open.sdk.model.requst.trade.SaobeiBarcodePayRequest;
import com.saobei.open.sdk.model.response.trade.SaobeiBarcodePayResponse;

public class Saobei {
    public static final String PAY_VER = "110";//版本号
    public static final String ACCESS_TOKEN = "";//支付秘钥,扫呗分配
    public static final String MERCHANT_NO = "";//商户号,扫呗分配
    public static final String TERMINAL_ID = "";//终端号,扫呗分配

    public static void main(String[] args) throws Exception {
        barcodepay();//付款码支付
    }

    //付款码支付
    private static void barcodepay() throws Exception {

        try {
            //创建client
            SaobeiApiClient<SaobeiBarcodePayRequest, SaobeiBarcodePayResponse> client = new DefaultSaobeiApiClient<>(ACCESS_TOKEN);
            //创建requst
            SaobeiBarcodePayRequest requst = new SaobeiBarcodePayRequest();
            requst.setPay_ver(PAY_VER);//版本号
            requst.setPay_type("020");//支付方式,010微信,020 支付宝,060qq钱包,080京东钱包,090口碑,100翼支付,110银联二维码,140和包支付(仅限和包通道),000自动识别类型
            requst.setService_id("010");//接口类型,当前类型010
            requst.setMerchant_no(MERCHANT_NO);//商户号
            requst.setTerminal_id(TERMINAL_ID);//终端号
            requst.setTerminal_trace("202003252204310000");//终端流水号,填写商户系统的订单号
            requst.setTerminal_time("20200325220431");//终端交易时间,yyyyMMddHHmmss,全局统一时间格式
            requst.setAuth_no("282216345385848623");//授权码
            requst.setTotal_fee("1");//金额,单位分
            //发送请求
            System.out.println("请求报文:" + JSON.toJSONString(requst));
          //支持自动核券的条码支付接口,有支付即核销需求的客户建议使用该方法
          SaobeiBarcodePayResponse response = client.executePayUseCoupon(requst,true);
            System.out.println("返回报文:" + JSON.toJSONString(response));
            //处理响应或异常
            if ("01".equals(response.getReturn_code())&&"01".equals(response.getResult_code())) {
                System.out.println("调用成功");
            } else {
                System.err.println("调用失败,原因:" + response.getReturn_msg());
            }
        } catch (Exception e) {
            System.err.println("调用遭遇异常,原因:" + e.getMessage());
            throw new RuntimeException(e.getMessage(), e);
        }
    }
}

四、支付相关API

4.1付款码支付

Java-SDK工具

  • client:SaobeiApiClient<SaobeiBarcodePayRequest, SaobeiBarcodePayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.executePayUseCoupon方法
  • 参数说明:use_coupon字段 值:true:用券 false:不用券
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/barcodepay
  • Method:POST

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

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201202
pay_type String 3 Y 支付方式,
010 微信,
020 支付宝,
060 qq钱包,
100 翼支付,
110 银联二维码,
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格式 ,人行侧风控主要依据,请真实填写)
terminal_location String 128 N 受理终端设备实时经纬度信息,格式为(纬度/经度):+31.2579921/-120.729388
+表示北纬、东经,
-表示南纬、西经。

经度是向东到180°或向西到180°
纬度是0至90度之间
device_no String 32 N 商户侧门店或者终端编号,请先与运营同事确认是否在扫呗平台配置过映射,若没有配置映射,请勿传值,否则支付会报错。
terminal_trace String 32 Y 终端流水号,填写商户系统的支付订单号,不可重复
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
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_type010020110时,可选填此字段《字段说明》
goods_tag String 32 N 微信侧订单优惠标记,代金券或立减优惠功能的参数(字段值:csbld
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 支付宝外部业务号,用于标识这笔解码请求,使用最优券查询接口后必传
user_info String 64 N 会员卡号,详见营销中台,会员体系
key_sign String 32 Y 2.4签名算法签名测试页

goods_detail的内容说明

参数名称 类型 必填 说明
goods_id String Y 商品编号
goods_name String Y 商品名称
quantity String Y 商品数量,需为整数,不要带小数点
price String Y 商品单价,单位为分(注:pay_type010时,此字段类型为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失败 ,
03支付中,
99该条码暂不支持支付类型自动匹配
pay_type String 3 N 支付方式:
010微信,
020 支付宝,
060qq钱包,
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 N 通道订单号,微信订单号、支付宝订单号等
channel_order_no String 64 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聚合码支付接口
Java-SDK工具

  • client:SaobeiApiClient<SaobeiPrePayRequest, SaobeiPrePayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/prepay
  • Method:POST

请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201
pay_type String 3 Y 支付方式,
010微信,
020 支付宝,
060qq钱包,
100翼支付
service_id String 3 Y 接口类型,当前类型011
merchant_no String 15 Y 商户号
terminal_id String 8 Y 终端号
terminal_ip String 16 Y 收银机、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 256 N 外部系统通知地址4.10回调通知
attach String 128 N 附加数据,原样返回
goods_detail String 2048 N 订单包含的商品列表信息,Json数组格式。pay_type010020,可选填此字段
goods_tag String 32 N 微信订单优惠标记,代金券或立减优惠功能的参数(字段值:csbld
custom_store_id String 32 N 微信门店编号和支付宝外部自定义门店编号,透传。微信对应scene_info(场景信息)中的门店id。 支付宝自定义门店编号不能随便传,在确认门店编号存在的情况下传值,否则影响支付
official_store_id String 32 N 支付宝官方门店编号,透传
key_sign String 32 Y 2.4签名算法签名测试页

goods_detail的内容说明

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

响应参数

参数名称 类型 长度 必填 说明
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微信,
020 支付宝,
060qq钱包,
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公众号预支付(统一下单)

Java-SDK工具

  • client:SaobeiApiClient<SaobeiJsPayRequest, SaobeiJsPayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/jspay
  • Method:POST

openid获取方式如下:
微信公众号


支付宝生活号

注:请使用该接口返回的参数按照如下文档完成支付(**返回的参数不能修改**,文档如下:
微信公众号


支付宝生活号

请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201
pay_type String 3 Y 支付方式,
010微信,
020支付宝,
060qq钱包,
100翼支付,
110银联云闪付
service_id String 3 Y 接口类型,当前类型012
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,全局统一时间格式
total_fee String 10 Y 金额,单位分,小于2147483647
sub_appid String 16 Y 传商户自己的公众号appid,微信支付时此参数必传。(即获取open_id所使用的appid)。
open_id String 128 Y 用户标识(微信openid,支付宝userid),pay_type010020时必填
order_body String 128 N 订单描述,显示在订单详情页面,禁止使用+,空格,/,?,%,#,&,=,【这几类特殊符号
notify_url String 256 N 外部系统通知地址4.10回调通知
attach String 128 N 附加数据,原样返回
goods_detail String 2048 N 订单包含的商品列表信息,Json数组格式。pay_type010020,可选填此字段
goods_tag String 32 N 订单优惠标记,代金券或立减优惠功能的参数(字段值:csbld
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的内容说明

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

响应参数

参数名称 类型 长度 必填 说明
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微信,
020支付宝,
060qq钱包,
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
token_id String 32 N qq钱包公众号支付
redirect_uri String 512 N 云闪付支付或一些银行通道会返回,若该字段有值,请取该字段的链接打开。

4.4小程序支付接口

Java-SDK工具

  • client:SaobeiApiClient<SaobeiMiniPayRequest, SaobeiMiniPayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/minipay
  • Method:POST

注意:

  • 请求完这个接口得到的返回参数直接去调微信小程序/支付宝小程序的js支付(参见下方描述),接口返回的参数值一个都不能修改
  • 若报“预支付失败sub_mch_id与sub_appid不匹配”,请联系运营同事,并提供小程序appid,在正式商户的对应通道关注配置里添加appid,appid主体需与商户主体一致,否则无法配置。
  • 该接口为预支付接口,还未进行支付,故该接口不返回优惠字段。优惠字段会在支付完成后,通过回调接口返回,或者通过查询接口获取。


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


支付宝小程序

请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201202
pay_type String 3 Y 支付方式,010微信,020支付宝
service_id String 3 Y 接口类型,当前类型015
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,全局统一时间格式
total_fee String 10 Y 金额,单位分,小于2147483647
sub_appid String 16 Y 传商户自己的小程序appid,微信支付时此参数必传。(即获取open_id所使用的appid)。
open_id String 128 Y 用户标识(微信openid,支付宝userid),pay_type010020时必填
timeout_express String 3 N 订单交易关闭时间(单位分,不传默认120)。 如果小程序有设置订单失效时间的,建议和订单失效时间设置一致
goods_detail String 2048 N 订单包含的商品列表信息,Json数组格式。pay_type010020时,可选填此字段,详情见《字段说明》
goods_tag String 32 N 订单优惠标记,代金券或立减优惠功能的参数(字段值:csbld
order_body String 128 N 订单描述,显示在订单详情页面,禁止使用+,空格,/,?,%,#,&,=,【这几类特殊符号
notify_url String 256 N 外部系统通知地址4.10回调通知
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的内容说明

参数名称 类型 长度 必填 说明
goods_id String 32 Y 商品编号
goods_name String 128 Y 商品名称
quantity String 11 Y 商品数量,需为整数,不要带小数点
price String 11 Y 商品单价,单位为分(注:pay_type010时,此字段类型为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支付查询

Java-SDK工具

  • client:SaobeiApiClient<SaobeiTradeQueryRequest, SaobeiTradeQueryResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/query
  • Method:POST

订单查询,单号传递有两种方式,二选一,推荐优选方式一:

  • 方式一: 使用利楚订单号进行查询:用支付下单接口返回的out_trade_no值,传在支付查询接口的out_trade_no字段。
  • 方式二:使用商户自己订单号进行查询:用支付下单接口请求里的terminal_trace字段传在查询接口pay_trace字段,和支付下单请求里的terminal_time字段传在查询接口的pay_time字段,联合作为查询条件,此时out_trade_no字段的值需赋值为""空。

注意:建议最多查询15次,每次间隔5s。付款码支付的情况下,若查询多次还是支付中,可在确定没有资金损失的情况下调用4.7撤销交易接口(支付成功的会退款),关闭订单。

请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201202
pay_type String 3 Y 支付方式:
010微信,
020 支付宝,
060qq钱包,
100翼支付,
110银联二维码,
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 O 当前支付终端流水号,与pay_time同时传递
pay_time String 14 O 当前支付终端交易时间,yyyyMMddHHmmss,全局统一时间格式,与pay_trace同时传递
out_trade_no String 64 O 订单号,查询凭据,可填平台订单号、微信订单号、支付宝订单号、银行卡订单号任意一个(使用方式二查询订单时,该字段需赋值为""空)
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 支付宝,
060qq钱包,
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 N 通道订单号,微信订单号、支付宝订单号等
channel_order_no String 64 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退款申请

Java-SDK工具

  • client:SaobeiApiClient<SaobeiTradeRefundRequest, SaobeiTradeRefundResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/refund
  • Method:POST
  • 订单退款,单号传递两种方式,二选一,推荐优选方式一:
  • 方式一:使用利楚订单号进行退款:用支付下单接口返回的out_trade_no值,传在退款申请接口的out_trade_no字段。
  • 方式二:使用商户自己订单号进行退款:用支付下单接口请求里的terminal_trace字段传在退款申请接口里的pay_trace字段,和支付下单请求里的terminal_time字段传在退款申请接口的pay_time字段,联合作为唯一条件。

请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201
pay_type String 3 Y 支付方式,
010微信,
020 支付宝,
060qq钱包,
100翼支付,
110银联二维码,
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 终端退款流水号,填写商户系统的退款流水号,每次请求新生成,需唯一
terminal_time String 14 Y 终端退款时间,yyyyMMddHHmmss,全局统一时间格式,每次请求新生成
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 Y 订单号,查询凭据,平台订单号、微信订单号、支付宝订单号任意一个
pay_trace String 32 N 支付请求里的终端流水号,与pay_time同时传递
pay_time String 14 N 支付请求里的终端交易时间,yyyyMMddHHmmss,全局统一时间格式,与pay_trace同时传递
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 支付宝,
060qq钱包,
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 退商家应结算金额,单位分
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_trade_no String 32 N 平台唯一订单号
out_refund_no String 32 N 平台唯一退款单号

注意:

  • 需要商户当前账户内有大于退款金额的余额,否则会造成余额不足,退款失败;
  • 退款时限:富有通道:180天、官方通道:1年、网商通道:90天。

4.7撤销交易(只针对付款码支付)

Java-SDK工具

  • client:SaobeiApiClient<SaobeiTradeCancelRequest, SaobeiTradeCancelResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/cancel
  • Method:POST

    • 订单撤销,单号传递两种方式,二选一,推荐优选方式一:
  • 方式一:用支付下单接口返回的out_trade_no值,传在撤销交易接口的out_trade_no字段。
  • 方式二:用支付下单接口请求里的terminal_trace字段传在撤销交易接口pay_trace字段,和支付下单请求里的terminal_time字段传在撤销交易接口的pay_time字段。

注意:撤销接口会对已经支付的订单进行退款,程序请勿自动调用该接口,需人工处理确认确实可撤销后再,手动调用该接口。
请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201
pay_type String 3 Y 支付方式:
010微信,
020支付宝,
040现金,
060qq钱包,
100翼支付,
110银联二维码,
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 终端流水号(socket协议:长度为6位,Http协议:长度为32位),每次请求新生成,需唯一
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式,每次请求新生成
out_trade_no String 32 N 平台唯一订单号,优先使用订单号out_trade_no发起撤销,在out_trade_no获取异常的情况,可使用当前支付请求的终端交易流水号pay_trace和终端交易时间pay_time发起撤销
pay_trace String 32 N 支付请求里的终端流水号,与pay_time同时传递
pay_time String 14 N 支付请求里的终端交易时间,yyyyMMddHHmmss,全局统一时间格式,与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现金,
060qq钱包,
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关闭订单

Java-SDK工具

  • client:SaobeiApiClient<SaobeiTradeCloseRequest, SaobeiTradeCloseResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/close
  • Method:POST

订单关单,单号传递两种方式,二选一,推荐优选方式一:

  • 方式一:使用利楚订单号进行关单:用支付下单接口返回的out_trade_no值,传在关闭订单接口的out_trade_no字段。
  • 方式二:使用商户自己订单号进行关单:用支付下单接口请求里的terminal_trace字段传在关闭订单接口的pay_trace字段,和支付下单请求里的terminal_time字段传在关闭订单接口的pay_time字段。

注:条码支付的订单不支持调用关闭订单接口

请求参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201
pay_type String 3 Y 支付方式:
010微信,
020支付宝,
000自动识别类型
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 终端流水号(socket协议:长度为6位,Http协议:长度为32位),每次请求新生成,需唯一
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式,每次请求新生成
out_trade_no String 32 N 平台唯一订单号,优先使用订单号out_trade_no发起撤销,在out_trade_no获取异常的情况,可使用当前支付请求的终端交易流水号pay_trace和终端交易时间pay_time发起撤销
pay_trace String 32 N 支付请求里的终端流水号,与pay_time同时传递
pay_time String 14 N 支付请求里的终端交易时间,yyyyMMddHHmmss,全局统一时间格式,与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成功,表示关单成功,此笔订单不能再发起支付;
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退款订单查询

Java-SDK工具

  • client:SaobeiApiClient<SaobeiTradeQueryRefundRequest, SaobeiTradeQueryRefundResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法
  • demo下载:3.1.1 测试demo

http请求

  • URL:/pay/open/queryrefund
  • Method:POST

订单退款结果查询,单号传递两种方式,二选一,推荐优选方式一:

  • 方式一:用退款申请接口返回的out_refund_no值,传在退款订单查询接口的out_refund_no字段。
  • 方式二:用退款申请接口请求里的terminal_trace字段传在退款查询接口里的pay_trace字段,和退款申请请求里的terminal_time字段传在退款查询接口的pay_time字段 联合作为唯一条件。
参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201
pay_type String 3 Y 支付方式:
010微信,
020 支付宝,
060qq钱包,
100翼支付,
110银联二维码,
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 Y 平台唯一退款订单号
pay_trace String 32 O 退款申请接口里的终端退款流水号(
terminal_trace),与pay_time同时传递
pay_time String 14 O 退款申请接口里的终端交易时间(
terminal_time),yyyyMMddHHmmss,全局统一时间格式,与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 签名, 拼装所有必传参数+令牌,UTF-8编码,32位md5加密转换《2.4签名算法签名测试页
result_code String 2 N 业务结果:01成功 ,02失败
pay_type String 3 N 支付方式:
010微信,
020 支付宝,
060qq钱包,
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 N 通道订单号,微信订单号、支付宝订单号等
channel_order_no String 64 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、后台通知交互时,如果收到商户的应答超时,会判定本次通知失败,重新发送通知,直到成功为止(在通知一直不成功的情况下,会发起多次通知,不保证通知最终一定能成功。应答超时的情况,还有可能导致商户收到重复的回调通知,建议控制应答回复时间在3s内,避免出现重复通知)
2、在订单状态不明或者没有收到支付结果通知的情况下,建议商户主动调用【查询接口】确认订单状态。

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

推送参数

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值201202
return_code String 2 Y 响应码:01成功 ,02失败,响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示,“签名失败”,“参数格式校验错误"等
result_code String 2 Y 业务结果:01成功 ,02失败
pay_type String 3 Y 支付方式:
010微信,
020 支付宝,
060qq钱包,
100翼支付,
110云闪付
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 成功 ,02 失败
return_msg String 128 Y 返回信息提示,“签名失败”,“参数格式校验错误"等

以上为响应参数

4.11聚合码接口

Java-SDK工具

  • client:SaobeiApiClient<SaobeiQrPayRequest, SaobeiQrPayResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法

http请求

  • URL:/pay/open/qrpay
  • Method:POST

注意:

  1. 该接口调用完后只是返回了一个链接。使用有两种,方式一:把链接转换成二维码后,扫码发起支付。方式二:在微信、支付宝内的H5页面中跳转链接打开。
  2. 在没有扫码发起支付之前,如果调用查询接口,是查询不到订单信息的。需要扫码后,发起支付(点了支付按钮的),才能使用终端流水号和终端交易时间或者扫呗订单号,调用4.5支付查询接口发起订单查询。
  3. 若报“当前页面的URL未注册: http://wxpay.lcsw.cn/test/pay_sdk.html ”,请联系运营同事,在正式商户上对应通道的关注配置里,添加支付授权目录地址:http://wxpay.lcsw.cn/test/
参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,当前版本201
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 终端流水号,填写商户系统的订单号,不可重复
terminal_time String 14 Y 终端交易时间,yyyyMMddHHmmss,全局统一时间格式
total_fee String 12 Y 金额,单位分
order_body String 128 N 订单描述,禁止使用+,空格,/,?,%,#,&,=,【这几类特殊符号
notify_url String 256 N 外部系统通知地址4.10回调通知
attach String 128 N 附加数据,原样返回
timeout_express String 4 N 订单相对超时时间。单位s,从交易创建时间开始计算。该笔订单允许的最晚付款时间,逾期将关闭交易。取值范围:1~7200的整数,不传默认7200s
repeated_trace String 2 N 是否允许重复扫码
1:不允许重复扫码;
0或不传:允许重复扫码
key_sign String 32 Y 签名字符串,拼装所有传递参数(字典序)+令牌,UTF-8编码,32位md5加密转换《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 签名字符串,拼装所有传递参数(字典序)+令牌,UTF-8编码,32位md5加密转换《2.4签名算法签名测试页

以上字段在return_code为01时返回,返回时参与签名

4.12WAP收银台

该收银台仅支持:微信、支付宝、云闪付、QQ钱包、翼支付内打开,不支持浏览器、三方应用或小程序内打开。
Java-SDK工具

  • client:SaobeiApiClient<SaobeiWapPayRequest, String> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法

http请求

  • URL:/open/wap/110/pay
  • Method:GET

请求参数

参数名称 类型 长度 必填 说明
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_body String 128 N 订单描述,禁止使用+,空格,/,?,%,#,&,=,【这几类特殊符号
notify_url String 256 N 外部系统通知地址,必须urlencode
(get请求拼接需要urlencode,签名拼接不需要urlencode)4.10回调通知
auto_pay String 1 N 自动点击支付按钮,1自动,0或不传手动
attach String 128 N 附加数据,原样返回
repeated_trace String 2 N 是否允许订单重复,1:不允许重复,0或不传:允许重复
key_sign String 32 Y 签名字符串,字典序拼装所有非空参数+令牌,32位md5加密转换《2.4签名算法签名测试页

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

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

微信刷脸说明:
https://pay.weixin.qq.com/wiki/doc/wxfacepay/develop/android/facepay.html#微信刷脸支付场景说明
image.png
第一步:使用官方流程中的第一步和第二步中的获取数据接口,得到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#支付宝刷脸支付场景说明
image.png
按照官方流程:
第一步:使用官方“获取刷脸所需的设备信息”接口(接口所需值由设备提供),得到返回结果。
第二步:将第一步返回结果对象转换成json传入到本文档的“自助收银sdk调用凭证获取”接口的rawdata字段,从而得到authinfo值(对应的是支付宝返回的zim_id的值),
第三步:调用官方“唤起人脸识别”接口,将上一步返回的authinfo字段的值传入到接口所需的zimId字段,得到返回值ftoken。
第四步:使用上一步返回的ftoken字段,调用的本文档中“(刷脸)自助收银支付接口”传在auth_no字段,这样就可以完成刷脸支付。

两个刷脸支付流程均为四步,第一和第三步调用官方接口,第二和第四步调用扫呗

Java-SDK工具

  • client:SaobeiApiClient<SaobeiFaceInfoRequest, SaobeiFaceInfoResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法

httpclient请求

  • 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 签名字符串,拼装所有传递参数(字典序)+令牌,UTF-8编码,32位md5加密转换《2.4签名算法签名测试页

以上为请求参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码:
01 成功 ,
02 失败,响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示,“凭证获取成功”,“凭证获取失败”等
key_sign String 32 Y 签名字符串,拼装所有传递参数(字典序)+令牌,UTF-8编码,32位md5加密转换《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时返回)

以上字段在return_code01时返回,返回时参与签名

sub_mchid_info参数(pay_ver为120版本时返回):

参数名称 类型 长度 必填 说明
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方法

httpclient请求

  • 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 签名字符串,拼装所有非空参数(字典序)+令牌,UTF-8编码,32位md5加密转换《2.4签名算法签名测试页

以上为请求参数

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码:
01 成功 ,
02 失败,响应码仅代表通信状态,不代表业务结果
return_msg String 128 Y 返回信息提示,“预支付请求成功”,“预支付请求失败”等
key_sign String 32 Y 签名字符串,拼装所有非空参数(字典序)+令牌,UTF-8编码,32位md5加密转换

以上为响应参数

参数名称 类型 长度 必填 说明
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 本交易支付时使用的所有优惠券信息 ,单品优惠功能字段,详情见《优惠字段说明》

以上字段在return_code01时返回,返回时参与签名

4.15交易实时同步

应用场景
当商户使用我们的产品(如台卡、pos等硬件设备),但不走我们的支付接口时,如果想要在设备完成收款后,使用方得到交易数据,可按照该接口要求,编写接收回调地址,提供给扫呗侧配置(需运营同事提邮件配置申请)。设备收款后,扫呗侧会根据配置的推送内容,将支付结果作为参数推送到商户提供的回调地址上,商户需要接收处理,并按文档规范返回应答。 (返回格式:{"return_code":"01","return_msg":"success"})
注意:
1、后台通知交互时,如果收到商户的应答超时,会判定本次通知失败,重新发送通知,直到成功为止(在通知一直不成功的情况下,会发起多次通知,不保证通知最终一定能成功。应答超时的情况,还有可能导致商户收到重复的回调通知,建议控制应答回复时间在3s内,避免出现重复通知)
2、在订单状态不明或者没有收到支付结果通知的情况下,建议商户主动调用【查询接口】确认订单状态。
3、接口开发完后,可将地址提供给技术支持人员,由技术人员配合进行联调验证。
注意:扫呗聚合支付平台第三方回调通知接口目前仅支持 HTTPs 1.1 通信协议 TLSv1.2 加密套件,非必要情况下可使用http地址接收

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

以下为通知参数:

参数名称 类型 长度 必填 说明
pay_ver String 3 Y 接口内业务逻辑兼容版本号,可用值230
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 通道订单号,微信订单号、支付宝订单号等
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 签名字符串,拼装所有非null参数字典序+令牌,32位md5加密转换《2.4签名算法签名测试页

以下为客户接收到通知后的应答参数:
备注:须即时响应,捕获好异常,按照
return_code="01"或者 return_code="02" 响应码返回,未按照要求的,巡查发现将被限制后续通知;

参数名称 类型 长度 必填 说明
return_code String 2 Y 响应码:
01 成功 ,
02 失败
return_msg String 128 Y 返回信息提示,“签名失败”,“参数格式校验错误"等

4.16获取access_token(openid)

  • 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 云闪付
key_sign String 32 Y 签名字符串,拼装所有必传参数(字典序)+令牌(access_token),UTF-8编码,32位md5加密转换

返回参数:

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

以上为响应参数

  • 该接口的key_sign参数生成规则为:
    key_sign=md5(merchant_no=xxxxxx&redirect_uri=xxxxxx&terminal_no=xxxxxx&access_token=xxxxxx);
  • 请求授权的示例链接为:
    https://xxxxxx/wx/jsapi/authopenid?merchant_no=xxxxxx&terminal_no=xxxxxx&redirect_uri=https%3A%2F%2Fwww.example.com%2Fpay.html&key_sign=xxxxxx
  • 成功授权授权后回到收银台时的地址:
    https://www.example.com/pay.html?openid=xxxxxxxxxxxxxxxxxxxx

注意:redirect_uri参数需要在后面+?+参数名+参数值(避免格式不对无法解析),redirect_uri参数在urlEncode前进行加密,若跳转时报错403forbidden,请提供收银台的具体URL(不包含GET参数)给对接人员配置白名单,否则将无法正常进入收银台。

4.17付款码查询 OPENID 接口

Java-SDK工具

  • client:SaobeiApiClient<SaobeiAuthCodeOpenidRequest, SaobeiAuthCodeOpenidResponse> client = new DefaultSaobeiApiClient<>(终端token密钥);
  • 方法:client.execute方法

httpclient请求

  • 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,入参sub_appid必传)
sence_no String 128 N 支付宝条码解码时必填,用于标识这笔解码请求,且需要与付款码支付接口中的sence_no保持一致,否则支付时会提示需刷新条码
attach String 128 N 附加数据,原样返回
key_sign String 32 Y 签名字符串,拼装所有传递参数(字典序)+令牌(access_token),UTF-8编码,32位md5加密转换

以上为请求参数

参数名称 类型 长度 必填 说明
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 签名字符串,拼装所有传递参数(字典序)+令牌(access_token),UTF-8编码,32位md5加密转换

以上字段在return_code01时返回

说明:

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

© 利楚商服 2020 All rights reserved.