聚合支付对接文档v2.0

# 1.API接入认证

## 1.1接口说明

> `本文档为《聚合支付对接文档》的 v2 版，主要更新了验签规则。在原文档中的部分接口不满足需求时，请参阅此文档以进行对接。`
开放平台的所有服务 URL 的请求参数分为系统级参数和业务级参数两部分，系统级参数是所有服务 API 都拥有的参数，而业务级参数由具体服务 API 定义。

### 更新内容
2024年5月28日11:08:34
- 验签规则及签名描述更新
- 2.3订单查询接口业务级请求及响应参数更新

## 1.2接口地址

> 请联系客户经理获取接口地址

## 1.3调用方式

> HTTP POST
参数类型为：application/x-www-form-urlencoded;charset=UTF-8

## 1.4系统级参数

> 系统级参数是由开放平台定义的一组参数，每个服务都拥有这些参数，用以传送框架级的参数信息。如 method 就是一个系统级参数，使用该参数指定业务的名称。共有 6 个系统级参数：

| 名称        | 类型   | 是否必须 | 描述                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------ |
| appkey      | String | 是       | 应用键，用以确定客户端应用的身份，如 000001。应用键对应一个密钥secret。要基于平台开发应用，必须事先通过申请获取appkey/secret后，才能进行应用的开发。  终端号即为appkey |
| timestamp   | Long   | 是       | 发送请求的时间戳（秒）， 和互联网时间误差不能超过 5分钟。    |
| sign        | String | 是       | 接口调用的签名值  可验证请求参数的合法性                     |
| method      | String | 是       | 业务标识，每个业务有单独的标识                               |
| notify_url  | String | 否       | 交易成功异步通知url                                          |
| rpi_no      | String | 是       | 商户唯一编号                                                 |
| biz_content | String | 是       | 业务级请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 |

## 1.5签名sign

1. 对业务级`非空`的请求参数按 key 做升序排列。
2. 把参数名和参数值连接成字符串，得到拼接字符串：`<键1><值1><键2><值2><键3><值3>...` 示例：`k1v1k2v2k3v3k4v4`
3. 将 secret 秘钥拼接到参数字符串后面：`<请求参数字符串><秘钥>` 示例：`k1v1k2v2k3v3k4v4ABCDEFG`
4. 对该字符串进行 SHA1 运算，生成 16 进制 SHA1 字符串，该加密后字符串即为签名值。
5. 将签名值放入系统级参数 sign 中，和其他参数一起调用接口即可。

### 示例

假设有以下业务级参数：

- k1: v1
- k2: v2
- k3: 空值
- k4: v4

假设秘钥为 `ABCDEFG`。

处理步骤如下：

1. 排除空值参数并按 key 升序排列，得到：`k1: v1, k2: v2, k4: v4`
2. 拼接字符串：`k1v1k2v2k4v4`
3. 拼接秘钥：`k1v1k2v2k4v4ABCDEFG`
4. 对字符串进行 SHA1 运算，生成签名值。
5. 将生成的签名值放入系统级参数 `sign` 中。

## 1.6业务级参数

详见 API 接口的具体参数定义。

## 1.7附录

### 1.7.1交易状态

# 2.业务接口

## 2.1反扫码创建订单
暂未开放
## 2.2主扫创建订单
暂未开放

## 2.3查询订单

- 接口说明

- 需要查询订单及明细状态，调用此接口

- method

rsypay.online.trade.order.query.v2

### 2.3.1请求参数

- 公共请求参数

| 名称        | 类型   | 是否必须 | 描述                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------ |
| appkey      | String | 是       | 应用键，用以确定客户端应用的身份，如 000001。应用键对应一个密钥secret。要基于平台开发应用，必须事先通过申请获取appkey/secret后，才能进行应用的开发。  终端code即为appkey |
| timestamp   | Long   | 是       | 发送请求的时间戳（秒）， 和互联网时间误差不能超过 5分钟。    |
| sign        | String | 是       | 接口调用的签名值  可验证请求参数的合法性                     |
| method      | String | 是       | 业务标识，每个业务有单独的标识                               |
| notify_url  | String | 否       | 交易成功异步通知url                                          |
| rpi_no      | String | 是       | 商户唯一编号                                                 |
| biz_content | String | 是       | 业务级请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 |

- 业务请求参数

| 名称         | 类型   | 描述       |
| ------------ | ------ | ---------- |
| order_code   | String | 系统订单号 |
| out_trade_no | String | 客户订单号 |

### 2.3.2响应参数

- 公共响应参数

| 名称                             | 类型    | 父级 | 描述                          |
| -------------------------------- | ------- | ---- | ----------------------------- |
| code                             | Integer |      | 状态码：返回200请求成功       |
| success                          | boolean |      | 是否成功                      |
| data                             | String  |      | 承载数据                      |
| msg                              | String  |      | 消息                          |
| sign                             | String  | data | 签名（仅加密 必传的响应参数） |
| rsy_online_order_detail_response | String  | data | 响应业务参数集合              |

- 业务响应参数
| 名称           | 类型   | 描述                                                         |
| -------------- | ------ | ------------------------------------------------------------ |
| order_code     | String | 订单号                                                       |
| aisle_order_code     | String | 通道订单号                                                       |
| total_amount   | String | 交易金额                                                     |
| pay_way        | String | 支付方式(1微信、2支付宝、3银联)                              |
| pay_state      | String | 交易状态标识(0未支付1支付成功2支付失败3取消支付4退款中5已退款6退款失败) |
| pay_state_msg  | String | 交易状态信息                                                 |
| pay_trade_type | String | 交易类型(1支付单，2退款单)                                   |
| is_refund      | String | 是否有退款（0否1部分退款2全部退款）                          |
| refund_amount  | String | 退款金额                                                     |
| rpt_pay_time   | String | 发起支付时间                                                 |
| out_trade_no   | String | 客户订单号                                                   |
| shopdate       | String | 客户系统的交易发生日期格式yyyyMMdd                           |
| subject        | String | 订单备注                                                     |
| other_content  | String | 其他参数                                                     |
- 示例

```json
{
    "code": 200,
    "success": true,
    "data": {
        "sign": "65f04db3868eb5900e5e3a30d31396adbbf48be8",
        "rsy_online_order_detail_response": {
            "order_code": "2024051714534480101200000668",
            "pay_state_msg": "支付成功",
            "pay_state": "1",
            "pay_trade_type": "1",
            "out_trade_no": "202405171453440001xu",
            "total_amount": "0.01",
            "shopdate": "20240517",
            "aisle_order_code": "170548160306000062400000025817",
            "refund_amount": "0.01",
            "rpt_pay_time": "2024-05-17 14:53:45",
            "is_refund": "2",
            "pay_way": "2"
        }
    },
    "msg": "操作成功"
}
```

## 2.4取消订单
暂未开放

## 2.5订单退款
暂未开放

## 2.6退款查询
暂未开放

# 3.回调接口
暂未开放