yml/hfb_sys
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
134d6fa05e0c5ca47aa6e689f060ed6318e173cb
hfb_sys/docs/乐刷商户交易.md
T

117 KiB
Raw Blame History

API目录

分类 接口中文名 接口英文名 描述
下单接口 统一下单接口 /cgi-bin/lepos_pay_gateway
.cgi		 主扫，C扫B。消费者主动扫码。
条码支付 条码支付 /cgi-bin/lepos_pay_gateway.cgi 被扫，B扫C。消费者出示付款码被扫。
交易结果 支付结果通知 / 返回支付结果。影响推送的因素较多，建议接交易结果查询接口。
交易结果查询 /cgi-bin/lepos_pay_gateway.cg 查询交易结果
退款 退款 /cgi-bin/lepos_pay_gateway.cgi 进行退款操作
退款查询 /cgi-bin/lepos_pay_gateway.cgi 查询退款信息
退款结果通知 查看退款结果
订单关闭接口 订单关闭 /cgi-bin/lepos_pay_gateway.cgi 关闭订单
授权码 授权码查询用户openid /cgi-bin/lepos_pay_gateway.cgi 查询openid
授权码获取银联云闪付用户ID 获取云闪付用户ID
异步通知 刷卡、扫码支付异步通知

****数字签名

（1）为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。

（2）签名有两个步骤，先按一定规则拼接要签名的原始串，再选择具体的算法和密钥计算出签名结果。

（3）原始串中，字段名和字段值都采用原始值，不进行URL Encode。

（4）平台返回的应答或通知消息可能会由于升级增加参数，请验证应答签名时注意允许这种情况。

签名方法

（1）设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

（2）在stringA最后拼接上key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

签名样例

（1）假设需要传递的参数如下：

server：query_status
merchant_id：1234567890
third_order_id：12345678901
nonce_str：12345678901

（2）对参数按照key=value的格式，并按照参数名ASCII字典序排序如下

stringA=merchant_id=1234567890&nonce_str=12345678901&server=query_status&third_order_id=12345678901

（3）拼接商户秘钥key

stringSignTemp=stringA+"&key=192006250b4c09247ec02edce69f6a2d" //注：key为商户密钥key

（4）计算签名

交易报文MD5计算：sign=MD5(stringSignTemp).toUpperCase()
通知报文MD5计算：sign=MD5(stringSignTemp).toLowerCase()
交易报文SM3计算：sign=SM3(stringSignTemp).toUpperCase()
通知报文SM3计算：sign=SM3(stringSignTemp).toLowerCase()

注：md5加密为32位。
注：SM3签名为64位
（1）设所有请求数据为集合M（请求数据中需上送sign_type为SM3，不上送默认为使用MD5），将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），

使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

（2）在stringA最后拼接上key得到stringSignTemp字符串，

并对stringSignTemp进行SM3运算，再将得到的字符串所有字符转换为大写，得到sign值signValue

特别注意

（1）请求数据验签方法

除sign、leshua、resp_code字段外，其他参数按照签名方法验签，空值不传递，不参与签名组串。

（2）应答数据验签方法

除sign、leshua、resp_code字段外，其他参数按照签名方法验签，空值参与签名组串。
（注：微信刷脸接口是全字段加签）

（3）支付结果通知验签方法

除sign、leshua、error_code字段外，其他参数按照签名方法验签，空值参与签名组串。

商户维度接入，支付结果通知验签需要向商务申请 商户获取代理商解析密钥

判断付款码规则

```java 支付宝：支付授权码，25~30开头的长度为16~24位的数字, 实际字符串长度以开发者获取的付款码长度为准 微信：扫码支付授权码，设备读取用户微信中的条码或二维码信息（注：用户刷卡条形码规则：18位纯数字以10、11、12、13、14、15开头） 银联二维码：62开头19位数字 数字人民币：0100开头的数字，其中01002 工行(数字人民币的不完整,后续会有改动) 01003 农行 01004 中行 01005 建行 01007 网商 01008 邮储 01009 交通银行 ```

1、统一下单（主扫：C扫B）

1.1接口说明

代理商在C扫B场景调用此支付接口完成下单，支持支付宝拉码支付、公众号支付、服务窗支付、银联JS支付、微信小程序支付。

测试商户信息及请求密钥和回调密钥请联系我们获取。

生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司。

1.2请求方式

POST

1.3请求地址

测试环境域名：https://t-paygate.lepass.cn

生产环境域名：https://paygate.leshuazf.com

接口地址：/cgi-bin/lepos_pay_gateway.cgi

1.4频率限制

4000次/s

1.5业务入参

变量名 必填 限制 类型 说明
service M 无 string 接口名
get_tdcode（此为固定值)
t0 O 无 int T0交易标志
默认为0，0：d1交易 1：d0交易
sign_type 0 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
pay_way M 16 string 支付类型
详见下方支付类型
merchant_id M 10 string 乐刷商户号
由乐刷分配
user_name O 无 string 收银员名称
third_order_id M 64 string 商户内部订单号
可以包含字母：确保同一个商户下唯一
amount M 10 string 订单总金额
金额不能为零或负数
jspay_flag M 1 string 支付类型
0-支付宝Native扫码支付、银联Native扫码支付；
1-微信JSAPI、支付宝JSAPI支付、银联JSAPI支付；
2-微信、支付宝简易支付<跳转乐刷收银台支付>；
（jspay_flag=2时必传jump_url，否则会报错）
3-微信小程序支付、支付宝小程序支付
注：
1）微信拉码支付已下线；
2）如需接入银联JS支付，请联系乐刷运营沟通域名报备。
3）数字货币支付当前仅支持jspay_flag=0
royalty O 1 string 交易分账标识
0：普通交易 1：分账（用于分账的交易需传该参数） 2：交易主体分账（延迟结算）
3：预授权
注：如果未传该字段默认为0，按不分账处理
appid M 32 string appid
条件必填，微信支付时必填。填微信公众号支付的公众号id或微信小程序支付的小程序appid;
传了会使用此appid 进行下单
sub_openid C 32 string sub_openid
微信JSAPI、微信小程序、支付宝JSAPI、支付宝小程序、银联JSAPI支付必填
extend_business_params O 无 string 该字段 为JSON格式的字符串，当前可透传支付宝的参数见下表
具体格式详见文档下方：业务拓展参数示例注：花呗分期商家订单传参贴息示例：
"extend_business_params":"{"business_params":{ "enable_thirdparty_subsidy":"N"}}"
如果第三⽅贴息活动为全场贴息，默认可贴息，传⼊ N 值则本笔交易禁⽤三⽅贴息；
如果第三⽅贴息活动为指定订单传参贴息，默认禁⽤贴息，传⼊Y 值则本笔交易启⽤三⽅贴息
jump_url O 128 string 前台跳转地址
简易支付时必填，完成后，乐刷将跳转到该页面，需做UrlEncode 处理
（受微信支付宝限制，已失效，可不传）
notify_url O 128 string 通知地址
接收乐刷通知（支付结果通知）的URL，需做UrlEncode 处理，需要绝对路径，确保乐刷能正确访问，若不需要回调请忽略
client_ip O 16 string 商户发起交易的IP地址
body O 256 string 商品描述
不能包含回车换行等特殊字符
shop_no O 16 string 商户门店编号
只能是汉字、英文字母、数字。注：该参数不上传给微信、支付宝
pos_no O 16 string 商户终端编号
只能是汉字、英文字母、数字 注意：银联类型交易时，只能 8位：数字字母 不支持 特殊字符
attach O 96 string 附加数据
下单成功原样返回；注意：只能是汉字、英文字母、数字
limit_pay O 1 string 指定支付方式
1：禁止使用信用卡；
0或者不填：不限制
goods_tag O 32 string 订单优惠标记
订单优惠标记（订单级别-品类级别），透传给微信，对应微信的goods_tag字段。微信会自动进行优惠匹配计算和核销。
用于给整个订单打上一个"标签"，主要用于代金券立减优惠场景，示例："coffee"。
goods_detail O 8000 string 单品详情
微信
单品级详细信息，透传给微信，对应微信的detail字段，**注意**不是对应detail.goods_detail字段。微信会自动进行优惠匹配计算和核销。
按微信单品优惠券格式传递透传给微信，请做UrlEncode
示例：{"goods_detail":[{"merchant_goods_id":"xiaomi_14_pro","goods_name":"小米14 Pro","quantity":1,"unit_price":499900}]}

银联
银联扫码交易时，透传给银联的“收款方附加数据”acqAddnData参数，当前银联的单品营销及扫码点餐均使用到该参数，具体参数格式及说明见：银联收款方附加数据。
order_expiration O 无 string 订单有效时间
单位：秒（支付宝的超时时间最小粒度为分钟，建议上送的为60的整数倍）最大时效600s
hb_fq_num O 无 string 花呗分期数
支付宝花呗分期数，支持3、6、12期
front_url C 无 string 前端跳转地址
银联JSAPI支付时选填，支付成功时跳转
front_fail_url C 无 string 支付失败前端跳转地址
银联JSAPI支付时选填，支付失败时跳转
nonce_str M 32 string 随机字符串
sign M 32 string 签名
MD5签名结果
device_info O 32 string 设备编号
针对微信、支付宝有效，透传至银联。
微信：数字、字母、下划线格式
支付宝：目前支持非0开头的数字
store_id O 32 string 门店编号
针对微信、支付宝有效，透传至银联。
微信：数字、字母、下划线格式
ass_merchant_id O 32 string 通道商户号
非必填。可使用指定的微信、支付宝子商户号进行交易，一个乐刷商户号有多个通道商户号情况下可用。
注：对应乐刷商户号大于200条时不能传该参数
pnrins_id_cd O 32 string 银联服务商标识
银联扫码交易时，透传给银联，对应银联的 pnrInsIdCd参数。
gps_info O 512 string gps信息
校验GPS信息格式， 如：-128.12,23.1 -- 1. xxx,xxx -- 2. 经度xxx为[-180，180]之间的浮点数，维度xxx为[-90，90]之间的浮点数，最多保留小数点八位float(11,8)
bs_info O 512 string 基站信息
校验基站信息格式,
格式说明： -- 1. 格式为：xxx,xxx,xxx,xxx 如：460,1,12,23454 -- 2. xxx均为整数，长度不超过11位

