docs: 新增联合收单与扫呗接口文档
This commit is contained in:
yml2213
@@ -0,0 +1,7 @@
|
||||
# 扫呗（乐刷）开发文档
|
||||
|
||||
- [接入指引](接入指引.md)
|
||||
- [普通支付2.0 API](普通支付2.0-API.md)
|
||||
|
||||
- 接入指引来源：<https://help.lcsw.cn/xrmpic/q6imdiojes7iq5y1/qg52lx>
|
||||
- 普通支付2.0来源：<https://help.lcsw.cn/xrmpic/tisnldchblgxohfl/rinsc3>
|
||||
@@ -0,0 +1,217 @@
|
||||
# 接入指引
|
||||
|
||||
> 来源：<https://help.lcsw.cn/xrmpic/q6imdiojes7iq5y1/qg52lx>
|
||||
|
||||
## 开始接入
|
||||
|
||||
|
||||
|
||||
**温馨提示**：阅读本文档之前，请认真仔细的确认您已经执行了下面的三步操作，并获得了有效的扫呗接入资料：
|
||||
|
||||
1. 签订合作协议。
|
||||
2. 联系业务BD提交扫呗内部接口对接申请。
|
||||
3. 开发人员与扫呗技术支持建立联系。
|
||||
4. 联系业务BD或者运营同事，提交资料进行商户开户。
|
||||
5. 对接支持同事基于正式商户映射测试商户，或提供其它对接测试参数。
|
||||
|
||||
## 测试环境准备
|
||||
|
||||
**⑴测试服务地址**
|
||||
|
||||
具体测试地址以对接支持同事邮件内提供的地址为准。
|
||||
|
||||
**⑵测试账号**
|
||||
|
||||
测试账号统一由我司技术同学分配。因支付需要真实扣款，若对接的是支付接口，需先联系业务同事或者项目运营同事，创建商户同主体的正式商户后，才能提供测试商户。
|
||||
|
||||
- 对接商户接口需以下参数：
|
||||
- 机构号`inst_no`
|
||||
- 令牌`key`
|
||||
- 对接支付接口需以下参数：
|
||||
- 商户号`merchant_no`
|
||||
- 终端号`terminal_id`
|
||||
- 令牌`access_token`
|
||||
|
||||
拿到测试环境后，合作方即可进入测试联调阶段，有问题可在相关对接群中咨询技术同学，由于支持群较多，在咨询问题时，最好是@对应对接支持同事。
|
||||
|
||||
## 对接测试辅助工具
|
||||
|
||||
测试工具页：[http://test2.lcsw.cn:8117/demo/](http://test2.lcsw.cn:8117/demo/)
|
||||
|
||||
使用该页面设置好商户号、终端号、终端密钥，可测试接口的调用，查看请求报文、返回报文、请求签名串等，常用工具中还可拼接字典序签名串。字典序通用请求中，可请求字典序的接口，获取签名串。
|
||||
|
||||
注意：如果是正式环境商户信息，注意将接口地址切换到正式。
|
||||
|
||||
## 生产环境
|
||||
|
||||
注意：
|
||||
|
||||
接口联调必须先在测试环境联调，由技术同学验收通过后，才可正式
|
||||
|
||||
接入线上生产环境。
|
||||
|
||||
生产环境账号参数：由商务或运营同事提供
|
||||
|
||||
生产环境域名：统一由技术同学提供
|
||||
|
||||
> 以上资料在测试环境中和生产环境中并不相同，准备调试和切换环境时请认真核对并确认无误。
|
||||
>
|
||||
|
||||
## 开通支付通道
|
||||
|
||||
- 微信公众号 合作商如需对接公众号支付接口，需提供**微信应用ID（AppID）**、**应用密钥（AppSecret）**以及**支付授权目录**，在相关参数配置完毕后，再联系扫呗技术人员，获取测试商户号、测试终端号以及测试接口域名。
|
||||
- QQ钱包 合作商如需使用QQ钱包支付通道，需要提供**QQ钱包商户号**、**QQ钱包key**、**QQ钱包证书密码**以及**QQ钱包退款密码**，在后台配置好相关参数后，方可开通QQ钱包支付通道。
|
||||
- 京东钱包 合作商如需使用京东钱包支付通道，需要提供**京东钱包商户号**、**京东钱包密钥**，在后台配置好相关参数后，方可开通京东钱包支付通道。
|
||||
- 微信及支付宝的刷卡支付、扫码支付 合作商如需对接微信、支付宝的预支付、扫码支付的接口，可直接联系扫呗技术人员，获取测试商户号、测试终端号以及测试接口域名。
|
||||
|
||||
## 通信协议
|
||||
|
||||
本文档中的所有接口，未明确说明的，均采用HTTP标准通信协议，请求和响应的`Content-type`均为`application/json`，字符编码统一为`UTF-8`。
|
||||
|
||||
`注："商户回调通知"接口、"交易通知"接口、"交易实时同步"接口Content-type为text/xm`。
|
||||
|
||||
## 签名算法
|
||||
|
||||
`httpclient方式发起的接口请求，请求和接收数据均需要校验签名。`[签名测试工具](http://test2.lcsw.cn:8117/demo/index1.html)
|
||||
|
||||
`拼接串说明`：接口中每一个字段(key_sign字段除外),以字典顺序(字母顺序)排序之后,按照a=value1&b=value2.....&`令牌标识`="密钥"的顺序,进行拼接。对得到的字符串进行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" ；
|
||||
|
||||
> ❗
|
||||
>
|
||||
> 特别注意：
|
||||
>
|
||||
> 1. 赋值的空字符串需参与签名；如"attach": ""，需要拼接***&attach=&***
|
||||
> 2. 接口中包含terminal_id(终端号)字段的，令牌标识为“access_token”这个单词，待签名字符串格式:string2=string1+"&access_token=终端密钥";
|
||||
> 3. 接口中包含inst_no(机构号)字段的，令牌标识为“key”这个单词，待签名字符串格式: string2=string1+"&key=机构密钥";
|
||||
>
|
||||
|
||||
通过MD5取得签名字符串: key_sign=md5(string2)
|
||||
|
||||
## JAVA-SDK
|
||||
|
||||
### SDK下载
|
||||
|
||||
SDK文件：[java-sdk-1.2.1](https://open.lcsw.cn/document/支付2.0java-sdk-1.2.1.zip)
|
||||
|
||||
> ❗
|
||||
>
|
||||
> 特别注意：
|
||||
>
|
||||
> SDK主要提供普通支付2.0的接口方法，暂未提供其它接口的实体类以及请求方法。其它接口可使用SDK内的签名工具，并自行编写实体类和请求方法。
|
||||
>
|
||||
|
||||
### SDK引入方式参考
|
||||
|
||||
1. 方式一：IDEA或者Eclipse引入本地jar包的方式。具体操作可网上搜索对应开发工具添加jar包的步骤。
|
||||
2. 方式二：使用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>
|
||||
```
|
||||
|
||||
1. 方式三：在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>
|
||||
```
|
||||
|
||||
### 工具类
|
||||
|
||||
> ❗
|
||||
>
|
||||
> 特别说明：
|
||||
>
|
||||
> 1. SDK主要提供工具类，便于对请求参数进行签名或者返回参数验签。
|
||||
> 2. SDK内有部分接口的实体类，若在SDK内没找到对应实体类，请自行定义实体类。
|
||||
> 3. 若SDK内存在的实体类字段与接口内字段不一致的，可自行创建子类定义属性，并继承原实体类。
|
||||
>
|
||||
|
||||
`注：目前只提供java语言的SDK,其它开发语言请自行按照签名算法要求进行拼接签名`
|
||||
|
||||
**ApiUtil工具类**：主要提供构建请求参数和返回参数，可自动进行签名和验签。
|
||||
|
||||
```
|
||||
//构造请求参数并对报文自动加签，t为设置好请求参数的实体对象。使用了该方法，不需要再使用SignBeanUtil工具类进行签名
|
||||
JSONObject request = ApiUtil.convertRequest(t,"填机构密钥或者终端密钥","填令牌标识，请看《签名算法》章节-特别注意-的说明");
|
||||
|
||||
//转换返回（或回调）参数并对报文自动验签，response为接口返回参数，t为创建好的返回参数接收对象。使用了该方法，不需要再使用SignBeanUtil工具类进行签名
|
||||
t = ApiUtil.convertResponse(response,t,"填机构密钥或者终端密钥","填令牌标识，请看《签名算法》章节-特别注意-的说明");
|
||||
```
|
||||
|
||||
**SignBeanUtil工具类**：主要提供参数的字典序排序后的签名方法。
|
||||
|
||||
```
|
||||
//参数签名方法，若使用了ApiUtil工具类的封装参数方法，无需使用该方法在签名。t为请求参数，key_sign和utf-8为固定字符串不用修改。
|
||||
SignBeanUtil.FilterNullSign(t, "填令牌标识，请看《签名算法》章节-特别注意-的说明","填机构密钥或者终端密钥", "key_sign", "utf-8");
|
||||
```
|
||||
|
||||
**HttpClientUtil工具类**：主要提供post请求方法。
|
||||
|
||||
```
|
||||
//serviceUrl为接口完整url地址，request为请求参数（可用ApiUtil工具转换请求参数），timeout为接口超时时间（单位ms），response为返回参数（可用ApiUtil工具转换成返回实体）
|
||||
String response = HttpClientUtil.post(serviceUrl,JSON.toJSONString(request), timeout,"application/json","utf-8");
|
||||
```
|
||||
|
||||
### 通用方法
|
||||
|
||||
以下方法，可应用与所有post请求，且使用字典序签名的接口。方法内会自动进行签名，故不需要为接口中的key_sign字段赋值。
|
||||
|
||||
```
|
||||
OpenParameters.Builder builder=new OpenParameters.Builder();
|
||||
builder.apiName("接口地址");//对应接口上的url部分地址，如/pay/open/query
|
||||
builder.apiUrl("接口域名");//请使用对应接口域名，将和apiName拼接成完整接口地址。如http://www.lcsw.cn/lcsw
|
||||
builder.param(json.toString());//按照接口字段要求为实体对象属性赋值后转json并toString。
|
||||
OpenParameters openParameters = builder.build();//实例化对象
|
||||
//创建client
|
||||
SaobeiApiClient client = new DefaultSaobeiApiClient<>("终端密钥或机构密钥");
|
||||
String execute = client.execute(openParameters);//返回参数已自动进行了验签
|
||||
```
|
||||
|
||||
## 警告
|
||||
|
||||
**密钥**是一个非常重要的数据，请您必须小心谨慎的确保此数据保存在足够安全的地方。您从扫呗官方获得此数据的同时，即表明您保证不会被用于非法用途和不会在没有得到您授权的情况下被盗用，一旦因此数据保管不善而导致的经济损失及法律责任，均由您独自承担。
|
||||
|
||||
## 支付流程
|
||||
|
||||
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,150 @@
|
||||
# 代理商维度接入 <-这里可点
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/mu5beo0vhypgdskb>
|
||||
|
||||
## 接入指南（须知）
|
||||
|
||||
**！注意：【商户交易】文档内接口为独立内容，无需参考此接入指南，按照【商户交易】文档描述对接即可**
|
||||
|
||||
## 1.1 参数格式与调用方式
|
||||
|
||||
（1）接口传输的所有参数使用 UTF-8 编码格式，包括签名。接口以 https的POST方式进行调用。
|
||||
|
||||
（2）Content-Type为application/json
|
||||
|
||||
（3）域名：
|
||||
|
||||
测试环境：[https://t-uts.lepass.cn](http://t-uts.lepass.cn)
|
||||
|
||||
生产环境：[https://uts.leshuazf.com](https://uts.leshuazf.com)
|
||||
|
||||
## 1.2 报文结构
|
||||
|
||||
**请求报文**
|
||||
|
||||
请求报文由一级服务商编号、当前代理商编号、版本号、请求流程号、签名串、验签方式、报文主体7个参数组成。说明如下：
|
||||
|
||||
**注意： ****M：must，必须；**
|
||||
|
||||
**C：condition，条件必填；**
|
||||
|
||||
**O：option，可选；**
|
||||
|
||||
| **参数名称** | **类型** | **长度限制** | **是否必输** | **说明** |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| agentId | String | 无 | M | 服务商编号，由乐刷分配的接入方唯一标识，明文传输。 |
|
||||
| currentAgentId | String | 无 | M | 当前代理商编号（操作来源） |
|
||||
| version | String | 无 | O | 目前固定值1.0 |
|
||||
| reqSerialNo | String | 无 | O | 请求流水号(yyyyMMddHHmmssSSSXXXXX，其中 XXXXX为5位顺序号,禁止使用UUID等无意义数据) |
|
||||
| sign | String | 无 | M | 签名串 |
|
||||
| algorithm | boolean | 无 | O | 默认true-国密验签，false-MD5验签 |
|
||||
| data | Object | 无 | M | 业务数据 |
|
||||
|
||||
> 💡 注意，请求列表时，每页最多请求50条
|
||||
>
|
||||
|
||||
**返回报文**
|
||||
|
||||
返回报文由error_code、error_msg、count、业务数据报文主体4个参数组成。说明如下：
|
||||
|
||||
| **参数名称** | **类型** | **长度限制** | **是否必输** | **说明** |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| error_code | String | 无 | M | 业务响应码 0-成功 |
|
||||
| error_msg | String | 无 | O | 错误信息 |
|
||||
| count | long | 无 | O | 记录总数 |
|
||||
| data | Object | 无 | O | 业务数据 |
|
||||
|
||||
## 1.3 数据签名
|
||||
|
||||
签名算法（sign）如下：
|
||||
|
||||
**（1）国密验签：**
|
||||
|
||||
**sign=SMUtil**.**encryptBySM3WithSalt(渠道商固定key值, ****JSON.toJSONString****(data))**
|
||||
|
||||
例: key=XXXXXXXXXXXXXXXXXX，请求报文中，data={"merchantId":"0123456789"}
|
||||
|
||||
sign=SMUtil.encryptBySM3WithSalt("XXXXXXXXXXXXXXXXXX", "{"merchantId":"0123456789"}")
|
||||
|
||||
SMUtil工具类见文末
|
||||
|
||||
**（2）MD5验签：**
|
||||
|
||||
**sign= md5(渠道商固定key值+****JSON.toJSONString****(data)).toUpperCase())**
|
||||
|
||||
例: 请求报文中，data={"merchantId":"0123456789"}
|
||||
|
||||
待签名串为: XXXXXXXXXXXXXXXXXX{"merchantId":"0123456789"}
|
||||
|
||||
MD5后转大写: A4A5BF63CADF23F4AA78A3D642B75B8E
|
||||
|
||||
> 💡 注意，使用JSON.toJSONString的目的是将data转化成内容为ascii码排序键值对的字符串，例如{"a":{"d":"D","e":"E"},"b":"B","c":"C"}
|
||||
>
|
||||
> 💡 fastjson版本需为1.2.27或更高版本，如果单独使用JSON.toJSONString无法实现排序效果，可添加参数MapSortField，例如：JSON.toJSONString(data, SerializerFeature.MapSortField)，如果开发语言非java，也可手动拼接再转字符串
|
||||
>
|
||||
> 💡 加签时data中的字段可以少传，不能多传，并且类型需与文档说明完全一致，例如手机号虽为全数字，但为String类型
|
||||
>
|
||||
|
||||
## 签名工具类
|
||||
|
||||
**验签工具类**SignUtil，注意：此工具类不适用【商户交易】接口
|
||||
|
||||
```java
|
||||
package test;
|
||||
|
||||
import cn.hutool.core.codec.Base64;
|
||||
import cn.hutool.crypto.digest.MD5;
|
||||
|
||||
import com.alibaba.fastjson.JSONObject;
|
||||
import com.alibaba.fastjson.JSON;
|
||||
import com.alibaba.fastjson.serializer.SerializerFeature;
|
||||
import org.bouncycastle.crypto.digests.SM3Digest;
|
||||
import org.bouncycastle.crypto.macs.HMac;
|
||||
import org.bouncycastle.crypto.params.KeyParameter;
|
||||
|
||||
public class SignUtil {
|
||||
|
||||
|
||||
public static void main(String[] args) {
|
||||
// 渠道商固定key值
|
||||
String key = "ZDJMY2EYOTETNDDJMI00YZAZLWIYNMETMZZLNDEZZTYXMJLM";
|
||||
|
||||
// 业务数据
|
||||
JSONObject jsonObject = new JSONObject();
|
||||
jsonObject.put("merchantId", "3131014839");
|
||||
jsonObject.put("currentAgentId", "315605362");
|
||||
|
||||
String sm3Sign = "1rONut2RbElyf949MbtoohlWqtjFTeVzmgJs88kC2P0=";
|
||||
String realSm3Sign = SM3Encrypt(key, JSON.toJSONString(jsonObject, SerializerFeature.MapSortField));
|
||||
System.out.println("国密验签结果：" + sm3Sign.equals(realSm3Sign) + "，真实sign：" + realSm3Sign + "，传入sign：" + sm3Sign);
|
||||
|
||||
String md5Sign = "E5FACB67B9904FC21F2D60325A3F5034";
|
||||
String realMd5Sign = MD5Encrypt(key, JSON.toJSONString(jsonObject, SerializerFeature.MapSortField));
|
||||
System.out.println("MD5验签结果：" + md5Sign.equals(realMd5Sign) + "，真实sign：" + realMd5Sign + "，传入sign：" + md5Sign);
|
||||
}
|
||||
|
||||
// 国密验签，推荐使用
|
||||
public static String SM3Encrypt(String key, String srcData) {
|
||||
System.out.println("SM3Encrypt，待加密数据：" + srcData);
|
||||
return Base64.encode(hmac(key.getBytes(), srcData.getBytes()));
|
||||
}
|
||||
|
||||
public static byte[] hmac(byte[] key, byte[] srcData) {
|
||||
KeyParameter keyParameter = new KeyParameter(key);
|
||||
SM3Digest digest = new SM3Digest();
|
||||
HMac mac = new HMac(digest);
|
||||
mac.init(keyParameter);
|
||||
mac.update(srcData, 0, srcData.length);
|
||||
byte[] result = new byte[mac.getMacSize()];
|
||||
mac.doFinal(result, 0);
|
||||
return result;
|
||||
}
|
||||
|
||||
// MD5验签
|
||||
public static String MD5Encrypt(String key, String srcData) {
|
||||
System.out.println("MD5Encrypt，待加密数据：" + srcData);
|
||||
return MD5.create().digestHex(key + srcData).toUpperCase();
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,457 @@
|
||||
# 基础接口
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/imdpgnoa19kpnxv1>
|
||||
|
||||
### 上传图片
|
||||
|
||||
通过此接口上传商户的活体图片。
|
||||
|
||||
> - **URL**：`/open-api/common/uploadPic`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `ext` | String | M | 扩展名，限制jpg/png/jpeg |
|
||||
| `picData` | String | M | base64编码的图片数据，2M以内 |
|
||||
|
||||
> 💡 注意，目前只支持jpg、jpeg、png格式的图片
|
||||
>
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "123456789abcde",
|
||||
"agentId": "1234567",
|
||||
"data": {
|
||||
"ext": "jpg",
|
||||
"picData": "/9j/4QkDRXhpZgAATU0AKgBBBBg……"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `path` | String | 图片路径 |
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": {
|
||||
"path": "picture/M00/07/5E/rBQhymPXhGCATiPIHNGomYn0Pz3215.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：请求数据非法，例如 图片格式错误。
|
||||
>
|
||||
> 状态码：`1 参数非法`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "1",
|
||||
"error_msg": "请上传jpg/png/jpeg文件",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 获取行业编码
|
||||
|
||||
通过此接口获取行业编码，按层级、编码获取。
|
||||
|
||||
> - **URL**：`/open-api/mcc/mccList`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| level | Integer | M | 行业层级，1：大类，2：子类，3：细类 |
|
||||
| fatherCode | String | O | 父级行业编码 |
|
||||
| mccCode | String | O | 行业编码 |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| data | List<Object> | M | data为list，故在此特别列出 |
|
||||
| mccCode | Integer | M | 行业编码 |
|
||||
| mccTxt | Integer | M | 行业名称 |
|
||||
| fatherCode | Integer | O | 父级行业编码 |
|
||||
| fatherTxt | Integer | O | 父级行业名称 |
|
||||
| subMcc | List<Object> | O | 子行业列表，结构同外部 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "8IXdaoFNBV6NbVDSngPlvItD4//0yYcxmkfdyCDnH5M=",
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"data": {
|
||||
"level": 1,
|
||||
"fatherCode": "",
|
||||
"mccCode": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": [
|
||||
{
|
||||
"mccCode": "A001",
|
||||
"mccTxt": "住宿、餐饮和休闲娱乐业",
|
||||
"fatherCode": "1",
|
||||
"fatherTxt": null,
|
||||
"subMcc": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：参数错误 。
|
||||
>
|
||||
> 状态码：`1 失败`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "400",
|
||||
"error_msg": "参数错误",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
#### 注意事项
|
||||
|
||||
### 获取地区编码
|
||||
|
||||
通过此接口获取地区编码，按层级、编码获取。
|
||||
|
||||
> **不支持跨层级查询**，areaLevel=2 | 3 时，必须传递其他入参（根据需要任选）。
|
||||
>
|
||||
|
||||
> - **URL**：`/open-api/base/areaCode`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| areaLevel | String | M | 地区层级，1：省，2：市，3：区 |
|
||||
| parentCode | String | O | 父级地区编码 |
|
||||
| areaCode | String | O | 地区编码 |
|
||||
| areaName | String | O | 地区名称 |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| data | List<Object> | M | data为list，故在此特别列出 |
|
||||
| areaLevel | String | M | 地区层级，1：省，2：市，3：区 |
|
||||
| parentCode | String | M | 父级地区编码 |
|
||||
| areaCode | String | M | 地区编码 |
|
||||
| areaName | String | M | 地区名称 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "WJV87eXjlFHe0rrrwtcdfaYHsOH1MxKRglSbqDpuAAg=",
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"data": {
|
||||
"areaLevel": 1,
|
||||
"parentCode": "",
|
||||
"areaCode": "",
|
||||
"areaName": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": [
|
||||
{
|
||||
"id": 105311,
|
||||
"areaLevel": "1",
|
||||
"parentCode": "0",
|
||||
"areaCode": "130000",
|
||||
"areaName": "河北省"
|
||||
},
|
||||
{
|
||||
"id": 6657,
|
||||
"areaLevel": "1",
|
||||
"parentCode": "0",
|
||||
"areaCode": "140000",
|
||||
"areaName": "山西省"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：参数错误 。
|
||||
>
|
||||
> 状态码：`1 失败`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "400",
|
||||
"error_msg": "参数错误",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
#### 注意事项
|
||||
|
||||
### 获取银行列表
|
||||
|
||||
通过此接口获取银行列表。
|
||||
|
||||
> - **URL**：`/open-api/base/bankList`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| bankName | String | O | 银行名称 |
|
||||
| bankCode | String | O | 银行编码 |
|
||||
| pageNo | Integer | M | 页数 |
|
||||
| pageSize | Integer | M | 每页数量 |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| data | List<Object> | M | data为list，故在此特别列出 |
|
||||
| name | String | M | 银行名称 |
|
||||
| code | String | M | 银行编码 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "xqwUm+EQCBflHSZJhsRRmxLSb8VNivqXAJhRFOMGo84=",
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"data": {
|
||||
"bankName": "",
|
||||
"bankCode": "",
|
||||
"pageNo": 1,
|
||||
"pageSize": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 4480,
|
||||
"data": [
|
||||
{
|
||||
"name": "中国工商银行",
|
||||
"code": "C1010211000012"
|
||||
},
|
||||
{
|
||||
"name": "测试银行123",
|
||||
"code": "test43511"
|
||||
},
|
||||
{
|
||||
"name": "测试银行789",
|
||||
"code": "test987"
|
||||
},
|
||||
{
|
||||
"name": "交通银行",
|
||||
"code": "C1030131001288"
|
||||
},
|
||||
{
|
||||
"name": "小琦",
|
||||
"code": "C1030131001290"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：参数错误 。
|
||||
>
|
||||
> 状态码：`1 失败`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "400",
|
||||
"error_msg": "参数错误",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
#### 注意事项
|
||||
|
||||
### 获取银行网点列表
|
||||
|
||||
通过此接口获取行业编码，按层级、编码获取。
|
||||
|
||||
> - **URL**：`/open-api/base/branchList`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| provinceCode | String | M | 省份编码 |
|
||||
| cityCode | String | M | 城市编码 |
|
||||
| bankCode | String | M | 银行编码 |
|
||||
| bankSiteName | String | O | 网点名称 |
|
||||
| pageNo | Integer | M | 页数 |
|
||||
| pageSize | Integer | M | 每页数量 |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| data | List<Object> | M | data为list，故在此特别列出 |
|
||||
| name | String | M | 网点名称(对应bankSite) |
|
||||
| code | String | M | 网点编码(对应unionpayCode) |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "Q/AhuHPQYEKjWrlBeS98KJQtNdxg6iA0j5ADmpuenGM=",
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"data": {
|
||||
"provinceCode": "130000",
|
||||
"cityCode": "130100",
|
||||
"bankCode": "C1010211000012",
|
||||
"bankSiteName": "",
|
||||
"pageNo": 1,
|
||||
"pageSize": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 73,
|
||||
"data": [
|
||||
{
|
||||
"name": "中国工商银行河北省分行营业部业务处理中心",
|
||||
"code": "102121000029"
|
||||
},
|
||||
{
|
||||
"name": "中国工商银行股份有限公司石家庄东风支行",
|
||||
"code": "102121000037"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：参数错误 。
|
||||
>
|
||||
> 状态码：`1 失败`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "400",
|
||||
"error_msg": "参数错误",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
###
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,737 @@
|
||||
# 交易结算数据查询、推送
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/btwmtfskppsxmvd5>
|
||||
|
||||
##
|
||||
|
||||
## 交易结算详情查询
|
||||
|
||||
通过此接口 查询订单交易结算信息 , 查询跨度不允许超过30天， 不支持跨年查询
|
||||
|
||||
> 💡 注意，结算数据根据订单的实际结算时间生成
|
||||
>
|
||||
> 💡 注意，目前限制查询50次/5s，批量同步数据建议从商户维度分页查询
|
||||
>
|
||||
|
||||
> - URL：/open-api/tradeDetail/listTradeDetail
|
||||
> - **Method**：POST
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| startTime | string | M | 交易开始时间(交易开始时间必传) |
|
||||
| endTime | string | M | 交易结束时间(交易结束时间必传) |
|
||||
| orderId | string | O | 乐刷交易单号、商户编号必传其一 |
|
||||
| merchantId | string | O | 乐刷交易单号、商户编号必传其一 |
|
||||
| pageNo | Integer | M | 当前页 |
|
||||
| pageSize | Integer | M | 每页大小 |
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| merchantId | string | M | 商户编号 |
|
||||
| merchantName | string | M | 商户名称 |
|
||||
| agentId | string | M | 直属代理编号 |
|
||||
| topAgentId | string | M | 一级代理编号 |
|
||||
| keeperId | string | M | 业务员编号 |
|
||||
| transactionId | string | M | 交易流水号 |
|
||||
| orderId | string | M | 订单编号 |
|
||||
| time | string | M | 交易时间 |
|
||||
| posSn | string | M | pos_sn |
|
||||
| pinpadUuid | string | M | 乐刷sn |
|
||||
| qrcodeNo | string | M | 码牌编号 |
|
||||
| amount | number | M | 交易金额(单位:分) |
|
||||
| cardType | Integer | M | 刷卡交易卡类型:0-借记卡,2-贷记卡,3-境外卡,4未知 |
|
||||
| state | Integer | M | 交易状态：-1 未知,0 交易初始,5 支付成功,11 支付失败,3 退款成功,31 退款中,32 退款失败,40 预授权成功,41 预授权失败,42 预授权撤销成功,43 预授权撤销失败,44 预授权完成成功,45 预授权完成失败,48 预授权完成撤销成功,49 预授权完成撤销失败,50 预授权完成中间状态,51 预授权中间状态,52 预授权撤销中间状态,53 预授权完成撤销状态,54 预授权完成退款订单 |
|
||||
| tradeType | Integer | M | 交易类型:1-支付, 2-退款 |
|
||||
| payType | Integer | M | 支付方式:1-刷卡,2-微信,3-支付宝,6-银联二维码 |
|
||||
| t0Flag | Integer | M | t0标识： 1、t0 ; 0 T1 |
|
||||
| attach | string | M | 备注信息 |
|
||||
| settleAmount | Integer | M | 结算金额(分) |
|
||||
| settleState | Integer | M | 状态： -1：打款失败； 0：打款中； 1：打款成功； 2：打款退票； 3：冻结出款；**0-打款中状态下 无结算数据**（即对应字段值为0，如feeRate字段） |
|
||||
| feeRate | Integer | M | 手续费费率(百万分之一) |
|
||||
| feeFixed | Integer | M | 商户固定手续费，单位：万分之一分 |
|
||||
| merchantFee | Integer | M | 手续费(分) |
|
||||
|
||||
> 💡 注意：settleState只能判断打款状态,可能会存在settleState=1,但是结算数据没有同步的极端情况
|
||||
>
|
||||
> 建议通过settleState = 1且settleAmount != 0为条件来查询结算数据,以排除没有成功同步结算数据的偶发场景
|
||||
>
|
||||
> 推荐查询结算数据时间：T1交易次日9-10点 、 T0交易半个小时左右
|
||||
>
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "K9JViuBrknLD+lev3nhOKZRb42v8La7achR9jUSs2A8=",
|
||||
"data": {
|
||||
"pageSize": 10,
|
||||
"pageNo": 1,
|
||||
"merchantId": "3131014839",
|
||||
"startTime": "2022-05-09 00:00:00",
|
||||
"endTime": "2022-05-09 23:59:59"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 61,
|
||||
"data": [
|
||||
{
|
||||
"merchantId": "3131014839",
|
||||
"merchantName": "孤独荒迪",
|
||||
"agentId": "1923721",
|
||||
"topAgentId": "1923721",
|
||||
"keeperId": "1923721001",
|
||||
"transactionId": "0000000283903146",
|
||||
"orderId": "0000000283903146",
|
||||
"time": "2022-05-26 16:02:09",
|
||||
"posSn": "",
|
||||
"pinpadUuid": "",
|
||||
"qrcodeNo": "",
|
||||
"amount": 1,
|
||||
"cardType": 0,
|
||||
"state": 5,
|
||||
"tradeType": 1,
|
||||
"payType": 2,
|
||||
"t0Flag": 0,
|
||||
"attach": "扫码收款备注",
|
||||
"settleAmount": 0,
|
||||
"feeRate": 0,
|
||||
"feeFixed": 0,
|
||||
"merchantFee": 0,
|
||||
"profitAmount": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 交易结算实时推送
|
||||
|
||||
区分交易结算实时推送
|
||||
|
||||
推送范围：已配置外放交易结算的一代代理商
|
||||
|
||||
一代旗下的商户订单状态为终态的数据
|
||||
|
||||
推送规则： 交易消息发送成功后不在发送， 结算消息有settleAmount、feeRate、merchantFee变更就会推送一次
|
||||
|
||||
> - URL：由接入方提供
|
||||
> - **Method**：POST
|
||||
>
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"detailInfo": {
|
||||
"agentId": "315605362",
|
||||
"amount": 512,
|
||||
"attach": "",
|
||||
"cardType": 0,
|
||||
"keeperId": "1923721001",
|
||||
"merchantId": "3131014839",
|
||||
"merchantName": "孤独荒迪",
|
||||
"orderId": "2302140741110600",
|
||||
"payType": 1,
|
||||
"pinpadUuid": "9990052674",
|
||||
"posSn": "7290932048",
|
||||
"qrcodeNo": "",
|
||||
"state": 5,
|
||||
"t0Flag": 1,
|
||||
"time": "2023-02-14 07:41:12",
|
||||
"topAgentId": "1923721",
|
||||
"tradeType": 1,
|
||||
"transactionId": "230214411156325137"
|
||||
},
|
||||
"type": 0
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"detailInfo": {
|
||||
"agentId": "375592313",
|
||||
"amount": 130100,
|
||||
"feeFixed": 0,
|
||||
"feeRate": 3500,
|
||||
"keeperId": "375592313001",
|
||||
"merchantFee": 455,
|
||||
"merchantId": "8558118786",
|
||||
"merchantName": "汕头高新区千玺美容店",
|
||||
"orderId": "1001168578623047",
|
||||
"settleAmount": 129645,
|
||||
"state": 5,
|
||||
"time": "2023-02-16 15:35:05",
|
||||
"topAgentId": "1923721",
|
||||
"transactionId": "1001168578623047"
|
||||
},
|
||||
"type": 1
|
||||
}
|
||||
```
|
||||
|
||||
#### 推送字段
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| type | Integer | M | 0：交易 1：结算 |
|
||||
| **detailInfo** | Object | M | |
|
||||
| merchantId | string | M | 商户编号 |
|
||||
| merchantName | string | M | 商户名称 |
|
||||
| agentId | string | M | 直属代理编号 |
|
||||
| topAgentId | string | M | 一级代理编号 |
|
||||
| keeperId | string | M | 业务员编号 |
|
||||
| transactionId | string | M | 交易流水号 |
|
||||
| orderId | string | M | 乐刷交易单号 |
|
||||
| amount | Long | M | 交易金额(单位:分) |
|
||||
| time | string | M | 交易时间 |
|
||||
| state | Integer | M | 交易状态：5 支付成功,11 支付失败,3 退款成功,31 退款中,32 退款失败,40 预授权成功,41 预授权失败,42 预授权撤销成功,43 预授权撤销失败,44 预授权完成成功,45 预授权完成失败,48 预授权完成撤销成功,54 预授权完成退款订单 |
|
||||
| posSn | string | C | type=0 pos_sn |
|
||||
| pinpadUuid | string | C | type=0 乐刷sn |
|
||||
| qrcodeNo | string | C | type=0 码牌编号 |
|
||||
| cardType | Integer | C | type=0 刷卡交易卡类型:0-借记卡,2-贷记卡,3-境外卡,4未知 |
|
||||
| tradeType | Integer | C | type=0 交易类型:1-支付, 2-退款 |
|
||||
| payType | Integer | C | type=0支付方式:1-刷卡,2-微信,3-支付宝,6-银联二维码 |
|
||||
| t0Flag | Integer | C | type=0 t0标识： 1、t0 ; 0 T1 |
|
||||
| attach | string | C | type=0 备注信息 |
|
||||
| settleAmount | Long | C | type=1 结算金额(分) |
|
||||
| feeRate | Long | C | type=1手续费费率(万分之一)type=1 |
|
||||
| feeFixed | Long | C | type=1商户固定手续费，单位：万分之一分 |
|
||||
| merchantFee | Long | C | type=1手续费(分) |
|
||||
|
||||
#### 接入方响应
|
||||
|
||||
> **状态码：**
|
||||
>
|
||||
> error_code = `0 推送处理成功`
|
||||
>
|
||||
> error_code != `0`处理失败触发推送异常补偿机制
|
||||
>
|
||||
|
||||
#### 推送异常补偿逻辑
|
||||
|
||||
每隔十分钟检测10分钟前的一个小时内的失败订单数据
|
||||
|
||||
> 例：
|
||||
>
|
||||
> 16：30 跑批 15：20 - 16：20
|
||||
>
|
||||
> 16：40 跑批 15：30 - 16：30
|
||||
>
|
||||
> 16：50 跑批 15：40 - 16：40
|
||||
>
|
||||
> 17：00 跑批 15：50 - 16：50
|
||||
>
|
||||
> 17：10 跑批 16：00 - 17：00
|
||||
>
|
||||
> ps： 失败数据最多重复推送三次
|
||||
>
|
||||
|
||||
## 商户打款单结果查询
|
||||
|
||||
代理商可通过此接口查询旗下商户的打款情况。
|
||||
|
||||
> - **URL**：`/open-api/settlement/settlementOrder`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| billId | String | M | 打款单号 |
|
||||
| type | String | M | 类型：“T0”、“T1” |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| topAgentId | String | M | 一代编号 |
|
||||
| billId | String | M | 打款单号 |
|
||||
| merchantId | String | M | 商户编号 |
|
||||
| agentId | String | M | 直属代理商编号 |
|
||||
| settleType | String | M | 结算类型：T0, T1 |
|
||||
| realSettleAmount | Long | M | 实付金额（单位：分） |
|
||||
| planSettleAmount | Long | M | 应付金额（单位：分） |
|
||||
| suspendSettleAmount | Long | M | 止付金额（单位：分） |
|
||||
| state | Integer | M | 状态： -1：打款失败； 0：打款中； 1：打款成功； 2：打款退票； 3：冻结出款； |
|
||||
| failReason | String | M | 失败原因 |
|
||||
| createTime | String | M | 打款单创建日期 |
|
||||
| bankretTime | String | M | 打款时间 |
|
||||
| recreateFlag | String | M | 0 系统出款打款单 1风控打款单 2手提单 |
|
||||
| remark | String | M | 备注 |
|
||||
| bankAccount | String | M | 银行账号 |
|
||||
| bankBranch | String | M | 银行名称 |
|
||||
| bankHolder | String | M | 开户人 |
|
||||
| unionPayCode | String | M | 联行号 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "5592097",
|
||||
"currentAgentId": "5592097",
|
||||
"sign": "AE+nH/3ufd8JfZufsYBFoUS5Cf2/9w21yw36q7Ir7OI=",
|
||||
"data": {
|
||||
"billId": "20230320001000005344",
|
||||
"type": "T0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": {
|
||||
"topAgentId": "5592097",
|
||||
"billId": "20230320001000005344",
|
||||
"merchantId": "5931017344",
|
||||
"agentId": "5592097",
|
||||
"settleType": "T0",
|
||||
"realSettleAmount": 0,
|
||||
"planSettleAmount": 0,
|
||||
"suspendSettleAmount": 0,
|
||||
"state": 1,
|
||||
"failReason": "",
|
||||
"createTime": "2023-03-20 15:40:21",
|
||||
"bankretTime": "1970-01-01 08:00:01",
|
||||
"recreateFlag": null,
|
||||
"remark": "",
|
||||
"bankAccount": "621************0559",
|
||||
"bankBranch": "中国银行股份有限公司北京万泉河支行",
|
||||
"bankHolder": "李*",
|
||||
"unionPayCode": "104100005188"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：请求数据非法，例如 打款单编号为空。
|
||||
>
|
||||
> 状态码：`1 参数非法`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "1",
|
||||
"error_msg": "打款单编号不能为空",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 查询商户指定日期打款情况
|
||||
|
||||
代理商查询商户T0，T1打款情况，此接口仅对一代代理商开放。
|
||||
|
||||
> - **URL**：`/open-api/settlement/merchantSettlementOrder`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| merchantId | String | M | 商户号 |
|
||||
| date | String | M | 打款单的创建日期格式：（例2019-10-12) |
|
||||
| type | String | M | 类型：“T0”、“T1” |
|
||||
| state | Integer | M | 打款状态: -1：打款失败; 0:打款中;1:打款成功; 2:打款退票;3:冻结出款; |
|
||||
| pageNo | Integer | M | 页码(页码超出总页数后返回第一页)，每页默认20条数据 |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| **data** | List<Object> | M | 数据 |
|
||||
| topAgentId | String | M | 一代编号 |
|
||||
| billId | String | M | 打款单号 |
|
||||
| merchantId | String | M | 商户编号 |
|
||||
| agentId | String | M | 直属代理商编号 |
|
||||
| settleType | String | M | 结算类型：T0, T1 |
|
||||
| realSettleAmount | Long | M | 实付金额（单位：分） |
|
||||
| planSettleAmount | Long | M | 应付金额（单位：分） |
|
||||
| suspendSettleAmount | Long | M | 止付金额（单位：分） |
|
||||
| state | Integer | M | 状态： -1：打款失败； 0：打款中； 1：打款成功； 2：打款退票； 3：冻结出款； |
|
||||
| failReason | String | M | 失败原因 |
|
||||
| createTime | String | M | 打款单创建日期 |
|
||||
| bankretTime | String | M | 打款时间 |
|
||||
| recreateFlag | String | M | 打款单是否是重新生成的；0：否 1：是 （T0无该字段） |
|
||||
| remark | String | M | 备注 |
|
||||
| bankAccount | String | M | 银行账号 |
|
||||
| bankBranch | String | M | 银行名称 |
|
||||
| bankHolder | String | M | 开户人 |
|
||||
| unionPayCode | String | M | 联行号 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "AE+nH/3ufd8JfZufsYBFoUS5Cf2/9w21yw36q7Ir7OI=",
|
||||
"data": {
|
||||
"merchantId": "5931017344",
|
||||
"type": "T0",
|
||||
"date": "2023-03-20",
|
||||
"state": 4,
|
||||
"pageNo": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 2,
|
||||
"data": [
|
||||
{
|
||||
"topAgentId": "5592097",
|
||||
"billId": "20230320001000009344",
|
||||
"merchantId": "5931017344",
|
||||
"agentId": "5592097",
|
||||
"settleType": "T0",
|
||||
"realSettleAmount": 1164,
|
||||
"planSettleAmount": 1164,
|
||||
"suspendSettleAmount": 0,
|
||||
"state": 0,
|
||||
"failReason": "",
|
||||
"createTime": "2023-03-20 17:50:14",
|
||||
"bankretTime": "1970-01-01 08:00:01",
|
||||
"recreateFlag": null,
|
||||
"remark": "",
|
||||
"bankAccount": "621************0559",
|
||||
"bankBranch": "中国银行股份有限公司北京万泉河支行",
|
||||
"bankHolder": "李*",
|
||||
"unionPayCode": "104100005188"
|
||||
},
|
||||
{
|
||||
"topAgentId": "5592097",
|
||||
"billId": "20230320001000008344",
|
||||
"merchantId": "5931017344",
|
||||
"agentId": "5592097",
|
||||
"settleType": "T0",
|
||||
"realSettleAmount": 0,
|
||||
"planSettleAmount": 0,
|
||||
"suspendSettleAmount": 0,
|
||||
"state": 1,
|
||||
"failReason": "",
|
||||
"createTime": "2023-03-20 17:44:10",
|
||||
"bankretTime": "1970-01-01 08:00:01",
|
||||
"recreateFlag": null,
|
||||
"remark": "",
|
||||
"bankAccount": "621************0559",
|
||||
"bankBranch": "中国银行股份有限公司北京万泉河支行",
|
||||
"bankHolder": "李*",
|
||||
"unionPayCode": "104100005188"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：请求数据非法，例如 商户编号为空。
|
||||
>
|
||||
> 状态码：`1 参数非法`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "1",
|
||||
"error_msg": "商户编号不能为空",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 查询旗下商户打款失败明细
|
||||
|
||||
代理商可通过此接口查询旗下商户打款失败明细。
|
||||
|
||||
> - **URL**：`/open-api/settlement/agentFailSettlementOrder`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| date | String | M | 打款单创建日期 |
|
||||
| type | String | M | 类型：“T0”、“T1” |
|
||||
| pageNo | Integer | M | 页码(页码超出总页数后返回第一页)，每页默认20条数据 |
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| **data** | List<Object> | M | 数据 |
|
||||
| topAgentId | String | M | 一代编号 |
|
||||
| billId | String | M | 打款单号 |
|
||||
| merchantId | String | M | 商户编号 |
|
||||
| agentId | String | M | 直属代理商编号 |
|
||||
| settleType | String | M | 结算类型：T0, T1 |
|
||||
| realSettleAmount | Long | M | 实付金额（单位：分） |
|
||||
| planSettleAmount | Long | M | 应付金额（单位：分） |
|
||||
| suspendSettleAmount | Long | M | 止付金额（单位：分） |
|
||||
| state | Integer | M | 状态： -1：打款失败； 0：打款中； 1：打款成功； 2：打款退票； 3：冻结出款； |
|
||||
| failReason | String | M | 失败原因 |
|
||||
| createTime | String | M | 打款单创建日期 |
|
||||
| bankretTime | String | M | 打款时间 |
|
||||
| recreateFlag | String | M | 打款单是否是重新生成的；0：否 1：是 （T0无该字段） |
|
||||
| remark | String | M | 备注 |
|
||||
| bankAccount | String | M | 银行账号 |
|
||||
| bankBranch | String | M | 银行名称 |
|
||||
| bankHolder | String | M | 开户人 |
|
||||
| unionPayCode | String | M | 联行号 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "AE+nH/3ufd8JfZufsYBFoUS5Cf2/9w21yw36q7Ir7OI=",
|
||||
"data": {
|
||||
"type": "T1",
|
||||
"date": "2023-03-21",
|
||||
"pageNo": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 1,
|
||||
"data": [
|
||||
{
|
||||
"topAgentId": "6250921",
|
||||
"billId": "20230321000000009499",
|
||||
"merchantId": "1931010499",
|
||||
"agentId": "795823931",
|
||||
"settleType": "T1",
|
||||
"realSettleAmount": 1,
|
||||
"planSettleAmount": 1,
|
||||
"suspendSettleAmount": 0,
|
||||
"state": -1,
|
||||
"failReason": "order not found",
|
||||
"createTime": "2023-03-21 08:19:09",
|
||||
"bankretTime": "2023-03-21 09:21:14",
|
||||
"recreateFlag": "1",
|
||||
"remark": "商户资金结算RepayBill|0",
|
||||
"bankAccount": "622************9035",
|
||||
"bankBranch": "交通银行股份有限公司深圳锦绣御园社区支行",
|
||||
"bankHolder": "陆**",
|
||||
"unionPayCode": "301584000547"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：请求数据非法，例如 类型为空。
|
||||
>
|
||||
> 状态码：`1 参数非法`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "1",
|
||||
"error_msg": "类型不能为空",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 商户打款回调
|
||||
|
||||
用于通知下游代理商，其所属商户T0、T1打款结果。
|
||||
|
||||
|
||||
|
||||
#### 流程图
|
||||
|
||||
#### 业务返回数据
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| type | Integer | M | 类型 2:打款 |
|
||||
| **detailInfo** | Object | M | 数据 |
|
||||
| topAgentId | String | M | 一代编号 |
|
||||
| billId | String | M | 打款单号 |
|
||||
| merchantId | String | M | 商户编号 |
|
||||
| agentId | String | M | 直属代理商编号 |
|
||||
| settleType | String | M | 结算类型：T0, T1 |
|
||||
| realSettleAmount | Long | M | 实付金额（单位：分） |
|
||||
| planSettleAmount | Long | M | 应付金额（单位：分） |
|
||||
| suspendSettleAmount | Long | M | 止付金额（单位：分） |
|
||||
| state | Integer | M | 状态： -1：打款失败； 0：打款中； 1：打款成功； 2：打款退票； 3：冻结出款； |
|
||||
| failReason | String | M | 失败原因 |
|
||||
| createTime | String | M | 打款单创建日期 |
|
||||
| bankretTime | String | M | 打款时间 |
|
||||
| recreateFlag | String | M | 打款单是否是重新生成的；0：否 1：是 （T0无该字段） |
|
||||
| remark | String | M | 备注 |
|
||||
| bankAccount | String | M | 银行账号 |
|
||||
| bankBranch | String | M | 银行名称 |
|
||||
| bankHolder | String | M | 开户人 |
|
||||
| unionPayCode | String | M | 联行号 |
|
||||
|
||||
#### 回调示例
|
||||
|
||||
```json
|
||||
|
||||
{
|
||||
"type": 2,
|
||||
"detailInfo": {
|
||||
"topAgentId": "6250921",
|
||||
"billId": "20230321000000009499",
|
||||
"merchantId": "1931010499",
|
||||
"agentId": "795823931",
|
||||
"settleType": "T1",
|
||||
"realSettleAmount": 1,
|
||||
"planSettleAmount": 1,
|
||||
"suspendSettleAmount": 0,
|
||||
"state": -1,
|
||||
"failReason": "order not found",
|
||||
"createTime": "2023-03-21 08:19:09",
|
||||
"bankretTime": "2023-03-21 09:21:14",
|
||||
"recreateFlag": "1",
|
||||
"remark": "商户资金结算RepayBill|0",
|
||||
"bankAccount": "622************9035",
|
||||
"bankBranch": "交通银行股份有限公司深圳锦绣御园社区支行",
|
||||
"bankHolder": "陆**",
|
||||
"unionPayCode": "301584000547"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 接入方响应
|
||||
|
||||
> **状态码：**
|
||||
>
|
||||
> error_code = `0 推送成功`
|
||||
>
|
||||
> error_code != `0`或其他情况视为推送失败
|
||||
>
|
||||
|
||||
#### 注意事项
|
||||
|
||||
> （1）每次通知服务商只通知一次，如果回调地址调用失败，不会再次发起回调。
|
||||
>
|
||||
|
||||
## 交易subOpenId查询
|
||||
|
||||
通过此接口查询扫码订单subOpenId信息
|
||||
|
||||
> 💡 注意，仅支持查询近三个月订单
|
||||
>
|
||||
|
||||
> - URL：/open-api/tradeDetail/querySubOpenId
|
||||
> - **Method**：POST
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| orderId | string | M | 交易单号 |
|
||||
| merchantId | string | M | 商户编号 |
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| sub_openid | string | M | subOpenId |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "0IuBJXzSr0XU6P63RAsw0GWbSwEpKeaTHtCn2IyVZ4w=",
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "315605362",
|
||||
"data": {
|
||||
"merchantId": "3131014839",
|
||||
"orderId": "0000002783904339"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": {
|
||||
"sub_openid": "o8uJ6uMWYd3VQpYtAq-thmO9jw-o"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,435 @@
|
||||
# 码牌管理
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/kiaqd2z4nqkciapg>
|
||||
|
||||
### 码牌分配列表
|
||||
|
||||
通过此接口查询码牌已分配和未分配列表。
|
||||
|
||||
> - URL：`/open-api/agentQrcode/listDistributeQrcode `
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
> 💡 注意，此接口当前代理商编号currentAgentId不能为空
|
||||
>
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| distributeState | Integer | O | 分配状态,0=未分配,1=已分配 |
|
||||
| qrcodeNum | String | O | 码牌编号 |
|
||||
| qrcodeType | Integer | O | 码牌类型 |
|
||||
| pageNo | Integer | M | 页码 |
|
||||
| pageSize | Integer | M | 页大小 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "K9JViuBrknLD+lev3nhOKZRb42v8La7achR9jUSs2A8=",
|
||||
"data": {
|
||||
"distributeState" : 1，
|
||||
"pageNo" : 1,
|
||||
"pageSize" : 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| qrcodeCount | Integer | M | 码牌数量 |
|
||||
| bindCount | Integer | M | 已绑定数量 |
|
||||
| noBindCount | Integer | M | 待绑定数量 |
|
||||
| currentAgentId | string | M | 当前代理商编号 |
|
||||
| currentAgentName | string | M | 当前代理商名称 |
|
||||
| **fixQrcodeList** | object [] | M | |
|
||||
| agentId | string | M | 所属代理商编号 |
|
||||
| agentLevel | integer | M | 代理商等级 9表示业务员 |
|
||||
| allSuperAgentId | string | M | 直属代理商所有上级编号 |
|
||||
| batchNo | string | M | 非批次号 |
|
||||
| bindState | integer | M | 码牌状态：0、未绑定 1、已绑定 2、已解绑 3、初始入库 4.取消入库 5.取消分配 6.已分配 7.已废弃 |
|
||||
| bindType | integer | M | 码牌绑定类型：1、手动(已有码)2、自动(商户动态申请) |
|
||||
| createTime | string | M | 创建时间即分配时间 |
|
||||
| distributeState | integer | M | 分配状态,0=未分配,1=已分配 |
|
||||
| factoryMark | string | M | 厂商标识 |
|
||||
| factoryNum | string | M | 厂商原始码 |
|
||||
| operator | string | M | 操作人 |
|
||||
| qrConfig | string | M | 配置信息 |
|
||||
| qrcodeName | string | M | 码牌名称 |
|
||||
| qrcodeNum | string | M | 码牌号码 |
|
||||
| qrcodeType | integer | M | 码牌类型 |
|
||||
| randomCode | string | M | 码牌随机码 |
|
||||
| realState | integer | M | 批次状态：0、禁用1、正常2、取消分配 |
|
||||
| state | integer | M | 码牌交易状态 0、禁用 1、正常 |
|
||||
| topAgentId | string | M | 一级代理商编号 |
|
||||
| updateTime | string | M | 更新时间 |
|
||||
| yinlianQrnum | string | M | 银联码牌号码 |
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 65,
|
||||
"data": {
|
||||
"qrcodeCount": 95,
|
||||
"bindCount": 52,
|
||||
"noBindCount": 43,
|
||||
"currentAgentId": "1923721",
|
||||
"currentAgentName": "戴宁",
|
||||
"fixQrcodeList": [
|
||||
{
|
||||
"qrcodeNum": "0149920000002",
|
||||
"yinlianQrnum": "",
|
||||
"qrcodeType": 4,
|
||||
"batchNo": "MP18002945",
|
||||
"agentId": "1923721",
|
||||
"agentLevel": 1,
|
||||
"allSuperAgentId": "1923721",
|
||||
"topAgentId": "1923721",
|
||||
"bindState": 1,
|
||||
"bindType": 1,
|
||||
"state": 1,
|
||||
"factoryMark": "SYD",
|
||||
"remarkFlag": 0,
|
||||
"createTime": "2022-12-06 15:48:35",
|
||||
"updateTime": "2023-01-05 11:26:05",
|
||||
"qrcodeName": null,
|
||||
"qrConfig": "",
|
||||
"randomCode": "",
|
||||
"distributeState": 1,
|
||||
"realState": 1,
|
||||
"operator": null,
|
||||
"closeByOperate": 0,
|
||||
"factoryNum": null,
|
||||
"isDeposit": 0,
|
||||
"qrCodeModelNo": "",
|
||||
"isActive": 0,
|
||||
"depositAmount": "0"
|
||||
}
|
||||
],
|
||||
"showBatchDeposit": "1"
|
||||
},
|
||||
"fail": false,
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 码牌分配
|
||||
|
||||
通过此接口进行码牌分配
|
||||
|
||||
> - URL：/open-api/agentQrcode/distributeByAgent
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
> 💡 注意，此接口当前代理商编号currentAgentId不能为空
|
||||
>
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| qrcodeNums | List[String] | M | 分配码牌编号不能为空, 码牌编号集合（一次性最多只能分配20个） |
|
||||
| distributeAgentId | string | M | 分拨后代理商编号 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "K9JViuBrknLD+lev3nhOKZRb42v8La7achR9jUSs2A8=",
|
||||
"data": {
|
||||
"qrcodeNums": ["0141675001302"],
|
||||
"distributeAgentId" : "680558958"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 返回参数说明
|
||||
|
||||
data中的数据，数据类型为object[]
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| qrcodeNum | string | M | 码牌编号 |
|
||||
| isSuccess | Boolean | M | 是否成功true：成功 false：失败 |
|
||||
| errorMsg | String | O | 失败信息 |
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": [
|
||||
{
|
||||
"qrcodeNum": "0141675001302",
|
||||
"isSuccess": true,
|
||||
"errorMsg": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 码牌取消分配
|
||||
|
||||
通过此接口进行码牌取消分配
|
||||
|
||||
> - URL：/open-api/agentQrcode/cancelDistributeQrcode
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
> 💡 注意，此接口当前代理商编号currentAgentId不能为空
|
||||
>
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| qrcodeNum | string | M | 码牌编号不能为空 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "K9JViuBrknLD+lev3nhOKZRb42v8La7achR9jUSs2A8=",
|
||||
"data": {
|
||||
"qrcodeNum": "0161575903296"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "码牌取消分配成功!",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 商户码牌管理
|
||||
|
||||
通过此接口查询商户已绑定的码牌列表
|
||||
|
||||
> - URL：/open-api/agentQrcode/listMerchantQrcode
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| agentId | String | O | 直属代理商 |
|
||||
| merchantId | String | O | 商户编号 |
|
||||
| qrcodeNum | String | O | 码牌编号 |
|
||||
| qrcodeType | Integer | O | 码牌类型 |
|
||||
| pageNo | Integer | M | 页码 |
|
||||
| pageSize | Integer | M | 页大小 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "K9JViuBrknLD+lev3nhOKZRb42v8La7achR9jUSs2A8=",
|
||||
"data": {
|
||||
"agentId": "680558958",
|
||||
"merchantId": "7831012294"，
|
||||
"pageNo" : 1,
|
||||
"pageSize" : 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| count | Interge | M | 当前代理商名称 |
|
||||
| **fixQrcodeList** | object [] | M | |
|
||||
| agentId | string | M | 所属代理商编号 |
|
||||
| agentLevel | Integer | M | 代理商等级 9表示业务员 |
|
||||
| allSuperAgentId | string | M | 直属代理商所有上级编号 |
|
||||
| batchNo | string | M | 非批次号 |
|
||||
| bindState | Integer | M | 码牌状态：0、未绑定 1、已绑定 2、已解绑 3、初始入库 4.取消入库 5.取消分配 6.已分配 7.已废弃 |
|
||||
| bindTime | string | M | 绑定时间 |
|
||||
| bindType | Integer | M | 码牌绑定类型：1、手动(已有码)2、自动(商户动态申请) |
|
||||
| createTime | string | M | 创建时间即分配时间 |
|
||||
| merchantId | String | M | 商户编号 |
|
||||
| merchantName | String | M | 商户简称 |
|
||||
| factoryMark | string | M | 厂商标识 |
|
||||
| factoryNum | string | M | 厂商原始码 |
|
||||
| operator | string | M | 操作人 |
|
||||
| qrConfig | string | M | 配置信息 |
|
||||
| qrcodeName | string | M | 码牌名称 |
|
||||
| qrCodeModelNo | string | M | 机具型号 |
|
||||
| qrcodeNum | string | M | 码牌号码 |
|
||||
| qrcodeType | Integer | M | 码牌类型 |
|
||||
| randomCode | string | M | 码牌随机码 |
|
||||
| realState | Integer | M | 批次状态：0、禁用1、正常2、取消分配 |
|
||||
| state | Integer | M | 码牌交易状态 0、禁用 1、正常 |
|
||||
| topAgentId | string | M | 一级代理商编号 |
|
||||
| updateTime | string | O | 更新时间 |
|
||||
| yinlianQrnum | string | M | 银联码牌号码 |
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 1,
|
||||
"data": [
|
||||
{
|
||||
"qrcodeNum": "0141675001311",
|
||||
"yinlianQrnum": "",
|
||||
"qrcodeType": 4,
|
||||
"batchNo": "MP18002928",
|
||||
"merchantId": "7831012294",
|
||||
"agentId": "680558958",
|
||||
"agentLevel": 2,
|
||||
"allSuperAgentId": "1923721_680558958",
|
||||
"topAgentId": "1923721",
|
||||
"bindState": 1,
|
||||
"bindType": 1,
|
||||
"state": 1,
|
||||
"factoryMark": "SYD",
|
||||
"remarkFlag": 0,
|
||||
"bindTime": "2023-02-03T09:57:21.000+00:00",
|
||||
"createTime": "2022-08-22 18:17:13",
|
||||
"updateTime": "2023-02-03 17:57:21",
|
||||
"qrcodeName": null,
|
||||
"qrConfig": "",
|
||||
"randomCode": "",
|
||||
"realState": 1,
|
||||
"operator": "1923721",
|
||||
"merchantName": "小微D0商户666",
|
||||
"closeByOperate": 0,
|
||||
"factoryNum": "",
|
||||
"isDeposit": 0,
|
||||
"qrCodeModelNo": "云音箱LP167",
|
||||
"isActive": 0,
|
||||
"depositAmount": "0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 码牌状态变更
|
||||
|
||||
通过此接口进行码牌状态变更如： -- 启用/禁用 码牌交易 -- 关闭/开通 码牌备注 -- 绑定/解绑 码牌
|
||||
|
||||
> - URL：/open-api/agentQrcode/changeQrcodeState
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| operationType | Integer | M | 0.交易开通/关闭 1.备注开通关闭 2.码牌绑定/解绑 |
|
||||
| qrcodeNum | string | M | 码牌编号 |
|
||||
| state | Integer | C | operationType = 0 时必填，码牌交易状态 0、禁用 1、正常 |
|
||||
| remarkFlag | Integer | C | operationType = 1 时必填 ， 必填备注标识 0、非必填1、必填 |
|
||||
| bindState | Integer | C | operationType = 2 时必填， 1：绑定 2：解绑 (只允许解绑码牌音箱) |
|
||||
| merchantId | string | C | operationType = 2时必填, 商户编号 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"agentId": "1923721",
|
||||
"currentAgentId": "1923721",
|
||||
"sign": "K9JViuBrknLD+lev3nhOKZRb42v8La7achR9jUSs2A8=",
|
||||
"data": {
|
||||
"qrcodeNum": "0161575903296",
|
||||
"operationType": 2,
|
||||
"bindState" : 1,
|
||||
"merchantId" : "2231017459"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### **常用枚举**
|
||||
|
||||
#### qrcodeType**码牌类型枚举**
|
||||
|
||||
| 编码 | 状态 |
|
||||
| --- | --- |
|
||||
| 3 | 聚合码 |
|
||||
| 4 | 码牌音响 |
|
||||
| 21 | 联合收单水晶码牌 |
|
||||
| 22 | 联合收单卡纸码牌 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,5 @@
|
||||
# 获取对账文件
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/dkfeqpprgxod2tro>
|
||||
|
||||
|
||||
@@ -0,0 +1,297 @@
|
||||
# 对账单相关说明
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/ad7rcd29thx7k29d>
|
||||
|
||||
# **1 FTP对账单**
|
||||
|
||||
## **1.1对账单文件格式说明**
|
||||
|
||||
**对账文件位置：**FTP（账号信息请联系对接运营提供） **文件生成时间：**交易次日9点后可下载
|
||||
|
||||
**默认仅生成代理商分润明细**。如需其他对账单，请联系对接运营申请配置（**配置后****隔一日后生效**，**不支持生成此前的****存量数据**）。
|
||||
|
||||
> 常见问题：不支持生成存量数据对账单，存量交易数据的手续费如何获取？调用**交易结算数据查询、推送**的**交易结算详情查询**主查接口。
|
||||
>
|
||||
|
||||
| **序号** | **文件内容** | **文件名命名格式** | **备注** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 交易明细 | 1619191_trade_new_2018-07-20.txt | 代理商编号_trade_new_日期.txt |
|
||||
| 2 | 代理商分润明细 | 78860_profit_2020-07-20.txt | 代理商编号_profit_日期.txt |
|
||||
| 3 | 商户打款明细（rt） | 12345687_rt_日期.txt | 代理商编号_rt_日期.txt |
|
||||
| 4 | 商户打款明细（rtp） | 1051356_rtp_日期.txt | 代理商编号_rtp_日期.txt |
|
||||
| 5 | 商户打款明细（rtz） | 12345687_rtz_日期.txt | 代理商编号_rtz_日期.txt |
|
||||
| 6 | 分账明细（订单分账） | 1157213_ledgerDetail_20210114.txt | 代理商编号_ledgerDetail_日期.txt |
|
||||
| 7 | 分账明细（余额分账） | 1157213_BalanceledgerDetail_20210114.txt | 代理商编号_BalanceledgerDetail_日期.txt |
|
||||
| 8 | 分时打款对账单 | (1619191_rtp_2019-10-27.txt) | |
|
||||
| 9 | 分时明细对账单 | 1619191_trade_timeAdjust_20191107.txt | 代理商编号_trade_timeAdjust_日期.txt |
|
||||
| 10 | 延时结算（扫码预授权）订单清分明细对账单 | 1619191_7021568_wechat_app_2025-10-28.txt | 代理商编号_7021568_wechat_app_日期.txt |
|
||||
| 11 | 代理商提现秒到分润对账单 | 5731989_withdraw_profit_20250806.txt | 代理商编号_withdraw_profit_日期.txt |
|
||||
| 12 | 补贴明细对账单 | 2653276_subsidy_2022-07-20.txt | 服务商编号_subsidy_YYYY-MM-DD.txt |
|
||||
|
||||
## **1.2参数说明**
|
||||
|
||||
### **1.2.1 交易明细对账单**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 记录类型 | BT/BV | 标题/记录值 |
|
||||
| 2 | 编号 | 0 | 序列号，无实际业务含义 |
|
||||
| 3 | 交易时间 | 2018-07-3116:07:27 | 乐刷记录的时间，T0 订单为结算时间，T1 订单为交易发起时间 |
|
||||
| 4 | 订单号 | 1807311607130567 | 乐刷记录该笔交易的唯一订单号 |
|
||||
| 5 | 商户号 | 5800108650 | 乐刷分配的唯一商户编号 |
|
||||
| 6 | 费率（万分之一） | 38 | 商户的交易成本费率 |
|
||||
| 7 | 交易金额（分） | 500 | 交易产生的实际金额 |
|
||||
| 8 | 手续费（分） | 2 | 交易产生的手续费 |
|
||||
| 9 | 结算金额（分） | 498 | 商户的应结算金额 |
|
||||
| 10 | 资金流向 | 进账 | 包括：进账,出账,冻结,解冻,退款 |
|
||||
| 11 | 交易类型 | 未获取 | 1、pos 刷卡交易：消费，消费充正，消费撤销，退货中，退货成功，退货失败；扫码业务：退货中，退货成功，退货失败 【预授权完成】 【预授权完成撤销】 （1）消费：商户资金+ （2）消费冲正：商户资金不变动 （3）消费撤销：商户资金— （4）退货成功：商户资金减 （5）退货失败：商户资金加（这里的退货失败，可以理解为退货扣款的冲正） (6) 冲账：商户资金不变动" |
|
||||
| 12 | 支付方式 | 支付宝支付 | 包括：刷卡支付，微信支付，支付宝支付、银联扫码支付 |
|
||||
| 13 | 卡类型 | 信用卡 | 此参数适用于刷卡支付，包括信用卡、借记卡、未知 |
|
||||
| 14 | 商户优惠类型 | 标准类 | 包括标准类，优惠类 |
|
||||
| 15 | 参考号 | 20180731210010 04520546902261 | 此参数适用于刷卡支付 |
|
||||
| 16 | 凭证号 | * | 此参数适用于刷卡支付，交易产生的凭证号 |
|
||||
| 17 | 终端号 | * | 此参数适用于刷卡支付，交易付款使用的付款终端编号 |
|
||||
| 18 | 第三方订单号 | 50020180731160717965 | 即代理商代商户发起交易时的订单号 |
|
||||
| 19 | 第三方退款号 | 50020180731160717965 | 即代理商代商户发起退款时的订单号 |
|
||||
| 20 | 支付时间 | 2018-07-3116:07:27 | 即交易完成时间，乐刷据此进行结算 |
|
||||
| 21 | 上游订单号（网、银联） | 91533024438317706700 | 网联、银联端订单号 |
|
||||
| 22 | 上游订单号（微信、支付宝） | 20180731210010 04520546902261 | 微信、支付宝端订单号 |
|
||||
| 23 | 付款银行 | ALIPAYACCOUNT | 此参数适用于扫码业务，如花呗、信用卡 |
|
||||
| 24 | 消费者标识 | otCz6vh-Mok4q6hirkf1T1ZePA2o | 微信、支付宝体系下的用户标识，即微信 OpenId、支付宝 userID |
|
||||
| 25 | 扫码支付交易类型 | JSAPI | 此参数适用于扫码业务，包括：NATIVE：扫码支付；MICROPAY：条码支付；JSAPI：公众号/服务窗支付；APP：app 支付；SmPgPay：小程序支付； |
|
||||
| 26 | 乐刷退款流水号 | 50020180731160717965 | 退款时记录的乐刷端创建的流水号 |
|
||||
| 27 | 优惠活动 | 蓝海 | 此参数为参加蓝海行动/绿洲计划交易标识，包括：蓝海：该笔交易属于蓝海行动;绿洲：该笔交易属于绿洲计划 |
|
||||
| 28 | 订单金额 | 600 | 交易发起的金额 |
|
||||
| 29 | 优惠金额 | 100 | 交易中优惠消费者的金额 |
|
||||
| 30 | 代金券类型 | DISCOUNT | 此参数为参加微信代金券类型标识，包括:DISCOUNT 免充值；N 预充值 |
|
||||
| 31 | 操作类型 | 0 | 0：进账 1：出账 |
|
||||
| 32 | 分账标识 | 1 | 1：需分账 2：预授权 |
|
||||
| 33 | 终端编号 | 123456789 | 终端编号 |
|
||||
| 34 | 门店编号 | 123456789 | 门店编号 |
|
||||
| 35 | 补贴金额(分) | 500 | 补贴金 |
|
||||
| 36 | 分账费率(万分hi之一) | / | （注：暂未取值，正在优化） |
|
||||
| 37 | 分账手续费（分） | 500 | 分账手续费 |
|
||||
|
||||
### **1.2.2 代理商分润明细对账单**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 订单 id | 1805211723306852 | 乐刷记录该笔交易的分润的唯一流水号 |
|
||||
| 2 | 商户 id | 1009001843 | 乐刷分配的唯一商户编号 |
|
||||
| 3 | 代理商 id | 83111708 | 乐刷分配的唯一代理商编号 |
|
||||
| 4 | 标准/优惠 | 标准 | 包括：标准、优惠、减免、特殊计费类 |
|
||||
| 5 | 商户费率（百分之一） | 0.43 | 此参数的数量级与交易对账单不一样，为百分之一； |
|
||||
| 6 | 成本费率（百分之一） | 0.23 | 此参数的数量级与交易对账单不一样，为百分之一； |
|
||||
| 7 | 金额（分） | 200 | 交易产生的实际金额 |
|
||||
| 8 | 商户手续费（分） | 0 | 交易产生的手续费，计算方式详询运营经理 |
|
||||
| 9 | 成本（分） | 0 | 代理商的成本，计算方式详询运营经理 |
|
||||
| 10 | 分润（分） | 0 | 商户手续费与代理商成本之间的差价 |
|
||||
| 11 | 交易时间 | 2018-05-21 17:23:49 | 同交易对账单的交易时间 |
|
||||
| 12 | 交易类型 | 0 | 0进账，1出账 |
|
||||
| 13 | 分润转补贴 | 0 | 百万分之一分 |
|
||||
|
||||
分润明细文件解析规则： trade_agent_header = ["订单id", "商户id", "代理商id", "标准/优惠", "商户费率(百万分之一)", "成本费率(百万分之一)", "金额(分)", "商户手续费(百万分之一分)", "成本(百万分之一分)", "分润(百万分之一分)", "交易时间","交易类型(0-进账，1-出账)","分润转补贴(百万分之一分)","结算标记(0-D0，1-D1)","交易类型","卡类型"] trade_agent_width = [20,10,8,8,20,20,10,15,15,15,12,8,15,8,8,8] **字段值宽度: **每个字段值的最大占位
|
||||
|
||||
注意：分润数据一般第二天跑批，即1号交易，2号生成分润数据
|
||||
|
||||
### **1.2.3 商户打款明细对账单（rt）**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 结算类型 | T0 | 包括：T0、T1 |
|
||||
| 2 | 打款单号 | 20180702000051843502 | 乐刷记录该笔打款的唯一流水号 |
|
||||
| 3 | 商户号 | 6511111102 | 乐刷分配的唯一商户编号 |
|
||||
| 4 | 结算日期 | 2018-07-01 | 1. T0：该笔打款对应的结算日期；2. T1：该笔打款对应的交易日期（被风控时，对应打款单的生成日期） |
|
||||
| 5 | 应付金额（分） | 47077 | 扣除手续费之后之后应结算给商户的金额； |
|
||||
| 6 | 银行账号 | （空值） | 商户结算账号 |
|
||||
| 7 | 银行开户名 | （空值） | 商户结算账户名（空值） |
|
||||
| 8 | 开户银行名称 | 招商银行 | 商户结算账号开户银行 |
|
||||
| 9 | 补贴金额(分) | 10 | 营销补贴金额 |
|
||||
| 10 | 打款单生成标记 | 0 | |
|
||||
| 11 | 止付金额(分) | 0 | 退款金额 |
|
||||
| 12 | 刷卡应付金额（分） | 0 | |
|
||||
| 13 | 扫码应付金额(分) | 705668 | 扫码支付金额 |
|
||||
| 14 | 分账应付金额(分) | 0 | |
|
||||
| 15 | 扫码手续费（分） | 0 | |
|
||||
| 16 | 刷卡手续费(分) | 2132 | |
|
||||
| 17 | 分账手续费(分) | 0 | |
|
||||
| 18 | 止付金额（分） | 0 | |
|
||||
| 19 | 提现费率（万分之一分） | 0 | |
|
||||
| 20 | 提现手续费（分） | 0 | |
|
||||
| 21 | 打款状态 | 付款成功 | 打款状态分别有：付款成功；初始化；打款中；付款失败；退票成功；其他 |
|
||||
| 22 | 失败原因 | 无效卡号或无此账号 | 付款失败的原因，付款成功时为空 |
|
||||
| 23 | 资金类型 | 7 | 详见[billFlag说明](https://www.yuque.com/leshua-jhzf/qrcode_pay/ooqu7z?inner=xwLfe) |
|
||||
| 24 | 实付金额(分) | 10 | 实际打款到账金额 |
|
||||
| 25 | D0交易单号 | | |
|
||||
| 26 | 手续费补贴总金额(分) | | |
|
||||
| 27 | 营销补贴总金额(分) | | |
|
||||
|
||||
### **1.2.4 商户打款明细对账单（rtp）**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 结算类型 | T0 | 包括：T0、T1 |
|
||||
| 2 | 打款单号 | 20180702000051843502 | 乐刷记录该笔打款的唯一流水号 |
|
||||
| 3 | 商户号 | 6511111102 | 乐刷分配的唯一商户编号 |
|
||||
| 4 | 结算日期 | 2018-07-01 | 1. T0：该笔打款对应的结算日期；2. T1：该笔打款对应的交易日期（被风控时，对应打款单的生成日期） |
|
||||
| 5 | 应付金额（分） | 47077 | 扣除手续费之后之后应结算给商户的金额； |
|
||||
| 6 | 银行账号 | （空值） | 商户结算账号 |
|
||||
| 7 | 银行开户名 | （空值） | 商户结算账户名（空值） |
|
||||
| 8 | 开户银行名称 | 招商银行 | 商户结算账号开户银行 |
|
||||
| 9 | 补贴金额(分) | 10 | 营销补贴金额 |
|
||||
| 10 | 打款单生成标记 | 0 | |
|
||||
| 11 | 止付金额(分) | 0 | 退款金额 |
|
||||
| 12 | 刷卡应付金额（分） | 0 | |
|
||||
| 13 | 扫码应付金额(分) | 705668 | 扫码支付金额 |
|
||||
| 14 | 分账应付金额(分) | 0 | |
|
||||
| 15 | 扫码手续费（分） | 0 | |
|
||||
| 16 | 刷卡手续费(分) | 2132 | |
|
||||
| 17 | 分账手续费(分) | 0 | |
|
||||
| 18 | 止付金额（分） | 0 | |
|
||||
| 19 | 提现费率（万分之一分） | 0 | |
|
||||
| 20 | 提现手续费（分） | 0 | |
|
||||
| 21 | 打款状态 | 付款成功 | 打款状态分别有：付款成功；初始化；打款中；付款失败；退票成功；其他 |
|
||||
| 22 | 失败原因 | 无效卡号或无此账号 | 付款失败的原因，付款成功时为空 |
|
||||
| 23 | 资金类型 | 7 | 详见[billFlag说明](https://www.yuque.com/leshua-jhzf/qrcode_pay/ooqu7z?inner=xwLfe) |
|
||||
| 24 | 实付金额(分) | 10 | 实际打款到账金额 |
|
||||
| 25 | D0交易单号 | | |
|
||||
| 26 | 手续费补贴总金额(分) | | |
|
||||
| 27 | 营销补贴总金额(分) | | |
|
||||
|
||||
###
|
||||
|
||||
### **1.2.5 商户打款明细对账单（rtz）**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 结算类型 | T0 | 包括：T0、T1 |
|
||||
| 2 | 打款单号 | 20180702000051843502 | 乐刷记录该笔打款的唯一流水号 |
|
||||
| 3 | 商户号 | 6511111102 | 乐刷分配的唯一商户编号 |
|
||||
| 4 | 结算日期 | 2018-07-01 | 1. T0：该笔打款对应的结算日期；2. T1：该笔打款对应的交易日期（被风控时，对应打款单的生成日期） |
|
||||
| 5 | 应付金额（分） | 47077 | 扣除手续费之后之后应结算给商户的金额； |
|
||||
| 6 | 银行账号 | （空值） | 商户结算账号 |
|
||||
| 7 | 银行开户名 | （空值） | 商户结算账户名（空值） |
|
||||
| 8 | 开户银行名称 | 招商银行 | 商户结算账号开户银行 |
|
||||
| 9 | 补贴金额(分) | 10 | 营销补贴金额 |
|
||||
| 10 | 打款单生成标记 | 0 | |
|
||||
| 11 | 止付金额(分) | 0 | 退款金额 |
|
||||
| 12 | 刷卡应付金额（分） | 0 | |
|
||||
| 13 | 扫码应付金额(分) | 705668 | 扫码支付金额 |
|
||||
| 14 | 分账应付金额(分) | 0 | |
|
||||
| 15 | 扫码手续费（分） | 0 | |
|
||||
| 16 | 刷卡手续费(分) | 2132 | |
|
||||
| 17 | 分账手续费(分) | 0 | |
|
||||
| 18 | 止付金额（分） | 0 | |
|
||||
| 19 | 提现费率（万分之一分） | 0 | |
|
||||
| 20 | 提现手续费（分） | 0 | |
|
||||
| 21 | 打款状态 | 付款成功 | 打款状态分别有：付款成功；初始化；打款中；付款失败；退票成功；其他 |
|
||||
| 22 | 失败原因 | 无效卡号或无此账号 | 付款失败的原因，付款成功时为空 |
|
||||
| 23 | 资金类型 | 7 | 详见[billFlag说明](https://www.yuque.com/leshua-jhzf/qrcode_pay/ooqu7z?inner=xwLfe) |
|
||||
| 24 | 实付金额(分) | 10 | 实际打款到账金额 |
|
||||
| 25 | D0交易单号 | | |
|
||||
| 26 | 手续费补贴总金额(分) | | |
|
||||
| 27 | 营销补贴总金额(分) | | |
|
||||
|
||||
###
|
||||
|
||||
**1.2.6 订单分账明细对账单**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 乐刷商户编号 | 5706109796 | 乐刷分配的唯一商户编号 |
|
||||
| 2 | 第三方订单号 | 000000100007500288 | 确认分账传输的分账订单号 |
|
||||
| 3 | 支付订单号 | 0000116679620106 | 发起交易的订单号 |
|
||||
| 4 | 分账订单总金额 | 120101 | 发起分账的订单总金额 |
|
||||
| 5 | 分账详情 | 5706109796#1\|6218114838#10000\|6218114838#10000\|6218114838#10000\|1511216542#100\|5416016682#48000\|5416016682#30000\|5416016682#12000 | 发起分账的详情 |
|
||||
| 6 | 交易手续费承担方编号 | 5416016682 | 承担交易手续费的商户号 |
|
||||
| 7 | 交易手续费 | 42 | 该笔交易产生的手续费 |
|
||||
| 8 | 发起时间 | 2020-04-15 03:04:13 | 发起分账的时间 |
|
||||
| 9 | 分账状态 | 已退货 | 分账的状态 |
|
||||
| 10 | 结算日期 | 20200416 | 分账结算日期 |
|
||||
| 11 | 非交易主体分账金额 | 120100 | 非交易主体分账金额 |
|
||||
| 12 | 商户退款订单号 | 20041503040000049180 | 发起分账退款的第三方分账订单号 |
|
||||
| 13 | 乐刷退款流水号 | 0000043779620015 | 乐刷退款订单号 |
|
||||
| 14 | 乐刷分账单号 | 0 | 0：进账 1：出账 |
|
||||
| 15 | 商户分账单号 | | |
|
||||
|
||||
### **1.2.7 余额分账明细对账单**
|
||||
|
||||
| 序号 | 字段 | 示例值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 乐刷商户编号 | 5706109796 | 乐刷分配的唯一商户编号，分账商户号 |
|
||||
| 2 | 第三方分账订单号 | 000000100007500288 | 确认分账传输的第三方分账订单号 |
|
||||
| 3 | 乐刷分账订单号 | 0000116679620106 | 确认分账乐刷侧生成的分账订单号 |
|
||||
| 4 | 分账订单总金额 | 120101 | 发起分账的总金额 |
|
||||
| 5 | 分账详情 | 5706109796#2#1\|6218114838#商户#10000 | 发起分账的详情，格式： 接收方ID#接收方类型#接收方接收金额 接收方类型枚举值有：2商户；3代理商；4服务商 |
|
||||
| 6 | 发起时间 | 2020-04-15 03:04:13 | 发起分账的时间 |
|
||||
| 7 | 完成时间 | 2020-04-15 03:04:18 | 受理成功的时间 |
|
||||
| 8 | 分账状态 | 撤销成功、分账成功 | 分账的状态 |
|
||||
| 9 | 备注 | 备注 | 备注内容 |
|
||||
|
||||
### **1.2.8 分时明细对账单**
|
||||
|
||||
| **序号** | **字段** | **示例值** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 编号 | 28405 | 序列号 |
|
||||
| 2 | 交易时间 | 2020-05-24 13:48:13 | 乐刷记录的时间，T0 订单为结算时间，T1 订单为交易发起时间 |
|
||||
| 3 | 支付订单号 | 9000144040820145 | 发起交易的订单号 |
|
||||
| 4 | 乐刷商户编号 | 0000000018 | 乐刷分配的唯一商户编号 |
|
||||
| 5 | 费率(万分之一) | 2.5 | 商户自身费率(对账单会以整数体现) |
|
||||
| 6 | 交易金额(分) | 2800 | 商户交易金额 |
|
||||
| 7 | 交易手续费(分) | 700 | 该笔交易产生的手续费 |
|
||||
| 8 | 结算金额(分) | 279300 | 扣除手续费应结算金额 |
|
||||
| 9 | 资金流向 | 进账 | 包括：进账,出账,冻结,解冻,退款 |
|
||||
| 10 | 交易类型 | 消费 | 1、pos 刷卡交易：消费，消费充正，消费撤销，退货中，退货成功，退货失败；、扫码业务：退货中，退货成功，退货失败 未获取:退款成功 【预授权完成】 【预授权完成撤销】 |
|
||||
| 11 | 支付方式 | 微信支付 | 包含:刷卡支付,支付宝支付,微信支付 |
|
||||
| 12 | 卡类型 | 信用卡 | 包含:借记卡,信用卡 |
|
||||
| 13 | 商户优惠类型 | 标准类 | 无 |
|
||||
| 14 | 参考号 | * | 此参数适用于刷卡支付 |
|
||||
| 15 | 凭证号 | HLX39059248892080058729 | 此参数适用于刷卡支付，交易产生的凭证号 |
|
||||
| 16 | 终端号 | None | |
|
||||
| 17 | 第三方订单号 | | 即代理商代商户发起交易时的订单号 |
|
||||
| 18 | 第三方退款号 | | 即代理商代商户发起退款时的订单号 |
|
||||
| 19 | 支付时间 | 2020-05-24 13:48:13 | 即交易完成时间，乐刷据此进行结算 |
|
||||
| 20 | 上游订单号(网、银联) | | 网联、银联端订单号 |
|
||||
| 21 | 上游订单号(微信、 支付宝) | | 微信、支付宝端订单号 |
|
||||
| 22 | 付款银行 | | 此参数适用于扫码业务，如花呗、信用卡 |
|
||||
| 23 | 消费者标识 | | 微信、支付宝体系下的用户标识，即微信 OpenId、支付宝 userID |
|
||||
| 24 | 扫码支付交易类型 | | 此参数适用于扫码业务，包括：NATIVE：扫码支付；MICROPAY：条码支付；JSAPI：公众号/服务窗支付；APP：app 支付；SmPgPay：小程序支付； |
|
||||
| 25 | 乐刷退款流水号 | | 退款时记录的乐刷端创建的流水号 |
|
||||
| 26 | 优惠活动 | 蓝海 | 此参数为参加蓝海行动/绿洲计划交易标识，包括：蓝海：该笔交易属于蓝海行动;绿洲：该笔交易属于绿洲计划 |
|
||||
| 27 | 订单金额 | 2800 | 交易发起的金额 |
|
||||
| 28 | 优惠金额 | 0 | 交易中优惠消费者的金额 |
|
||||
| 29 | 代金券类型 | * | 此参数为参加微信代金券类型标识，包括:DISCOUNT 免充值；N 预充值 |
|
||||
| 30 | 提现手续费 | 0 | |
|
||||
| 31 | 费率 | 5500 | 百万分之一 |
|
||||
|
||||
## **1.3分账版本**
|
||||
|
||||
| **序号** | **对账单类别** | **通用版本** |
|
||||
| --- | --- | --- |
|
||||
| 1 | 普通交易对账单 | 这个时间点有要求，一般早上8：30前要跑完，基础结算的交易明细，剔除掉了分时商户所产生的交易明细 |
|
||||
| 2 | 分润对账单 | 包含了正常分润的和退票的，刷卡和扫码的 |
|
||||
| 3 | 银行打款对账单 | 商户打款单的明细 |
|
||||
| | | **定制版本** |
|
||||
| 1 | 分时结算 | 结算对账文件是独有一份，直接查交易数据 |
|
||||
| 2 | 银联云闪付 | 云闪付开放平台交易对账单 |
|
||||
| 3 | 分账对账单 | 分账交易的对账单 |
|
||||
|
||||
## **1.4对账推送时间**
|
||||
|
||||
| **序号** | **时间** | **内容** |
|
||||
| --- | --- | --- |
|
||||
| 1 | 9：00 | 普通交易对账单 |
|
||||
| 2 | 7：02 | 云闪付对账单 |
|
||||
| 3 | 9：30 | 分时对账单 |
|
||||
| 4 | 7：50 | 分账对账单 |
|
||||
|
||||
## **1.5 对账单要点说明**
|
||||
|
||||
| **序号** | **要点说明** |
|
||||
| --- | --- |
|
||||
| 1 | 普通交易对账单是提供乐刷结算的交易明细（未通过乐刷结算的无法提供） |
|
||||
| 2 | 普通交易对账单不提供分时商户的交易信息。 |
|
||||
| 3 | 未配置提供对账单的代理商不提供普通交易对账单。 |
|
||||
| 4 | 普通交易对账是T+1提供，即当日的交易次日9.00左右提供 |
|
||||
| 5 | 普通交易、分润、打款对账单只会按照一级代理商提供 |
|
||||
| 6 | 反馈问题时请反馈具体哪个对账单，同时提供“取对账单的文件名称”，据此可以判断是哪种类型的对账单。 |
|
||||
@@ -0,0 +1,101 @@
|
||||
# http获取对账单下载链接API文档
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/gaen4xne6ld3h5t0>
|
||||
|
||||
# 签名方法
|
||||
|
||||
签名算法（sign）如下：
|
||||
|
||||
**sign= Base64(md5(lepos+渠道商固定key值+data字符串值).toLowerCase())**
|
||||
|
||||
例: 请求报文中，data={"merchantId":"0123456789"}
|
||||
|
||||
待签名串为: leposXXXXXXXXXXXXXXXXXX{"merchantId":"0123456789"}
|
||||
|
||||
MD5后转小写: 0bc0be2e34c2d9779482327da35358cd
|
||||
|
||||
base64: MGJjMGJlMmUzNGMyZDk3Nzk0ODIzMjdkYTM1MzU4Y2Q=
|
||||
|
||||
# 1 HTTPS 获取对账单下载链接
|
||||
|
||||
## 1.1 接口说明
|
||||
|
||||
获取对账单下载地址，**需联系乐刷对接运营申请加白**。
|
||||
|
||||
## 1.2请求方式
|
||||
|
||||
接口传输的所有参数使用UTF8 编码格式，包括签名以 https的POST方式进行调用
|
||||
|
||||
## 1.3请求地址
|
||||
|
||||
生产环境：[http://saas-mch.leshuazf.com/apiv2/ftp/getDownLoadUrl](http://t-saas-combine.lepass.cn/saas-open-api/codeorder/queryBrand)
|
||||
|
||||
## 1.4频率限制
|
||||
|
||||
20秒/200次 链接有效时间5分钟内下载次数不限，支持下载最近2个月对账单
|
||||
|
||||
## 1.5业务入参
|
||||
|
||||
公共参数请对照进件接口，以下只针对data字段做说明
|
||||
|
||||
| **变量名** | **类型** | **是否必填** | **说明** |
|
||||
| --- | --- | --- | --- |
|
||||
| fileName | string | 是 | 文件名称 不要包含特殊字符、中文等，否则一律视为非法 |
|
||||
|
||||
**对账单文件格式说明**
|
||||
|
||||
| **序号** | **文件内** | **文件名命名格式** | **备注** |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 交易明细 | 1619191_trade_new_2018-07-20.txt | 代理商编号_trade_new_日期.txt |
|
||||
| 2 | 代理商分润明细 | 78860_profit_2020-07-20.txt | 代理商编号_profit_日期.txt |
|
||||
| 3 | 商户打款明细 | 1619191_rt_2019-10-27.txt | 代理商编号_rt_日期.txt |
|
||||
| 4 | 商户打款明细（新） | 1619191_rtp_2019-10-27.txt | 代理商编号_rtp_日期.txt |
|
||||
| 5 | 分账明细 | 1157213_ledgerDetail_20210114.txt | 代理商编号_ledgerDetail_日期.txt |
|
||||
| 6 | 分时打款对账单 | (1619191_rtp_2019-10-27.txt) | |
|
||||
| 7 | 分时明细对账单 | 1619191_trade_timeAdjust_20191107.txt | 代理商编号_trade_timeAdjust_日期.txt |
|
||||
|
||||
## 1.6业务出参
|
||||
|
||||
data 数据说明
|
||||
|
||||
| **变量名** | **类型** | **说明** |
|
||||
| --- | --- | --- |
|
||||
| downLoadUrl | string | 文件下载地址。 注： 1文件下载地址后，请下载直接下载下来，如果使用浏览器打开，可能会出现乱码。 2文件下载地址有效期为5分钟（300秒）请及时下载，如果超过5分钟，请调接口重新获取文件下载地址 3下载之前，**请确保文件存在**，如果对账单没有生成或者文件根本不存在，也会导致下载失败（接口报错）或者打开失败（**url访问404**） |
|
||||
| ttl | integer(int64) | 文件下载地址有效时间（单位：秒），当前默认为300秒 |
|
||||
|
||||
## 1.7示例报文
|
||||
|
||||
**1）请求报文**
|
||||
|
||||
```plain
|
||||
url :http://saas-mch.leshuazf.com/apiv2/ftp/getDownLoadUrl
|
||||
form-data:
|
||||
"data" = {"fileName":"5963222_trade_new_2021-09-12.txt"},
|
||||
"sign" = "da2686a1c2b98cf7183517d903bac81c",
|
||||
"reqSerialNo" = "111111111",
|
||||
"version" = "1.0.0",
|
||||
"agentId" = "123546"
|
||||
```
|
||||
|
||||
**2）应答报文**
|
||||
|
||||
```plain
|
||||
{
|
||||
"data": {
|
||||
"downLoadUrl": "https://saas-jhzf-ftp.leshuazf.com/agent5963222
|
||||
/5963222_trade_new_2021-09-12.txt?k=k-8upT4obZQHB-0FH9yK2Q&e=1637316706",
|
||||
"ttl": 300
|
||||
},
|
||||
"reqSerialNo": "11111111",
|
||||
"respCode": "000000",
|
||||
"respMsg": "成功",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
## 1.8常见问题
|
||||
|
||||
| **返回编码** | **错误提示内容** | **可能原因** |
|
||||
| --- | --- | --- |
|
||||
| 000000 | 正常返回 | |
|
||||
| 其他 | 失败 | 原因在respMsg中说明 |
|
||||
@@ -0,0 +1,144 @@
|
||||
# 商户维度接入
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/omt6q9dehv2bk437>
|
||||
|
||||
# 接入指南（须知）
|
||||
|
||||
**！注意：【商户交易】文档内接口为独立内容，无需参考此接入指南，按照【商户交易】文档描述对接即可**
|
||||
|
||||
****
|
||||
|
||||
## **1.1 参数格式与调用方式**
|
||||
|
||||
（1）接口传输的所有参数使用 UTF-8 编码格式，包括签名。接口以 https的POST方式进行调用。 （2）Content-Type为application/json （3）域名： 测试环境：[https://t-uts.lepass.cn](http://t-uts.lepass.cn/) 生产环境：[https://uts.leshuazf.com](https://uts.leshuazf.com/)
|
||||
|
||||
## **1.2 报文结构**
|
||||
|
||||
**请求报文** 请求报文由乐刷商户编号、请求序列号、毫秒级时间戳、签名串、验签方式、报文主体6个参数组成。说明如下： **注意： **
|
||||
|
||||
**M：must，必须；** **C：condition，条件必填；** **O：option，可选；**
|
||||
|
||||
| **参数名称** | **类型** | **长度限制** | **是否必输** | **说明** | **是否参与验签** |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| merchantId | String | 10 | M | 乐刷商户编号 | 是 |
|
||||
| reqSerialNo | String | 100 | M | 请求序列号，推荐格式：时间+随机字符 | 是 |
|
||||
| timestamp | String | 无 | M | 毫秒级时间戳，例如：1689822708874 | 是 |
|
||||
| sign | String | 无 | M | 签名串 | 否 |
|
||||
| algorithm | boolean | 无 | O | 默认true-国密验签，false-MD5验签 | 否 |
|
||||
| data | Object | 无 | M | 业务数据 | 是 |
|
||||
|
||||
> 💡 注意，分页请求列表时，每页最多请求50条数据
|
||||
>
|
||||
> 💡 注意，接口有限制调用频率，查询类接口100次/5s，更新类接口20次/5s
|
||||
>
|
||||
|
||||
**返回报文** 返回报文由error_code、error_msg、count、业务数据报文主体4个参数组成。说明如下：
|
||||
|
||||
|
||||
|
||||
## **1.3 数据签名**
|
||||
|
||||
签名算法（sign）如下：
|
||||
|
||||
将参数以lhsd+&key=value+商户密钥的格式进行拼接得到待加密字符串signStr，其中key按照ascii码顺序排列，merchantKey为商户密钥，例如：
|
||||
|
||||
```plain
|
||||
商户编号为3131014839，商户密钥key为：C0179E8F7FAA41B89FFAC6D6168F8C9C
|
||||
则signStr = lhsd&data={}&merchantId=3131014839&reqSerialNo=202307010921000001×tamp=1689921328880C0179E8F7FAA41B89FFAC6D6168F8C9C
|
||||
```
|
||||
|
||||
> 💡 参数为null或者空不参与验签，例如data为null则不拼接"data="
|
||||
>
|
||||
> 💡 其中data若不为null，则需转为json字符串进行拼接，并且json内容需要按照ascii码排序，例如{"a":{"d":"D","e":"E"},"b":"B","c":"C"}，java语言可参考fastjson工具方法：JSON.toJSONString(data, SerializerFeature.MapSortField)
|
||||
>
|
||||
> 💡 加签时data中的字段可以不传，不能多传，并且类型需与文档说明完全一致，例如手机号虽为全数字，但为String类型
|
||||
>
|
||||
|
||||
****
|
||||
|
||||
**（1）国密验签：**
|
||||
|
||||
**sign = SignUtil**.**encryptBySM3WithSalt(****商户密钥****key值, signStr)**
|
||||
|
||||
**（2）MD5验签：**
|
||||
|
||||
**sign = SignUtil.MD5Encrypt(signStr)**
|
||||
|
||||
## 签名工具类
|
||||
|
||||
**验签工具类**SignUtil
|
||||
|
||||
```java
|
||||
package test;
|
||||
|
||||
import cn.hutool.core.codec.Base64;
|
||||
import cn.hutool.crypto.digest.MD5;
|
||||
|
||||
import com.alibaba.fastjson.JSONObject;
|
||||
import com.alibaba.fastjson.JSON;
|
||||
import com.alibaba.fastjson.serializer.SerializerFeature;
|
||||
import org.apache.commons.lang.StringUtils;
|
||||
import org.bouncycastle.crypto.digests.SM3Digest;
|
||||
import org.bouncycastle.crypto.macs.HMac;
|
||||
import org.bouncycastle.crypto.params.KeyParameter;
|
||||
|
||||
public class SignUtil {
|
||||
|
||||
public static void main(String[] args) {
|
||||
// 商户密钥key值
|
||||
String key = "C0179E8F7FAA41B89FFAC6D6168F8C9C";
|
||||
// 请求参数
|
||||
JSONObject param = new JSONObject();
|
||||
param.put("merchantId", "3131014839");
|
||||
param.put("reqSerialNo", "202307010921000001");
|
||||
param.put("timestamp", System.currentTimeMillis());
|
||||
param.put("data", new JSONObject());
|
||||
String signStr = buildSignStr(param, key);
|
||||
System.out.println(signStr);
|
||||
|
||||
String sm3Sign = SM3Encrypt(key, signStr);
|
||||
System.out.println("sm3Sign:" + sm3Sign);
|
||||
String md5Sign = MD5Encrypt(signStr);
|
||||
System.out.println("md5Sign:" + md5Sign);
|
||||
|
||||
param.put("sign", sm3Sign);
|
||||
System.out.println("param:" + param);
|
||||
}
|
||||
|
||||
// 拼接待加密字符串，简易版，仅供参考
|
||||
private static String buildSignStr(JSONObject dto, String key) {
|
||||
String dataStr = "";
|
||||
if (dto.getJSONObject("data") != null) {
|
||||
dataStr = JSON.toJSONString(dto.getJSONObject("data"), SerializerFeature.MapSortField);
|
||||
}
|
||||
return "lhsd" + (StringUtils.isEmpty(dataStr) ? "" : ("&data=" + dataStr)) +
|
||||
"&merchantId=" + dto.getString("merchantId") +
|
||||
"&reqSerialNo=" + dto.getString("reqSerialNo") +
|
||||
"×tamp=" + dto.getString("timestamp") + key;
|
||||
}
|
||||
|
||||
// MD5验签，md加密后转大写
|
||||
public static String MD5Encrypt(String signStr) {
|
||||
System.out.println("MD5Encrypt，待加密数据：" + signStr);
|
||||
return MD5.create().digestHex(signStr).toUpperCase();
|
||||
}
|
||||
|
||||
// 国密验签，推荐使用
|
||||
public static String SM3Encrypt(String key, String signStr) {
|
||||
System.out.println("SM3Encrypt，待加密数据：" + signStr);
|
||||
return Base64.encode(hmac(key.getBytes(), signStr.getBytes()));
|
||||
}
|
||||
|
||||
public static byte[] hmac(byte[] key, byte[] srcData) {
|
||||
KeyParameter keyParameter = new KeyParameter(key);
|
||||
SM3Digest digest = new SM3Digest();
|
||||
HMac mac = new HMac(digest);
|
||||
mac.init(keyParameter);
|
||||
mac.update(srcData, 0, srcData.length);
|
||||
byte[] result = new byte[mac.getMacSize()];
|
||||
mac.doFinal(result, 0);
|
||||
return result;
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,80 @@
|
||||
# 基础接口
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/xwcqqguw7zzc2uvv>
|
||||
|
||||
## 上传图片
|
||||
|
||||
通过此接口上传图片获取路径。
|
||||
|
||||
> - **URL**：`/open-api/merchantV2/common/uploadPic`
|
||||
> - **Method**：`POST`
|
||||
>
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `ext` | String | M | 扩展名，限制jpg/png/jpeg |
|
||||
| `picData` | String | M | base64编码的图片数据，2M以内 |
|
||||
|
||||
> 💡 注意，目前只支持jpg、jpeg、png格式的图片
|
||||
>
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "gLjW4s3EBSIvDxYa1mFauv2XrkSuSnblOLbigmIxPVE=",
|
||||
"merchantId": "3131014839",
|
||||
"reqSerialNo": "202307010921000006",
|
||||
"timestamp": "1689844373531",
|
||||
"data": {
|
||||
"ext": "jpg",
|
||||
"picData": "/9j/4QkDRXhpZgAATU0AKgBBBBg……"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `path` | String | 图片路径 |
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 0,
|
||||
"data": {
|
||||
"path": "picture/M00/07/5E/rBQhymPXhGCATiPIHNGomYn0Pz3215.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
> **条件**：请求数据非法，例如 图片格式错误。
|
||||
>
|
||||
> 状态码：`1 参数非法`
|
||||
>
|
||||
> 响应示例:
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "1",
|
||||
"error_msg": "请上传jpg/png/jpeg文件",
|
||||
"count": 0,
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,112 @@
|
||||
# 交易结算数据查询
|
||||
|
||||
> 来源：<https://www.yuque.com/hayley-boppa/ws2xbg/ekb9g8kxazdzfde3>
|
||||
|
||||
通过此接口 查询订单交易结算信息 , 查询跨度不允许超过30天， 不支持跨年查询
|
||||
|
||||
> 💡 注意，结算数据根据订单的实际结算时间生成
|
||||
>
|
||||
|
||||
> - URL：/open-api/merchantV2/tradeDetail/listTradeDetail
|
||||
> - **Method**：POST
|
||||
>
|
||||
|
||||
|
||||
|
||||
#### 业务请求参数
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| startTime | string | M | 交易开始时间(交易开始时间必传) |
|
||||
| endTime | string | M | 交易结束时间(交易结束时间必传) |
|
||||
| orderId | string | O | 乐刷订单号 |
|
||||
| pageNo | Integer | M | 当前页 |
|
||||
| pageSize | Integer | M | 每页大小 |
|
||||
|
||||
#### 返回值
|
||||
|
||||
| 参数 | 类型 | 是否必须 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| merchantId | String | M | 商户编号 |
|
||||
| merchantName | String | M | 商户名称 |
|
||||
| agentId | String | M | 直属代理编号 |
|
||||
| topAgentId | String | M | 一级代理编号 |
|
||||
| keeperId | String | M | 业务员编号 |
|
||||
| transactionId | String | M | 交易流水号 |
|
||||
| orderId | String | M | 订单编号 |
|
||||
| time | String | M | 交易时间 |
|
||||
| posSn | String | M | pos_sn |
|
||||
| pinpadUuid | String | M | 乐刷sn |
|
||||
| qrcodeNo | String | M | 码牌编号 |
|
||||
| amount | Integer | M | 交易金额(单位:分) |
|
||||
| cardType | Integer | M | 刷卡交易卡类型:0-借记卡,2-贷记卡,3-境外卡,4未知 |
|
||||
| state | Integer | M | 交易状态：-1 未知,0 交易初始,5 支付成功,11 支付失败,3 退款成功,31 退款中,32 退款失败,40 预授权成功,41 预授权失败,42 预授权撤销成功,43 预授权撤销失败,44 预授权完成成功,45 预授权完成失败,48 预授权完成撤销成功,49 预授权完成撤销失败,50 预授权完成中间状态,51 预授权中间状态,52 预授权撤销中间状态,53 预授权完成撤销状态,54 预授权完成退款订单 |
|
||||
| tradeType | Integer | M | 交易类型:1-支付, 2-退款 |
|
||||
| payType | Integer | M | 支付方式:1-刷卡,2-微信,3-支付宝,6-银联二维码 |
|
||||
| t0Flag | Integer | M | t0标识： 1、t0 ; 0 T1 |
|
||||
| attach | String | M | 备注信息 |
|
||||
| settleAmount | Integer | M | 结算金额(分) |
|
||||
| feeRate | Integer | M | 手续费费率(百万分之一) |
|
||||
| feeFixed | Integer | M | 商户固定手续费，单位：万分之一分 |
|
||||
| merchantFee | Integer | M | 手续费(分) |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"sign": "gLjW4s3EBSIvDxYa1mFauv2XrkSuSnblOLbigmIxPVE=",
|
||||
"merchantId": "3131014839",
|
||||
"reqSerialNo": "202307010921000007",
|
||||
"timestamp": "1689844373531",
|
||||
"data": {
|
||||
"pageNo": 1,
|
||||
"pageSize": 10,
|
||||
"startTime": "2023-05-09 00:00:00",
|
||||
"endTime": "2023-05-09 23:59:59"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 成功响应
|
||||
|
||||
> **条件**：请求参数合法，并且数据校验通过。
|
||||
>
|
||||
> **状态码：**`0 OK`
|
||||
>
|
||||
> **响应示例：**
|
||||
>
|
||||
|
||||
```json
|
||||
{
|
||||
"error_code": "0",
|
||||
"error_msg": "success",
|
||||
"count": 61,
|
||||
"data": [
|
||||
{
|
||||
"merchantId": "3131014839",
|
||||
"merchantName": "孤独荒迪",
|
||||
"agentId": "1923721",
|
||||
"topAgentId": "1923721",
|
||||
"keeperId": "1923721001",
|
||||
"transactionId": "0000000283903146",
|
||||
"orderId": "0000000283903146",
|
||||
"time": "2022-05-26 16:02:09",
|
||||
"posSn": "",
|
||||
"pinpadUuid": "",
|
||||
"qrcodeNo": "",
|
||||
"amount": 1,
|
||||
"cardType": 0,
|
||||
"state": 5,
|
||||
"tradeType": 1,
|
||||
"payType": 2,
|
||||
"t0Flag": 0,
|
||||
"attach": "扫码收款备注",
|
||||
"settleAmount": 0,
|
||||
"feeRate": 0,
|
||||
"feeFixed": 0,
|
||||
"merchantFee": 0,
|
||||
"profitAmount": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,25 @@
|
||||
# 联合收单接口文档
|
||||
|
||||
语雀链接：<https://www.yuque.com/hayley-boppa/ws2xbg>
|
||||
|
||||
## 目录
|
||||
|
||||
- SDK&Demo （私有/无法匿名读取）
|
||||
- Java-sdk文档 （私有/无法匿名读取）
|
||||
- 接入前必看-接入流程 （私有/无法匿名读取）
|
||||
- [代理商维度接入 <-这里可点](04-代理商维度接入-这里可点.md)
|
||||
- [基础接口](05-基础接口.md)
|
||||
- [商户进件](06-商户进件.md)
|
||||
- [商户交易](07-商户交易.md)
|
||||
- [交易结算数据查询、推送](08-交易结算数据查询-推送.md)
|
||||
- [码牌管理](09-码牌管理.md)
|
||||
- [代理商管理](10-代理商管理.md)
|
||||
- [获取对账文件](11-获取对账文件.md)
|
||||
- 对账单申请流程 （私有/无法匿名读取）
|
||||
- [对账单相关说明](13-对账单相关说明.md)
|
||||
- [http获取对账单下载链接API文档](14-http获取对账单下载链接API文档.md)
|
||||
- [商户维度接入](15-商户维度接入.md)
|
||||
- [基础接口](16-基础接口.md)
|
||||
- [商户交易](17-商户交易.md)
|
||||
- [交易结算数据查询](18-交易结算数据查询.md)
|
||||
- 内部对接人员指引（不公开） （私有/无法匿名读取）
|
||||
Reference in New Issue
Block a user