基站信息，从左至右依次对应以下几个字段： mcc: 移动国家号码，由3位数字组成，唯一地识别移动用户所属的国家。我国为460 mnc:移动网号，由两位数字组成，用于识别移动用户所归属的移动网 lac:位置区编码,为寻呼而设置的一个区域，覆盖一片地理区域，按寻呼量划分 ci :负责收发的天线所朝向的扇区编号
extend_business_params O - string 见下extend_business_params参数表
scene_info O - string 该字段用于上报场景信息，仅针对微信交易有效，目前支持上报实际门店信息。该字段 为JSON格式的字符串，对象格式为{"store_info":{"id": "门店 ID","name ": "名称","area_code": "编码","address": "地址"}} ，字段详细说明参考下文。
need_receipt O - boolean 电子发票功能。仅针对微信交易有效，需要和微信公众平台的发票功能联合使用。
枚举：
（只能为true或false，只支持全小写字母或全大写字母）
1. true
2. false
terminal_info M - String 商户侧受理终端信息
terminal_info为String类型，内容为json：
terminal_info="{"longitude":"-121.48352","latitude":"+31.221345","network_license":"P3100","device_type":"01","device_id":"54MPDz39","serial_num":"5","app_version":"v1.1.1","device_ip":"252.1.1.25"}"

terminal_info不能为空，如无终端信息则按此规则传参：device_type和serial_num必传：
device_type固定传11
serial_num=lhsd+商户编号

json内各参数说明
longitude：经度，+代表东经，-代表西经。
latitude：纬度，+代表北纬，-代表南纬。
network_license:银行卡受理终端入网编号。该
编号由“中国银联标识产品企业资质认证办公室”为通过入网认证的终端进行 分配。银联直连终端必填。
格式：5 位字符，例如 P3100
device_type：设备类型，01：自动柜员机（含 ATM 和 CDM）和 多媒体自助终端
02：传统 POS
03：mPOS
04：智能 POS
05：II 型固定电话
06：云闪付终端；
07：保留使用；
08：手机 POS；
09：刷脸付终端；
10：条码支付受理终端；
11：条码支付辅助受理终端；
12：行业终端（公交、地铁用于指定行
业的终端）；
13：MIS 终端；

serial_num：设备序列号，设备类型02、
03、04、05、06、08、09 或 10 时必填
encrypt_rand_num：仅在被扫支付类交易报文中出现：若付 款码为 19 位数字，则取后 6 位； 若付款码码为 EMV 二维码，则取其 tag 57 的卡号/token 号的后 6 位
secret_text：仅在条码支付交易报文中出现：64bit
的密文数据，对终端硬件序列号和加密 随机因子加密后的结果。 本子域取值为：64bit 密文数据进行 base64 编码后的结果。该字段需要服务商和厂商联调时由厂商sdk之类加密后给出。
app_version：终端应用程序的版本号。应用程序变更
应保证版本号不重复。当长度不足时， 右补空格。固定8位
device_ip：终端交易IP。如经、维度信息未上送，该字段必送。

extend_business_params 参数表

变量名 必填 限制 类型 说明
business_params O - String
goods_detail O - String
extend_params O - String
seller_id O 28 String 卖家支付宝用户 ID。如果该值为空，则默认为商户签约账号对应的支付宝用户 ID
discountable_amont O 11 Price 参与优惠计算的金额，单位为元，精确到 小 数 点 后 两 位 ， 取值范围[0.01,100000000]。 如果该值未传入，但传入了【订单总金额】和【不可打折金额】，则该值默认为【订单总金额】-【不可打折金额】
undiscountable_amount O 11 Price 不参与优惠计算的金额，单位为元，精确 到 小 数 点 后 两 位 ， 取 值 范 围[0.01,100000000]。如果该值未传入，但传入了【订单总金额】和【可打折金额】，则该值默认为【订单总金额】-【可打折金额】
buyer_logon_id O 100 String 买家支付宝账号
operator_id O 28 String 商户操作员编号
enable_pay_channels O 128 String 可用渠道，用户只能在指定渠道范围内支付。当有多个渠道时用“,”分隔，与 disable_pay_channels 互 斥。
settle_info O - SettleInfo 描述结算信息，json 格式，详见结算参数说明
alipay_store_id O 32 String 支付宝的店铺编号
ext_user_info O - ExtUserInfo 外部指定买家
qr_code_timeout_express O 6 String 该笔订单允许的最晚付款时间，逾期将关闭交易，从生成二维码开始计时。取值范围：1m～15d。 m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在 0 点关闭）。 该参数数值不接受小数点，如 1.5h，可转换为90m。
（对应jspay_flag为0时）
merchant_order_no O 32 String 商户原始订单号，最大长度限制32 位
（对应jspay_flag为1/2/3时）
disable_pay_channels O 64 String 禁用支付渠道,多个渠道以逗号分割，如 同时禁用信用支付类型和积分，则 disable_pay_channels="cre dit_group,point" 具体的渠道以支付宝或者银联提供的为准

场景信息scene_info字段说明（当前仅针对微信交易会透传给微信）：

名称 参数名 必填 类型 示例值 描述
门店Id id 否 String(32) SZTX001 门店唯一标识
门店名称 name 否 String(64) 腾讯大厦腾大餐厅 门店名称
门店行政区划码 area_code 否 String(6) 440305 门店所在地行政区划码
门店详细地址 address 否 String(128) 科技园中一路腾讯大厦 门店详细地址

1.6业务出参

变量名 必填 限制 类型 说明
resp_code M 无 string 返回状态码
0 - 成功，非0 - 失败。注：此字段是通信标识，是否获取到二维码要看result_code
resp_msg C 无 string 返回错误信息
错误描述：resp_code非0时返回
result_code M 1 string 业务结果
0 - 成功，非0 - 失败
error_code O 无 string 错误码
参考错误码信息表
error_msg O 无 string 错误信息描述
attach O 96 string 附加数据
原样返回；注意：只能是汉字、英文字母、数字
merchant_id M 10 string 乐刷商户号
由乐刷分配
sub_merchant_id M 无 string 通道商户号
微信、支付宝、QRC商户号
third_order_id M 64 string 商户内部订单号
nonce_str M 32 string 随机字符串
sign M 32 string MD5签名结果
td_code C 无 string 二维码链接
非公众号支付返回，可直接通过该链接生成二维码扫码支付(jspay_flag传0-2该字段才会返回)
jspay_info C 无 string 支付信息
原生公众号、服务窗、小程序，返回json格式字符串、银联JS支付返回URL，用云闪付打开此链接即可调起支付 生效时间:默认10分钟,具体时间看订单有效时间
jspay_url C 无 string 支付跳转地址
简易支付时返回。重定向到该url可以完成后续支付流程。返回二维码链接有效期为10分钟；
leshua_order_id M 32 string 乐刷订单号
pay_way M 无 string 支付类型
详见下方支付类型
cost_time C 无 string 请求耗时
请求接口耗费的时间
channel_flag O 32 string 通道标记
GXST：高校食堂
PUBWEL：公益
PUBPAY：公缴
ZFBLH：支付宝新蓝海
SLZXY：私立中小幼
INS：保险
ONLINE：线上
YLLZ：绿洲
alipay_infos O trade_no:银联交易号

注意事项

（1）所有涉及到金额的单位都位分，币种为RMB，最小为1分，不允许出现小数

（2）文档中参数，标识为必填必须上送（如果缺少会报错），非必填的可填可不填（简易支付"支付跳转地址"字段为必传），

（3）返回参数中必填为是的参数是一定会返回的，必填为否的参数则不一定返回，因升级或配置等情况实际返回参数可能不会跟文档完全一致，必须以实际接收到的参数为准

获取微信用户openid
https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140842&token=&lang=zh_CN
获取支付宝用户openid
https://doc.open.alipay.com/doc2/detail.htm?spm=a219a.7629140.0.0.8ujLD6&treeId=115&articleId=104114&docType=1

公众号支付请求示例

1、请求格式如下：

https://paygate.leshuazf.com/cgi-bin/lepos_pay_gateway.cgi?amount=1&
appid=wx00e59fa8be9ba128&jspay_flag=1&merchant_id=3219113278&
nonce_str=lnxouwc0r7l93453x5&order_expiration=60&pay_way=WXZF&service=get_tdcode&
sub_openid=oe5BX0qaVuC5vqYdj65GlUcyAVUM&third_order_id=202004271809453917&sign=2A500B7F906284717212304A9BCFB33D

返回示例

1、响应格式如下：

<leshua>
	<resp_code><![CDATA[0]]></resp_code>
	<merchant_id><![CDATA[3219113278]]></merchant_id>
	<sign><![CDATA[D6D8B65D19C2874D645C8AB3001BDFC6]]></sign>
	<pay_way><![CDATA[WXZF]]></pay_way>
	<third_order_id><![CDATA[202004271809453917]]></third_order_id>
	<jspay_info><![CDATA[{"appId":"wx00e59fa8be9ba128","timeStamp":"1587982188","nonceStr":"0331f99e446a406a933f599102c6a096","package":"prepay_id=wx271809485236369bff1b171c1846357400","signType":"RSA","paySign":"uNoENZ3BOqggJptJRPw9PLCN759+GPlGcgQ9J1XVE/TSiA0pR6wro6ZqBMtyQ2GixTnJcvwfilZK7Bf8TJQ1jMizWB6BjbjJMtpptLtFNGTexjW/QqjubIVRqlNYPepSZiPYNNDsk3DwvaiYKzIahQ1T4SP8nSdTVEsttgqwAgIyccB87/oNN/EHPtCCuFHDYoDdB5k0JW8PBybFXg0zuy1GxqBhHyi/DESzd+Ke8hi6ZZgFcFzWEl55hhxASMvsbXjbSenK98eGwd/f/sJa5zZjS1snt24n56vnkUkjEi31KL/j7u5xBx3l97WZESJN3Kdda2zwWIMNKYbSE+MpQQ=="}]]></jspay_info>
	<nonce_str><![CDATA[hamzqguihsivovvcovgfqkrxxpklovxk]]></nonce_str>
	<result_code><![CDATA[0]]></result_code>
	<leshua_order_id><![CDATA[9000024427820118]]></leshua_order_id>
	<sub_merchant_id><![CDATA[344415140]]></sub_merchant_id>
</leshua>

支付宝拉码支付请求示例

1、请求格式如下：

https://t-paygate.lepass.cn/cgi-bin/lepos_pay_gateway.cgi?amount=1&jspay_flag=0
&merchant_id=0000000018&nonce_str=w1hxpdiu9nkjfw5qrp&order_expiration=60&
pay_way=ZFBZF&service=get_tdcode&third_order_id=202004291733230374&
sign=340DB607E3BEE2BAE60807B3601008E2

返回示例

1、响应格式如下：

<leshua>
	<resp_code><![CDATA[0]]></resp_code>
	<merchant_id><![CDATA[0000000018]]></merchant_id>
	<sign><![CDATA[8208ADC9E7E6DD8B7B020E2C14B58C68]]></sign>
	<result_code><![CDATA[0]]></result_code>
	<third_order_id><![CDATA[202004291733230374]]></third_order_id>
	<pay_way><![CDATA[ZFBZF]]></pay_way>
	<nonce_str><![CDATA[ibtzcpizitpmtenowvzasczstffcubex]]></nonce_str>
	<td_code><![CDATA[https://qr.alipay.com/bax00753gvtsjixecagz00ce]]></td_code>
	<leshua_order_id><![CDATA[0000005701801120]]></leshua_order_id>
	<sub_merchant_id><![CDATA[2088231796689692]]></sub_merchant_id>
</leshua>

2、条码支付（被扫：B扫C）

请求地址

（1）/cgi-bin/lepos_pay_gateway.cgi

（2）测试商户信息及请求密钥和回调密钥请联系我们获取。

（3）生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string upload_authcode（此为固定值）
t0交易标志 t0 O 无 int 默认为0，0：d1交易 1：d0交易
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
付款码 auth_code M 无 string 支持以下付款码：
1. 微信数字付款码
2. 支付宝数字付款码
3. 云闪付APP 62开头付款码
4. 银行APP 62开头付款码
5. 数字人民币APP付款码（0100开头）
6. 支付宝刷脸付款码（fp开头）
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id M 64 string 商户内部订单号，可以包含字母：确保同一个商户下唯一
订单金额 amount M 10 string 总金额
分账标识 royalty O 1 string 交易分账标识
0：普通交易 1：分账（用于分账的交易需传该参数） 2：交易主体分账（延迟结算）
3：预授权
注：如果未传该字段默认为0，按不分账处理
商户公
众账号 ID		 appid O 32 string 商户或者商户所属渠道号主体的公众号appid,由微信统一分配，仅对微信交易生效，传送前请确定商户和该appid已经建立绑定关系
通知地址 notify_url O 128 string 接收乐刷通知的URL，需做UrlEncode 处理，需要绝对路径，确保乐刷能正确访问，若不需要回调请忽略
用户IP地址 client_ip O 16 string 商户发起交易的IP地址
商品描述 body O 256 string 商品描述,不能包含回车换行等特殊字符
商户门店编号 shop_no O 16 string 只能是汉字、英文字母、数字
商户终端编号 pos_no O 16 string 只能是汉字、英文字母、数字 注意：银联类型交易时，只能 8位：数字字母 不支持 特殊字符
附加数据 attach O 96 string 支付成功原样返回；注意：只能是汉字、英文字母、数字
指定支付方式 limit_pay O 1 string 1：禁止使用信用卡；0或者不填：不限制
订单优惠标记 goods_tag O 32 string 订单优惠标记，透传给微信
商品详情 goods_detail O 8000 string 按微信单品优惠券格式传递，透传给微信;
银联扫码交易时，透传给银联的“收款方附加数据”acqAddnData参数，当前银联的单品营销及扫码点餐均使用到该参数，具体参数格式及说明见：银联收款方附加数据。
花呗分期数 hb_fq_num O 无 string 支付宝花呗分期数，支持3、6、12期
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
业务拓展参数 extend_business_params O 8000 string 该字段 为JSON格式的字符串，当前可透传支付宝的参数见下表
具体格式详见文档下方：业务拓展参数示例
注：花呗分期商家订单传参贴息示例：
"extend_business_params":"{"business_params":{ "enable_thirdparty_subsidy":"N"}}"
如果第三⽅贴息活动为全场贴息，默认可贴息，传⼊ N 值则本笔交易禁⽤三⽅贴息；
如果第三⽅贴息活动为指定订单传参贴息，默认禁⽤贴息，传⼊Y 值则本笔交易启⽤三⽅贴息
设备编号 device_info O 32 string 针对微信、支付宝有效，透传至银联。
微信：数字、字母、下划线格式
支付宝：目前支持非0开头的数字
门店编号 store_id O 32 string 针对微信、支付宝有效，透传至银联。
微信：数字、字母、下划线格式
支付宝：目前支持非0开头的数字
通道商户号 ass_merchant_id O 32 string 非必填。可使用指定的微信、支付宝子商户号进行交易，一个乐刷商户号有多个通道商户号情况下可用。
注：对应乐刷商户号大于200条时不能传该参数
银联服务商标识 pnrins_id_cd O 32 string 银联扫码交易时，透传给银联，对应银联的 pnrInsIdCd参数。
gps信息 gps_info O 512 string 校验GPS信息格式， 如：-128.12,23.1 -- 1. xxx,xxx -- 2. 经度xxx为[-180，180]之间的浮点数，维度xxx为[-90，90]之间的浮点数，最多保留小数点八位float(11,8)
** 基站信息** bs_info O 512 string 校验基站信息格式,
格式说明： -- 1. 格式为：xxx,xxx,xxx,xxx 如：460,1,12,23454 -- 2. xxx均为整数，长度不超过11位

基站信息，从左至右依次对应以下几个字段： mcc: 移动国家号码，由3位数字组成，唯一地识别移动用户所属的国家。我国为460 mnc:移动网号，由两位数字组成，用于识别移动用户所归属的移动网 lac:位置区编码,为寻呼而设置的一个区域，覆盖一片地理区域，按寻呼量划分 ci :负责收发的天线所朝向的扇区编号
场景信息 scene_info O string 该字段用于上报场景信息，仅针对微信交易有效，目前支持上报实际门店信息。该字段 为JSON格式的字符串，对象格式为{"store_info":{"id": "门店 ID","name ": "名称","area_code": "编码","address": "地址"}} ，字段详细说明参考下文。
电子发票功能 need_receipt O boolean 电子发票功能。仅针对微信交易有效，需要和微信公众平台的发票功能联合使用。
枚举：
（只能为true或false，只支持全小写字母或全大写字母）
1. true
2. false
交易终端信息 terminal_info O String 商户侧受理终端信息，格式为json 格 式。 如terminal_info= { "longitude":"-121.48352",#option "latitude":"+31.221345",#option
"network_license":"P3100", "device_type":"01"， "device_id":"54MPDz39", "serial_num":"5", "app_version": "v1.1.1" ， "device_ip": "252.1.1.25" , }

json内各参数说明
longitude：经度，+代表东经，-代表西经。
latitude：纬度，+代表北纬，-代表南纬。
network_license:银行卡受理终端入网编号。该
编号由“中国银联标识产品企业资质认证办公室”为通过入网认证的终端进行 分配。银联直连终端必填。
格式：5 位字符，例如 P3100
device_type：设备类型，01：自动柜员机（含 ATM 和 CDM）和 多媒体自助终端
02：传统 POS
03：mPOS
04：智能 POS
05：II 型固定电话
06：云闪付终端；
07：保留使用；
08：手机 POS；
09：刷脸付终端；
10：条码支付受理终端；
11：条码支付辅助受理终端；
12：行业终端（公交、地铁用于指定行
业的终端）；
13：MIS 终端；

serial_num：设备序列号，设备类型02、
03、04、05、06、08、09 或 10 时必填
encrypt_rand_num：仅在被扫支付类交易报文中出现：若付 款码为 19 位数字，则取后 6 位； 若付款码码为 EMV 二维码，则取其 tag 57 的卡号/token 号的后 6 位
secret_text：仅在条码支付交易报文中出现：64bit
的密文数据，对终端硬件序列号和加密 随机因子加密后的结果。 本子域取值为：64bit 密文数据进行 base64 编码后的结果。该字段需要服务商和厂商联调时由厂商sdk之类加密后给出。
app_version：终端应用程序的版本号。应用程序变更
应保证版本号不重复。当长度不足时， 右补空格。固定8位
device_ip：终端交易IP。如经、维度信息未上送，该字段必送。

extend_business_params参数：

变量名 必填 限制 类型 说明 示例
business_params O - Object 商户传入业务信息，应用于安全，营销
等参数直传场景，格式为 json 格式。
goods_detail O - Array 订单包含的商品列表信息，数组格式。
一般在支付宝扫码点餐业务中上传点餐的商品信息		 [{"goods_id": "5544", "goods_name": "爽口青笋丝","price": "0.50","quantity": 2,"goods_category": "888", "categories_tree": "888","body": "爽口青笋丝","show_url":"pageFoodChain/storeDetail/main?suid=10"}]
┖goods_id M 32 String 商品的编号
┖alipay_goods_id O 32 String 支付宝定义的统一商品编号
┖goods_name M 256 String 商品名称
┖quantity M 10 Number 商品数量
┖price M 9 Price 商品价格，单位为元
┖goods_category O 24 String 商品类目
┖categories_tree O 128 String 商品类目数，从商户品类目根节点到叶子节点的类目id组成，类目id使用 分割
┖body O 1000 String 商品描述信息
┖show_url O 400 String 商品的展示地址 http://www.alipay.co
m/xxx.jpg
extend_params O - Object 支付宝业务扩展参数
┖sys_service_provid
er_id		 O String
┖hb_fq_num O String
┖hb_fq_seller_percent O String
┖industry_reflux_info O String
┖card_type O String
┖
┖
┖
┖
seller_id O 28 String 如果该值为空，则默认为商户签约账号对应的支付宝用户ID预授权场景下无需上送
discountable_amont O 11 Price 参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]。 如果该值未传入，但传入了【订单总金额】和【不可打折金额】，则该值默认为【订单总金额】-【不可打折金额】
undiscountable_amount O 11 Price 不参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]。如果该值未传入，但传入了【订单总金额】和【可打折金额】，则该值默认为【订单总金额】-【可打折金额】
operator_id O 28 String 商户操作员编号
alipay_store_id O 32 String 支付宝的店铺编号
merchant_order_no O 32 String 商户的原始订单号
ext_user_info O - ExtUserInfo 外部指定买家
promo_params O 512 PromoParam 优惠明细参数，通过此属性补充营销参数
terminal_params O 2048 String json 格式；商户传入终端设备。如：
{"credential":"28763443825664394:20180207192030954:abcdefGHIJKLMN","signature":"xxxxxxx","terminalType":"IOT"}
advance_payment_type O 20 String 支付模式类型, 若 值 为ENJOY_PAY_V2表示当前交易允许走先享后付 2.0 垫资
query_options O 1024 String[] 返回查询选项，商户通过上送该参数来定制同步需要额外返回的信息字段，数组格式。如：["fund_bill_list","voucher_detail_list","discount_goods_detail"]
disable_pay_channels O 64 String 禁用支付渠道,多个渠道以逗号分割，如 同时禁用信用支付类型和积分，则 disable_pay_channels="cre dit_group,point" 具体的渠道以支付宝或者银联提供的为准

场景信息scene_info字段说明（当前仅针对微信交易会透传给微信）：

名称 参数名 必填 类型 示例值 描述
门店Id id 否 String(32) SZTX001 门店唯一标识
门店名称 name 否 String(64) 腾讯大厦腾大餐厅 门店名称
门店行政区划码 area_code 否 String(6) 440305 门店所在地行政区划码
门店详细地址 address 否 String(128) 科技园中一路腾讯大厦 门店详细地址

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识，业务状态要看result_code
返回错误信息 resp_msg C 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0 - 成功，非0 - 失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
商户号 merchant_id M 10 string 由乐刷分配
通道商户号 sub_merchant_id M 无 string 微信、支付宝、QRC商户号
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
订单状态 status M 无 string 详见下方订单状态
乐刷订单号 leshua_order_id M 32 string 乐刷订单号
支付类型 pay_way M 无 string 详见下方支付类型
支付完成时间 pay_time C 无 string 支付成功时才返回
银行类型 bank_type O 无 string 使用银行卡支付以外的（如零钱）全部展示为others，使用银行卡支付的详见下方付款银行类型
用户openid openid C 无 string 支付成功时才返回
微信、支付宝等订单号 out_transaction_id C 无 string 支付成功时才返回
用户子标识 sub_openid C 无 string 支付成功时才返回。微信：公众号APPID下用户唯一标识；支付宝：买家的支付宝用户ID
附加数据 attach O 96 string 支付成功原样返回；注意：只能是汉字、英文字母、数字
交易类型 trade_type C 无 string 支付成功时才返回：MICROPAY-条码支付，NATIVE-原生扫码支付，JSAPI-公众号支付、服务窗支付，SmPgPay-小程序支付，JSAPIQuick-简易支付
通道订单号 channel_order_id C 无 string 支付成功时才返回
通道订单时间 channel_datetime C 无 string 支付成功时才返回
支付宝红包金额 coupon C 无 string 支付成功时才返回，单位(分)
应结算金额 settlement_amount C 无 string 实际结算金额，支付成功时才返回，单位(分)
折扣优惠金额 discount_amount C 无 string 订单优惠金额，支付成功时才返回，单位(分)
优惠详情 promotion_detail O 无 string 银联单品的具体优惠详情；
微信优惠详情说明：微信官网
活动标志 active_flag O 无 string 活动标志。WXLZ：微信绿洲；ZFBLH：支付宝蓝海
买家实付金额 buyer_pay_amount C 无 String 微信、支付宝此值有效
请求耗时 cost_time C 无 string 请求接口耗费的时间
通道标记 channel_flag O 32 string GXST：高校食堂
PUBWEL：公益
PUBPAY：公缴
ZFBLH：支付宝新蓝海
SLZXY：私立中小幼
INS：保险
ONLINE：线上
银联/网联状态码 channel_code C 无 JSON 透传银联的返回码。
银联支付宝：code, sub_code 银联微信：return_code, result_code，err_code 银联二维码平台：respCode 条码前置平台：status、code、result_code、err_code。
以上各种code,仅在银联返回时透传。
格式：<channel_code></channel_code>
alipay_infos 见下alipay_infos参数表

alipay_infos参数表

参数名 变量名 必填 限制 类型 说明
total_amount M 11 Price 交易金额(单位:分, 类型:数字)
settle_amount C 11 String 结算币种订单金额
pay_amount C 11 String 支付币种订单金额
receipt_amount M 11 String 实收金额(单位:分, 类型:数字)
point_amount C 11 Price 使用集分宝付款的金额
invoice_amount C 11 Price 交易中可给用户开具发票的金额(单位:元)
fund_bill_list M TradeFundBill[] 交易支付使用的资金渠道。只有在签约中指定需要返回资金明细，或者入参的query_options 中指定时才返回该字段信息。
card_balance C 11 Price 支付宝卡余额
store_name C 512 String 发生支付交易的商户门店名称
discount_goods_detail C 1024 String 本次交易支付所使用的单品券优惠的商品优惠信息。只有在 query_options中指定时才返回该字段信息。
async_payment_mode C 20 String 异步支付模式，先享后付业务会返回该参 数 ， 目 前 有 三 种 值 ：ASYNC_DELAY_PAY( 异 步 延 时 付款); ASYNC_REALTIME_PAY( 异步准实时付款); SYNC_DIRECT_PAY(同步直接扣款);
purchase_merchant_contribute C 8 Price 如果使用的这张券是用户购买的，则该字段代表用户在购买这张券时商户优惠的金额
auth_trade_pay_mode C 64 String 预授权支付模式，该参数仅在信用预授权支付场景下返回。信用预授权支付：CREDIT_PREAUTH_PAY
advance_amount C 11 String 先享后付 2.0 垫资金额,不返回表示没有走垫资，非空表示垫资支付的金额
business_params C 512 String 商户传入业务信息，具体值要和支付宝约定将商户传入信息分发给相应系统，应用于安全，营销等参数直传场景格式为 json 格式
buyer_user_type C 18 String 买家用户类型。 CORPORATE:企业用户；PRIVATE:个人用户。
buyer_user_name C 128 String 买家名称；买家为个人用户时为买家姓名，买家为企业用户时为企业名称；
mdiscount_amount C 11 String 商家优惠金额
discount_amount C 11 String 平台优惠金额
charge_flags C 64 String 费率活动标识，当交易享受活动优惠费率时，返回该活动的标识；(1)蓝海活动优惠费率 0，值为 bluesea_1(2) 特 殊 行 业 优 惠 费 率 0 ， 值 为industry_special_00(3) 特殊行业优惠费率千一，值为industry_special_01
buyer_logon_id M 100 String 买家支付宝账号
订单优惠金额

微信支付包含商户和微信给的优惠金额，支付宝支付只包含商户给的优惠金额，银联二维码支付只包含商户给的优惠金额

业务拓展参数示例

"extend_business_params": "{ "
   extend_params ":{ "
   sys_service_provider_id ":"
   208812333665551 ",  "
   food_order_type ":"
 home_delivery " } }",

银联单品营销请求示例

请求地址?amount=100&auth_code=XXXXXXXXXXXXXXXX&goods_detail=
%7b%22goodsInfo%22%3a%5b%7b%22id%22%3a%2212341234%22%2c%22name%22%3a%22%e6%b5%8b%e8%af%95%e5%95%86%e5%93%81%22%2c%22price%22%3a%22100%22%2c%22quantity%22%3a%221%22%7d%5d%7d
&merchant_id=XXXXXXXXXX&nonce_str=7aee8b722a614cfa9cfb39ad5409fcdf&service=upload_authcode&third_order_id=UB4C0D38F5091465F920200326100751&
sign=69fb04df6dda8bfd3110e4891efedc8b
银联收款方附加数据

price 和 quantity 字段为数字类型

银联扫码交易时good_detail示例： 
{ 
  "orderInfo" : { 
    "title" :"日用品", 
    "dctAmount" :"10000", 
    "addnInfo" :"屈臣氏(人民广场)店" 
  },
  "goodsInfo" : [ 
    {"id": "1234567890",
     "name": "商品 1", 
     "price": 500, 
     "quantity": 1
    },
    {
      "id": "1234567891", 
      "name": "商品 2", 
      "price": 1000, 
      "quantity": 2, 
      "category": "类目 1", 
      "addnInfo": "商品图片 http://www.95516.com/xxx.jpg" } ] 
}

注：

  1. 银联扫码点餐时，在该域的订单信息 orderInfo 子域中的附加信息 addnInfo 字段需填写该门店对应的品牌标识、门店标识、桌号（其中 SaaS 收银的支付交易需有 品牌标识、门店标识，扫码点餐的支付交易必须有品牌标识、门店标识、桌号）。addnInfo 字段的参考格 式为：{brandId=值&storeId=值&tableNo=值}，例如： addnInfo={brandId=AXMX&storeId=12345&tableNo=12}
  2. 银联单品营销时，按照银联需要的内容，在该域的商品信息goodsInfo上送对应的商品信息。

注意事项

（1）所有涉及到金额的单位都位分，币种为RMB，最小为1分，不允许出现小数

（2）文档中参数，标识为必填必须上送（如果缺少会报错），非必填的可填可不填

（3）返回参数中必填为是的参数是一定会返回的，必填为否的参数则不一定返回，因升级或配置等情况实际返回参数可能不会跟文档完全一致，必须以实际接收到的参数为准

3.扫码支付结果

3.1、扫码支付结果通知

由于诸多因素都会影响到支付结果的通知，推送可能存在延迟，并且不能保证100%推送成功。故强烈建议主接交易查询接口。

**POST Content-Type: text/xml; charset=utf-8 **

通知参数

参数名 变量名 必填 限制 类型 说明
错误码 error_code O 无 string 参考错误码信息表
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使 用MD5算法)
签名 sign M 32 string MD5签名结果
商户号 merchant_id M 10 string 乐刷商户号
通道商户号 sub_merchant_id M 无 string 微信、支付宝、QRC商户号
乐刷订单号 leshua_order_id M 32 string
商户订单号 third_order_id M 64 string
订单金额 amount M 无 string
订单状态 status M 无 string 详见下方订单状态
支付类型 pay_way M 无 string 详见下方支付类型
支付时间 pay_time M 无 string '2020-09-15 10:11:30'
银行类型 bank_type O 无 string 使用银行卡支付以外的（如零钱）全部展示为others，使用银行卡支付的详见下方付款银行类型
用户openid openid O 无 string
微信、支付宝等订单号 out_transaction_id O 无 string
用户子标识 sub_openid C 无 string 支付成功时才返回。微信：微信公众号APPID 下用户唯一标识；支付宝：买家的支付宝用户ID
附加数据 attach O 96 string 原样返回；注意：只能是汉字、英文字母、数字
交易类型 trade_type C 无 string 支付成功时才返回：MICROPAY-条码支付，NATIVE-原生扫码支付，JSAPI-公众号支付、服务窗支付，SmPgPay-小程序支付，JSAPIQuick-简易支付
通道订单号 channel_order_id C 无 string 支付成功时才返回
通道订单时间 channel_datetime C 无 string 支付成功时才返回
支付宝红包金额 coupon C 无 string 支付成功时才返回
应结算金额 settlement_amount C 无 string 实际结算金额，支付成功时才返回
折扣优惠金额 discount_amount C 无 string 本订单优惠金额，支付成功时才返回
优惠详情 promotion_detail O 无 string 银联单品的具体优惠详情；微信优惠详情说明：微信官网
活动标志 active_flag O 无 string 活动标志：WXLZ：微信绿洲 ZFBLH：支付宝蓝海
买家实付金额 buyer_pay_amount O 无 String 微信、支付宝此值有效
付款方附加数据 iss_addn_data M 无 String 格式如下
设备编号 device_info O 32 string 上游返回时才返
门店编号 store_id O 32 string 上游返回时才返
通道标记 channel_flag O 32 string GXST：高校食堂
PUBWEL：公益
PUBPAY：公缴
ZFBLH：支付宝新蓝海
SLZXY：私立中小幼
INS：保险
ONLINE：线上
花呗分期期数 hb_fq_num O 无 string 支付宝花呗分期数，一般为3、6、12期，乐刷透传，具体期数由支付宝侧限定
支付宝优惠信息 alipay_infos string 见下alipay_infos参数表
分期信息 install_info O 无 string 包含分期笔数(install_nums)/分期付款手续费率(install_rate)/商户补贴手续费率(merchant_fee_subsidy)）

alipay_infos参数表

变量名 必填 限制 类型 说明
total_amount M 11 Price 交易金额(单位:分, 类型:数字)
point_amount O 11 Price 积分支付的金额，单位为元，两位小数。该金额代表该笔交易中用户使用积分支付的金额，比如集分宝或者支付宝实时优惠等
invoice_amount O 11 Price 交易中用户支付的可开具发票的金额，单位为元，两位小数。该金额代表该笔交易中可以给用户开具发票的金额
receipt_amount O 11 String 实收金额(单位:分, 类型:数字)
discount_goods_detail M 1024 String 本次交易支付所使用的单品券优惠的商品优惠信息。只有在 query_options中指定时才返回该字段信息。
mdiscount_amount O 11 String 商家优惠金额
discount_amount O 11 String 平台优惠金额
buyer_logon_id M 100 String 买家支付宝账号
fund_bill_list M 256 TradeFundBill[] 交易支付使用的资金渠道。只有在签约中指定需要返回资金明细，或者入参的query_options 中指定时才返回该字段信息。

注意：

1、支付发起后，乐刷一般30s左右才会返回支付通知，如需快速获取支付结果，请调用“交易结果查询”接口发起查询。

2、支付通知的频率：0s/15s/30s/1m/4m/34m/64m/94m/124m/184m

支付类型
类型 说明 状态
WXZF 微信 支持
ZFBZF 支付宝 支持
UPSMPAY 银联二维码 支持

iss_addn_data参考格式：

参数名 变量名 类型 说明
商品优惠信息 dctDetail String 商品优惠明细
商品编号 id String 参与优惠的商品编号
优惠活动编号 dctId String 优惠活动的编号
商品优惠数量 dctQuantity String 参与优惠的商品数量
商品优惠金额 dctPrice String 商品的优惠总金额(分) 
issAddnData= {
  "dctDetail" : [{
    "id": "1234567890",
    "dctId": "app012345",
    "dctQuantity": 1",
    "dctPrice": "500"
  },{
    "id": "1234567891",
    "dctId": "app012345",
    "dctQuantity": "2",
    "dctPrice": "1000",

返回参数

返回内容 说明
000000 通知成功，乐刷收到此返回后不会继续通知。返回内容000000是string类型，没有双引号。示例：return 000000;
其他 乐刷收到回复或者未收到回复，系统会再次通知。为避免资源浪费，请核实并确保响应信息的准确性，可以是否重复通知为检查手段

注意：

1.回调地址为统一下单或条码支付的通知地址。

2.交易回调处理时间为5S内。

3.支付成功才进行推送。

付款银行类型

通道 说明
微信 https://pay.weixin.qq.com/wiki/doc/api/mch_bank.php?chapter=4_2
支付宝 https://alipay.open.taobao.com/doc2/detail?treeId=26&articleId=103259&docType=1
银联二维码 1 - 借记卡 2- 贷记卡

3.2、扫码交易结果查询

请求地址

（1）/cgi-bin/lepos_pay_gateway.cgi

（2）测试商户信息及请求密钥和回调密钥请联系我们获取。

（3）生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司

（4）注：查询时，除非返回明确的支付成功、支付失败、订单关闭等最终状态，其他错误或者未支付状态，都需要再查询，直到得到明确的支付状态。如果超过一段时间还是未支付，可以调用关闭订单接口。

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string query_status（此为固定值）
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id O 64 string 选填
乐刷订单号 leshua_order_id O 16 string third_order_id和leshua_order_id必填1个，优先使用leshua_order_id
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识，业务状态要看result_code
返回错误信息 resp_msg C 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0 - 成功，非0 - 失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
商户号 merchant_id M 10 string 由乐刷分配
通道商户号 sub_merchant_id M 无 string 微信、支付宝、QRC商户号
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
订单状态 status M 无 string 详见下方订单状态
乐刷订单号 leshua_order_id M 32 string 乐刷订单号
订单金额 amount M 无 string
支付类型 pay_way M 无 string 详见下方支付类型
支付完成时间 pay_time C 无 string 支付成功时才返回
银行类型 bank_type O 无 string 使用银行卡支付以外的（如零钱）全部展示为others，使用银行卡支付的详见下方付款银行类型
用户openid openid C 无 string 支付成功时才返回
微信、支付宝等订单号 out_transaction_id C 无 string 支付成功时才返回
用户子标识 sub_openid C 无 string 支付成功时才返回。微信：微信公众号APPID下用户唯一标识；支付宝：买家的支付宝用户ID
附加数据 attach O 96 string 支付成功时原样返回；注意：只能是汉字、英文字母、数字
交易类型 trade_type C 无 string 支付成功时才返回：MICROPAY-条码支付，NATIVE-原生扫码支付，JSAPI-公众号支付、服务窗支付，SmPgPay-小程序支付，JSAPIQuick-简易支付
通道订单号 channel_order_id C 无 string 支付成功时才返回
通道订单时间 channel_datetime C 无 string 支付成功时才返回
支付宝红包金额 coupon C 无 string 支付成功时才返回，单位(分)
应结算金额 settlement_amount C 无 string 实际结算金额，支付成功时才返回
折扣优惠金额 discount_amount C 无 string 订单优惠金额，支付成功时才返回
优惠详情 promotion_detail O 无 string 银联单品的具体优惠详情;

微信优惠详情说明：微信官方文档
活动标志 active_flag O 无 string 活动标志。WXLZ：微信绿洲；ZFBLH：支付宝蓝海
买家实付金额 buyer_pay_amount O 无 String 微信、支付宝此值有效
请求耗时 cost_time C 无 string 请求接口耗费的时间
退款金额
 refund_amount O 无 string 订单已退款的金额
简易支付标识 simple_url_flag O 无 string 1表示是简易支付，0表示不是简易支付
设备编号 device_info O 32 string 上游返回时才返
门店编号 store_id O 32 string 上游返回时才返
支付中间态补充 interm_state O 32 O 目前仅针对微信支付，订单为支付中时返回：
NOTPAY,USERPAYING
通道标记 channel_flag O 32 string GXST：高校食堂
PUBWEL：公益
PUBPAY：公缴
ZFBLH：支付宝新蓝海
SLZXY：私立中小幼
INS：保险
ONLINE：线上
花呗分期期数 hb_fq_num O 无 string 支付宝花呗分期数，一般为3、6、12期，乐刷透传，具体期数由支付宝侧限定
alipay_infos 见下alipay_infos参数表

alipay_infos参数表

变量名 必填 限制 类型 说明
total_amount M 11 Price 交易金额(单位:分, 类型:数字)
point_amount O 11 Price 积分支付的金额，单位为元，两位小数。该金额代表该笔交易中用户使用积分支付的金额，比如集分宝或者支付宝实时优惠等
invoice_amount O 11 Price 交易中用户支付的可开具发票的金额，单位为元，两位小数。该金额代表该笔交易中可以给用户开具发票的金额
receipt_amount O 11 String 实收金额(单位:分, 类型:数字)
discount_goods_detail M 1024 String 本次交易支付所使用的单品券优惠的商品优惠信息。只有在 query_options中指定时才返回该字段信息。
mdiscount_amount O 11 String 商家优惠金额
discount_amount O 11 String 平台优惠金额
buyer_logon_id M 100 String 买家支付宝账号
fund_bill_list M 256 TradeFundBill[] 交易支付使用的资金渠道。只有在签约中指定需要返回资金明细，或者入参的query_options 中指定时才返回该字段信息。

注意事项

（1）所有涉及到金额的单位都位分，币种为RMB，最小为1分，不允许出现小数

（2）文档中参数，标识为必填必须上送（如果缺少会报错），非必填的可填可不填

（3）返回参数中必填为是的参数是一定会返回的，必填为否的参数则不一定返回，因升级或配置等情况实际返回参数可能不会跟文档完全一致，必须以实际接收到的参数为准

4、扫码退款

4.1、扫码退款接口

注意：超过三个月的订单，无法退款请注意
****一个交易订单号，最多支持发起50次退款 请求地址

（1）/cgi-bin/lepos_pay_gateway.cgi

（2）测试商户信息及请求密钥和回调密钥请联系我们获取。

（3）生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司

（4）退款一般会返回退款中的状态，如需获取真实退款状态，请调用退款查询接口

（5）每笔支付订单部分退款次数不能超过50次

（6）退款有效期为60天，即订单发起后的60天内可以退款

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string unified_refund 注：此为固定值
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id O 64 string
乐刷订单号 leshua_order_id O 32 string 商户订单号跟乐刷订单号必填1个，优先使用leshua_order_id
商户退款单号 merchant_refund_id M 64 string 可以包含字母（不能有“_”等特殊字符），确保同一商户下唯一
附加数据 attach O 96 string 退款成功原样返回；注意：只能是汉字、英文字母、数字
退款金额 refund_amount M 10 string 退款金额，可做部分退款
退款类型 refund_type O 否 string 0：不使用账户余额退款，
1：可以使用账户余额退款（优先使用正向交易抵扣，正向交易不够抵扣情况下可用账户余额进行退款）。
2：限定只可以用账户余额进行退款
不传默认不使用账户余额退款 (注意： 实时清分的只能使用账户退款 )
随机字符串 nonce_str M 32 string 随机字符串，长度要求32位以内
通知地址 notify_url O 128 string 接收乐刷退款结果通知的URL，需做Url Encode处理，需要绝对路径，确保乐刷能正确访问
签名 sign M 32 string MD5签名结果

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识,业务状态要看result_code
返回错误信息 resp_msg C 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0 - 成功，非0 - 失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
附加数据 attach O 96 string 退款成功原样返回；注意：只能是汉字、英文字母、数字
商户号 merchant_id M 10 string 由乐刷分配
通道商户号 sub_merchant_id M 无 string 微信、支付宝、QRC商户号
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
订单状态 status M 无 string 详见下方订单状态
乐刷订单号 leshua_order_id M 32 string 乐刷订单号
退款金额 refund_amount M 无 string 退款金额
商户退款id merchant_refund_id M 64 string
乐刷退款id leshua_refund_id M 32 string
订单总金额 total_amount M 无 string 订单总金额
订单余额 order_balance M 无 string 订单余额：本次退款后订单剩余金额
实际退款金额 settlement_refund_amount O 无 string 实际退款金额
折扣优惠退款金额 discount_refund_amount O 无 string 折扣优惠退款金额
退款优惠详情 refund_detail O 无 string 退款优惠详情
请求耗时 cost_time C 无 string 请求接口耗费的时间

4.2、扫码退款查询

请求地址

（1）/cgi-bin/lepos_pay_gateway.cgi

（2）测试商户信息及请求密钥和回调密钥请联系我们获取。

（3）生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司

（4）注: 此接口如果查询到退款状态为中间状态时，会同步向上游查询一次退款状态；如果查询到是退款异常情况时，会同步向上游重新发起一次退款请求。

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string unified_query_refund 注：此为固定值
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id O 64 string
乐刷订单号 leshua_order_id O 32 string 跟third_order_id必填1个
商户退款单号 merchant_refund_id O 64 string
乐刷退款单号 leshua_refund_id O 32 string 跟merchant_refund_id必填1个
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识,业务状态要看result_code
返回错误信息 resp_msg C 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0代表成功，非0代表失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
附加数据 attach O 96 string 原样返回；注意：只能是汉字、英文字母、数字
商户号 merchant_id M 10 string 由乐刷分配
通道商户号 sub_merchant_id M 无 string 微信、支付宝、QRC商户号
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
订单状态 status M 无 string 详见下方订单状态
乐刷订单号 leshua_order_id M 32 string 乐刷订单号
退款金额 refund_amount M 无 string 退款金额
商户退款id merchant_refund_id M 64 string
乐刷退款id leshua_refund_id M 32 string
订单总金额 total_amount M 无 string
退款时间 refund_time O 无 string 退款成功时间：退款成功才返回
实际退款金额 settlement_refund_amount O 无 string 实际退款金额
折扣优惠退款金额 discount_refund_amount O 无 string 折扣优惠退款金额
退款优惠详情 refund_detail O 无 string 退款优惠详情
请求耗时 cost_time C 无 string 请求接口耗费的时间

4.3、扫码退款结果通知

由于诸多因素都会影响到支付结果的通知，推送可能存在延迟，并且不能保证100%推送成功。故强烈建议主接交易查询接口。

通知参数

字段名 变量名 必填 长度限制 类型 说明
错误码 error_code O 无 string 参考错误码信息表
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
订单状态 status M 无 string 详见下方订单状态
失败原因 failure_reason O 无 string 失败原因
附加数据 attach O 96 string 原样返回；注意：只能是汉字、英文字母、数字
商户号 merchant_id M 10 string 由乐刷分配
通道商户号 sub_merchant_id M 无 string 微信、支付宝、QRC商户号
商户订单号 third_order_id M 64 string 商户内部订单号
乐刷订单号 leshua_order_id M 32 string 乐刷订单号
退款金额 refund_amount M 无 string 退款金额
商户退款id merchant_refund_id M 64 string
乐刷退款id leshua_refund_id M 32 string
订单总金额 total_amount M 无 string
退款时间 refund_time C 无 string 退款成功时间：退款成功才返回
折扣优惠退款金额 discount_refund_amount O 无 String 折扣优惠退款金额
实际退款金额 settlement_refund_amount O 无 String 实际退款金额
退款优惠详情 refund_detail O 无 String 退款优惠详情(在退款成功后才返回)

注意：

1、发起退款请求后，乐刷一般30s左右才会返回支付通知，如需快速获取支付结果，请调用“退款”接口发起查询。

返回参数

返回内容 说明
000000 通知成功，乐刷收到此返回后不会继续通知
其他 乐刷收到回复或者未收到回复，系统会再次通知。为避免资源浪费，请核实并确保响应信息的准确性，可以是否重复通知为检查手段

5、扫码订单关闭接口

请求地址

（1）/cgi-bin/lepos_pay_gateway.cgi

（2）测试商户信息及请求密钥和回调密钥请联系我们获取。

（3）生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司

（4）统一条码支付的订单后15秒后才允许调用订单关闭接口，统一下单订单无此限制。
（5）银联二维码的不支持关单

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string close_order（此为固定值）
sign_type sign_type O 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；(不上送默认为使用MD5算法)
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id O 64 string 选填
乐刷订单号 leshua_order_id O 16 string third_order_id和leshua_order_id必填1个，优先使用leshua_order_id
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识，业务状态要看result_code
返回错误信息 resp_msg C 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0 - 成功，非0 - 失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
用户子标识 sub_openid M 无 string
订单状态 status M 无 string
乐刷订单号 leshua_order_id M 32 string 乐刷订单号
交易类型 pay_way M 无 string 详见下方支付类型
订单金额 amount M 无 string
请求耗时 cost_time C 无 string 请求接口耗费的时间
订单状态
值 说明
0 支付中
2 支付成功
6 订单关闭
8 支付失败
10 退款中
11 退款成功
12 退款失败

6、授权码

授权码相关接口与**条码支付接口**配套使用

6.1、授权码查询用户openid

请求地址

（1）/cgi-bin/lepos_pay_gateway.cgi

（2）测试商户信息及请求密钥和回调密钥请联系我们获取。

（3）生产环境走完协议流程并且联调完提交测试报告后，我司运营同事将会提供参数给贵司

（4）注: 此接口需要上送户付款码和对应的微信公众号appid才能查询到用户openid

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string query_openid 注：此为固定值
商户号 merchant_id M 10 string 由乐刷分配
授权码 auth_code M 32 string 微信授权码
微信appid appid M 32 string 微信公众号ID
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识，业务状态要看result_code
返回错误信息 resp_msg C 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0 - 成功，非0 - 失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
用户子标识 sub_openid M 无 string
商户号 merchant_id M 10 string 由乐刷分配
微信用户标识 openid M 无 string 乐刷appid下的用户微信openid

6.2、授权码获取银联云闪付用户ID

简要描述

（1）使用用户授权码换取银联云闪付用户ID，使用此ID发起银联JS支付

注： 此步骤的前置条件：与公司归属银联分公司签署协议，并添加域名白名单获取用户授权码。

请求参数

参数名 变量名 必填 限制 类型 说明
接口名 service M 无 string query_userid（此为固定值）
商户号 merchant_id M 10 string 由乐刷分配
用户授权码 user_auth_code M 无 string
随机字符串 nonce_str M 32 string 随机字符串
银联支付标识 app_up_identifier C 收款方识别HTTP请求User Agent中包含银联支付标识，格式为“UnionPay/<版本号> <App标识>”，注意APP标识仅支持字母和数字。云闪付app支付不填,云闪付外app必填。示例：UnionPay/1.0 ICBCeLife
签名 sign M 32 string MD5签名结果

返回参数

参数名 变量名 必填 限制 类型 说明
返回状态码 resp_code M 无 string 0 - 成功，非0 - 失败。注：此字段是通信标识，业务状态要看result_code
返回错误信息 resp_msg O 无 string 错误描述：resp_code非0时返回
业务结果 result_code M 1 string 0 - 成功，非0 - 失败
错误码 error_code O 无 string 参考错误码信息表
错误码描述 error_msg O 无 string 错误信息描述
商户号 merchant_id M 10 string 由乐刷分配
商户订单号 third_order_id M 64 string 商户内部订单号
随机字符串 nonce_str M 32 string 随机字符串
签名 sign M 32 string MD5签名结果
用户ID user_id O 无 string
支付类型
类型 说明 状态
WXZF 微信 支持
ZFBZF 支付宝 支持
UPSMZF 银联二维码 支持
DCPAY 数字货币 支持
订单状态
值 说明
0 支付中
2 支付成功
6 订单关闭
8 支付失败
10 退款中
11 退款成功
12 退款失败
付款银行类型
通道 说明
微信 https://pay.weixin.qq.com/wiki/doc/api/mch_bank.php?chapter=4_2
支付宝 https://alipay.open.taobao.com/doc2/detail?treeId=26&articleId=103259&docType=1
银联二维码 1 - 借记卡 2- 贷记卡
业务拓展参数示例（支付宝小程序需传）
"extend_business_params": "{ "
business_params ": {
 "bizSource": "mAppQrFood",
 "sourcePath": "pageFoodChain/shopTakeOut/main?suid=10"
	},
	"goods_detail": [{
 "goods_id": "5544",
 "goods_name": "爽口青笋丝",
 "price": "0.50",
 "quantity": 2,
 "goods_category": "888",
 "categories_tree": "888",
 "body": "爽口青笋丝",
 "show_url": "pageFoodChain/storeDetail/main?suid=10"
	}], "extend_params": {
 "sys_service_provider_id": "208812333665551",
 "food_order_type": "home_delivery"
	}
}",

条码支付接口goods_detail，按银联单品营销格式传递**参数goodsInfo，格式如下**

 "goods_detail":{ 
   "goodsInfo" : [
     {
   		"id": "1234567890",
   		"name": "商品 1", 
   		"price": "500", 
   		"quantity": "1"},
     {  
       "id": "1234567891",
       "name": "商品 2",
       "price": "1000",
       "quantity": "2",
       "category": "类目 1",
       "addnInfo": "商品图片 http://www.95516.com/xxx.jpg"}]
 },

7、刷卡及扫码支付异步通知

采用HTTP 标准的POST协议（请使用 application/x-www-form-urlencoded 此Content-Type接收通知消息），为了保证数据正确性、准确性，数据必须验证签名。

返回数据（支付成功通知如下）

<leshua>
    <error_code>0<error_code>
     <amount>1<amount>
     <attach>0<attach>
     <bank_type>ALIPAYACCOUNT<bank_type>
     <buyer_pay_amount><buyer_pay_amount>
     <channel_datetime>2018-12-07 22:42:39<channel_datetime>
     <channel_order_id>7551000001201812073279154152<channel_order_id>
     <coupon>0<coupon>
     <discount_amount>0<discount_amount>
     <goods_tag><goods_tag>
     <leshua_order_id>1812072242293655<leshua_order_id>
     <merchant_id>0000000018<merchant_id>
     <openid>2088032562556921<openid>
     <out_transaction_id>2018120722001456935441223102<out_transaction_id>
     <pay_time>2018-12-07 22:42:39<pay_time>
     <pay_way>ZFBZF<pay_way>
     <royalty>0<royalty>
     <settlement_amount>1<settlement_amount>
     <sign>0b574d40e722ec76b55d4e8795f71182<sign>
     <status>2<status>
     <sub_openid><sub_openid>
     <third_order_id>20181207224223102101<third_order_id>
     <trade_type>NATIVE<trade_type>
<leshua>

返回数据（刷卡支付成功通知如下）

<leshua>
<error_code>0</error_code>    
<amount>600</amount>    
<authorize_code>000000</authorize_code> 
<batch_no>000010</batch_no>   
<card_type></card_type>    
<cups_merchant_id>890584058130851</cups_merchant_id>  
<cups_terminal_id>89147601</cups_terminal_id>  
<flow_id>000109</flow_id>  
<leshua_order_id>2203221139307885</leshua_order_id> 
<leshua_refund_id>220322393155923079</leshua_refund_id> 
<leshua_sn>2041000394</leshua_sn> 
<merchant_id>6012514015</merchant_id>   
<merchant_returngoods_id>20220322114213731</merchant_returngoods_id>
<pan_overseas></pan_overseas>    
<pan_type></pan_type>   
<reference_number>113935096395</reference_number>    
<returngoods_time>2022-03-22 11:41:43</returngoods_time>   
<sign>21e70c91171b8d6ba00dea3c3ef6affa</sign>
<sn>218JCA8L7760</sn>
<status>32</status>   
<third_order_id>20220322114005352</third_order_id>    
<transaction_id>220322393155923079</transaction_id>
</leshua>

返回数据（扫码退款成功通知如下）

<leshua> 
  <error_code>0</error_code>  
  <attach/>  
  <discount_refund_amount>0</discount_refund_amount>  
  <leshua_order_id>90001401275201</leshua_order_id>  
  <leshua_refund_id>90002391275201</leshua_refund_id>  
  <merchant_id>9115219</merchant_id>  
  <merchant_refund_id>0000091152192752007041753</merchant_refund_id>  
  <nonce_str>mccqvx9q0d5nifcsd0uv9xlmkxgr6kdg</nonce_str>  
  <refund_time>2020-07-04 17:53:24</refund_time>  
  <settlement_refund_amount>1000</settlement_refund_amount>  
  <sign>426adb68310b659953d18b629c1a2e7e</sign>  
  <status>11</status>  
  <sub_merchant_id>208860057301617</sub_merchant_id>  
  <third_order_id>0000091152192752007041749</third_order_id>  
  <total_amount>5500</total_amount> 
</leshua>

7.1 扫码支付成功通知

（1）通知 URL 是代理商后台配置的通知地址。扫码支付成功后，乐刷会把相关支付信息和用户信息发送到该 URL，商户需要接收处理信息。对后台通知交互时，如果收到商户的应答不是成功或者超时，乐刷认为通知失败，会通过一定的策略定期重新发起通知，尽可能的提高通知的成功率，但是不保证通知最终一定能成功。由于存在重复发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。系统必须能够正确处理重复的通知。

（2）验证签名方法：通知的 error_code、sign 字段不参与签名，签名方式参照数据格式及数据签名说明，其中签名 key 统一由乐刷提供。另外，组织签名串时空值也参与签名。

通知参数

字段名 变量名 必填 长度限制 类型 说明
错误码 error_code 否 无 string 参照错误码信息参照表
sign_type sign_type 否 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法；
签名 sign 是 32 string MD5 签名结果
商户号 merchant_id 是 10 string 乐刷商户号
乐刷订单号 leshua_order_id 是 32 string
商户订单号 third_order_id 是 64 string
订单金额 amount 是 无 string
订单状态 status 是 无 string 见下方订单的状态
支付类型 pay_way 是 无 string 见下方支付类型
支付时间 pay_time 是 无 string '2018-08-20 19:19:19'
银行类型 bank_type 否 无 string
用户openid openid 否 无 string
微信、支付宝等订单号 out_transaction_id 否 无 string
用户子标识 sub_openid 否 无 string 支付成功时才返回。微信：子商户appid 下用户唯一标识；支付宝：买家的支付宝用户id；
附加数据 attach 否 96 string 支付成功时才返回。原样返回
交易类型 trade_type 否 无 string 支付成功时才返回。（1）MICROPAY--刷卡支付/条码支付（2）NATIVE--原生扫码支付（3）JSAPI--公众号支付/服务窗支付（4）APP--app支付（5）H5Pay-支付支付（6）SmPgPay-小程序支付（7）JSAPIQuick-简易支付
通道订单号 channel_order_id 否 无 string 支付成功时才返回
通道订单时间 channel_datetime 否 无 string 支付成功时才返回
支付宝红包金额 coupon 否 无 string 支付成功时才返回，单位：分
应结算金额 settlement_amount 否 无 string 实际结算金额，支付成功时才返回，单位：分
折扣优惠金额 discount_amount 否 无 string 本订单优惠金额，支付成功时才返回，单位：分
优惠详情 promotion_detail 否 无 string 优惠详情：微信官网
活动标志 active_flag 否 无 string 活动标志：WXLZ：微信绿洲，ZFBLH：支付宝蓝海
商户终端编号 pos_no 否 60 string 只能是汉字、英文字母、数字 注意：银联类型交易时，只能 8位：数字字母 不支持 特殊字符

返回参数

字段名 说明
000000 通知成功，乐刷收到此返回后不会继续通知
其他 乐刷收到回复或者未收到回复，系统会再次通知。为避免资源浪费，请核实并确保响应信息的准确性，可以是否重复通知为检查手段。
支付类型
类型 说明 状态
WXZF 微信 支持
ZFBZF 支付宝 支持
UPSMZF 银联二维码 支持
QQZF QQ 支持
POS 刷卡 支持
DCPAY 数字货币 支持
UPSMPAY 银联二维码(回调时返回) 支持
订单状态值
值 说明
0 支付中
2 支付成功
6 订单关闭
8 支付失败
10 退款中
11 退款成功
12 退款失败
30 刷卡支付成功
31 刷卡撤销成功
32 刷卡退货成功
33 刷卡冲正成功

7.2 扫码退款通知

（1）通知 URL 与扫码支付成功通知一样，均为代理商后台配置的通知地址。扫码交易退款时、退款成功时、退款失败时，乐刷均会把相关退款信息发送到该 URL，商户需要接收处理信息。对后台通知交互时，如果收到商户的应答不是成功或者超时，乐刷认为通知失败，会通过一定的策略定期重新发起通知，尽可能的提高通知的成功率，但是不保证通知最终一定能成功。由于存在重复发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。系统必须能够正确处理重复的通知。

（2）验证签名方法：通知的 error_code、sign 字段不参与签名，签名方式参照第 3 章 数据签名，其中签名 key 统一由乐刷提供。另外，组织签名串时空值也参与签名。

通知参数

字段名 变量名 必填 长度限制 类型 说明
签名 sign 是 32 string MD5 签名结果
sign_type sign_type 否 10 string 接口签名类型::MD5/SM3。 支持MD5和国密SM3算法
订单状态 status 是 无 string 见下方订单状态
失败原因 failure_reason 否 无 string 失败原因
商户号 merchant_id 是 10 string 由乐刷分配
商户订单号 third_order_id 是 64 string 商户内部订单号
乐刷订单号 leshua_order_id 是 32 string 乐刷订单号
退款金额 refund_amount 是 无 string 退款金额（分）
商户退款 id merchant_refund_id 是 64 string
乐刷退款 id leshua_refund_id 是 32 string
订单总金额 total_amount 是 无 string
退款时间 refund_time 否 无 string 退款成功时间-退款成功才返回

返回参数

字段名 变量名
000000 通知成功，乐刷收到此返回后不会继续通知
其他 乐刷收到回复或者未收到回复，系统会再次通知
订单状态
值 说明
0 支付中
2 支付成功
6 订单关闭
8 支付失败
10 退款中
11 退款成功
12 退款失败
30 刷卡支付成功
31 刷卡撤销成功
32 刷卡退货成功
33 刷卡冲正成功

7.3 刷卡交易通知

（1）通知 URL 与扫码支付成功通知一样，均为代理商后台配置的通知地址。刷卡交易成功时、刷卡撤销成功时、刷卡退货成功时、刷卡冲正成功时，乐刷均会把相关交易信息发送到该 URL，商户需要接收处理信息。对后台通知交互时，如果收到商户的应答不是成功或者超时，乐刷认为通知失败，会通过一定的策略定期重新发起通知，尽可能的提高通知的成功率，但是不保证通知最终一定能成功。由于存在重复发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。系统必须能够正确处理重复的通知。

（2）验证签名方法：通知的 error_code、sign 字段不参与签名，签名方式参照第 3 章 数据签名，其中签名 key 统一由乐刷提供。另外，组织签名串时空值也参与签名。

（3）境外卡统一按照贷记卡费率进行结算，所以返回2

通知参数

字段名 变量名 必填 长度限制 类型 说明
签名 sign 是 32 string MD5 签名结果
订单状态 status 是 无 string 详见下方订单状态
结算类型 T0 是 无 string
设备SN号 sn 是 无 string 硬件序列号和机身上一致
授权码 authorize_code 是 6 string 普通交易下返回000000 预授权交易不固定
失败原因 failure_reason 否 无 string 失败原因
商户号 merchant_id 是 10 string 由乐刷分配
商户订单号 third_order_id 是 64 string 商户内部订单号
退货时，返回原订单的第三方订单号
乐刷订单号 leshua_order_id 是 32 string 乐刷订单号
退货时，返回原订单的乐刷订单号
交易金额 amount 是 无 string 交易金额（分）
银行卡号 card_id 否 无 string 刷卡交易时提供
卡类型 card_type 否 1 string 1----借记卡
2----贷记卡 3---- 准贷记
发行主体 pan_overseas 否 1 string 0----境内卡 1----境外卡
结算方式 pan_type 否 1 string (1使用商户借记卡费率，非1使用商户贷记卡费率 ) 0-----未知 1-----借记 2-----贷记 3-----准贷记 4-----借贷合一 5-----预付费 6-----半开放预付费
发卡行 bank_name 否 无 string 刷卡交易时提供
刷卡pos批次号 batch_no 是 无 string 每次签到后从后台获取批次号，当批交易均上送此批次号
刷卡pos流水号 flow_id 是 3 string 终端为每个交易随机生成的流水号，随交易信息上送
乐刷SN号 leshua_sn 是 无 string 刷卡交易时提供
刷卡pos参考号 reference_number 是 32 string POS中心分配的流水号，作为对账参考号
银联商户号 cups_merchant_id 否 20 string 表示上送银联的商户编号
银联终端号 cups_terminal_id 否 8 string 表示上送银联的终端编号
交易流水号 transaction_id 否 18 string 用于表示此操作的流水号
刷卡交易时间 pay_time 否 无 string 刷卡交易时提供
消费撤销时间 refund_time 否 无 string 消费撤销时提供
消费退货时间 returngoods_time 否 无 string 消费退货时提供
消费冲正时间 reverse_time 否 无 string 消费冲正时提供
商户撤销id merchant_refund_id 否 无 string 消费撤销时提供
第三方传入的撤销订单号
商户退货id merchant_returngoods_id 否 无 string 消费退货时提供
第三方传入的退货订单号
乐刷退款id leshua_refund_id 否 18 string 消费退货时提供
乐刷生成的退货流水号
商户冲正id merchant_reverse_id 否 无 string 消费冲正时提供
第三方传入的冲正订单号
到账标识 t0 否 1 String 0：表示t1到账 1：表示t0到账； 刷卡交易时提供

返回参数

字段名 变量名
000000 通知成功，乐刷收到此返回后不会继续通知
其他 乐刷收到回复或者未收到回复，系统会再次通知
订单状态
值 说明
30 刷卡支付成功
31 刷卡撤销成功
32 刷卡退货成功
33 刷卡冲正成功
41 预授权成功
43 预授权撤销成功
45 预授权完成（请求）成功
47 预授权完成（通知）成功
49 预授权完成撤销成功

7.4 刷卡交易查询

请求地址：/agentCardTransaction/cardFlowQuery

加密规则： md5hex(代理商密钥+reqSerialNo+version+ data的 json 串)

请求参数：

名称 类型 是否必须 默认值 备注 其他信息
version string 必须 版本号
agentId string 必须 代理商编号
sign string 必须 验签值
reqSerialNo string 必须 随机字符串，一般为一个和日期有关的随机数
data object 非必须
└merchantId string 必须 商户号
└operation string 必须 操作类型（query_by_order,query_by_transaction,query_by_third_order)）
└orderId string 非必须 订单编号
└transactionId string 非必须 交易单号
└thirdOrderId string 非必须 第三方订单号

返回参数：

名称 类型 是否必须 默认值 备注 其他信息
traceId string 必须 请求序列号
code integer 必须 错误码
message string 必须 错误信息
data object 非必须
└orderId string 非必须 乐刷订单号
└errorCode integer 非必须 请求错误码，成功为0
└errorMsg string 非必须 错误提示信息，成功时值为空
└thirdOrderId string 非必须 商户内部订单号
└merchantId string 非必须 乐刷商户号
└amount integer 非必须 交易金额
└orderStatus integer 非必须 订单状态,0-初始状态(可能交易失败);5-交易成功;11-交易失败;53-交易失败(冲正成功);54-交易结果未知(冲正失败);3-退款成功;32-退款失败;33-退款状态未知;4-退货成功;41-退货失败;42-退货状态未知
└batchNo string 非必须 POS交易批次号
└flowNo string 非必须 POS交易流水号
└sign string 非必须 签名
└merchantName string 非必须 乐刷商户名称
transactionsInfo object [] 非必须 流水 item 类型: object
└merchantId string 非必须 乐刷商户号
└pinpadUuid string 非必须 乐刷SN
└channelMerchantId string 非必须 通道商户号
└channelTerminalId string 非必须 通道终端号
└operationType integer 非必须 操作类型，与订单状态一致
└inputType string 非必须 交易用卡方式：051-插卡有密交易;052-插卡无密交易;071-挥卡有密交易;072-挥卡无密交易;
└cardBank string 非必须 发卡行名称
└authorizeCode string 非必须 交易授权码
└referenceNo string 非必须 交易参考号
└cardId string 非必须 交易卡号
└pinpadSn string 非必须 机具终端硬件号TUSN
└time string 非必须 交易时间
└cardType integer 非必须 卡类型：0(借记卡)，2(贷记卡)
└channelBatchNo string 非必须 通道交易批次号
└channelFlowNo string 非必须 通道交易流水号
└transactionId string 非必须 乐刷流水号
└channelId string 非必须 通道id
└channelMerchantName string 非必须 通道商户名称
└amount string 非必须 流水金额

8、交易错误码信息参照表

错误码 描述
-20001 参数错误或无效
-20002 无效的乐刷商户号
-20003 商户订单号格式有误
-20004 乐刷订单不存在
-20005 服务错误
-20006 验签失败
-20007 签名 Key 未配置
-20008 支付类型错误
-20009 订单金额填写有误
-20010 系统错误
-20011 非法参数
-20012 授权码为空
-20013 非法的授权码
-20014 未知类型的授权码
-20015 非法的公众号支付标识
-20016 无效乐刷订单号
-20018 无效的第三方订单号或者乐刷订单号
-20019 订单状态不允许退款
-20020 订单未退款
-20021 用户名跟商户ID不匹配
-20022 无效的第三方退款订单号
-20023 订单可退余额不足
-20024 乐刷或第三方订单号必填 1 个
-20025 乐刷或第三方退款订单号必填 1 个
-20026 第三方订单号在该商户号下已经存在
-20027 该订单已支付
-20028 订单支付失败，不能撤销
-20029 该订单已退款
-20030 该订单退款失败，不能撤销
-20031 无效的机具 SN 编号，请联系客服
-20032 机具 SN 跟商户无绑定关系
-4027 系统异常
-4006 订单不存在
-1006 该订单号已被用
-1002 无效商户号
-2034 测试商户号金额限制
-4004 订单正在处理中
-5103 商户退款 id 已存在
-5014 商户无退款权限
-5015 暂不支持退款
-5016 订单状态异常
-5017 订单可退金额不足
-5018 订单退款次数超限
-5019 订单未发起退款
-5020 接口不支持该功能
-2125 交易被风控拦截
-5035 下单异常，可能原因有通道网络异常，通道状态异常，通道商户异常等

以实际返回的错误提示(error_msg)为准

Reference in New Issue View Git Blame Copy Permalink