# 支付宝支付接口文档

## 接口概述
本文档描述支付宝支付相关的API接口，包括创建支付订单和查询支付状态。

---

## 1. 创建支付宝支付订单

### 接口描述
创建支付宝支付订单，用于扫码预下单并返回二维码。

### 请求信息

#### 请求URL
```
GET /app/ali-payment/create/{orderNo}
```

#### 请求方式
`GET`

#### 请求参数

| 参数名 | 参数类型 | 是否必填 | 参数位置 | 参数说明 |
|--------|----------|----------|----------|----------|
| orderNo | String | 是 | Path | 订单号 |

#### 请求示例
```http
GET /app/ali-payment/create/ORD20231223001
```

### 响应信息

#### 响应参数

| 参数名 | 参数类型 | 参数说明 |
|--------|----------|----------|
| code | Integer | 响应状态码，200表示成功 |
| msg | String | 响应消息 |
| data | Object | 返回数据，包含支付宝支付相关信息 |

#### 响应示例

成功响应：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "qrCode": "https://qr.alipay.com/xxx",
    "outTradeNo": "ORD20231223001",
    "totalAmount": "99.00"
  }
}
```

失败响应：
```json
{
  "code": 500,
  "msg": "订单不存在或已支付"
}
```

### 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 创建成功 |
| 400 | 参数错误，订单号不能为空 |
| 500 | 系统错误或订单状态异常 |

---

## 2. 查询订单支付状态

### 接口描述
查询指定订单的支付状态。

### 请求信息

#### 请求URL
```
GET /app/ali-payment/status/{orderNo}
```

#### 请求方式
`GET`

#### 请求参数

| 参数名 | 参数类型 | 是否必填 | 参数位置 | 参数说明 |
|--------|----------|----------|----------|----------|
| orderNo | String | 是 | Path | 订单号 |

#### 请求示例
```http
GET /app/ali-payment/status/ORD20231223001
```

### 响应信息

#### 响应参数

| 参数名 | 参数类型 | 参数说明 |
|--------|----------|----------|
| code | Integer | 响应状态码，200表示成功 |
| msg | String | 响应消息 |
| data | Object | 订单支付状态信息 |
| data.tradeStatus | String | 交易状态（WAIT_BUYER_PAY-等待支付，TRADE_SUCCESS-支付成功，TRADE_CLOSED-交易关闭） |
| data.tradeNo | String | 支付宝交易号 |
| data.totalAmount | String | 订单金额 |
| data.buyerPayAmount | String | 买家实付金额 |

#### 响应示例

支付成功响应：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "tradeStatus": "TRADE_SUCCESS",
    "tradeNo": "2023122322001234567890",
    "outTradeNo": "ORD20231223001",
    "totalAmount": "99.00",
    "buyerPayAmount": "99.00",
    "buyerLogonId": "158****5620"
  }
}
```

等待支付响应：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "tradeStatus": "WAIT_BUYER_PAY",
    "outTradeNo": "ORD20231223001",
    "totalAmount": "99.00"
  }
}
```

失败响应：
```json
{
  "code": 500,
  "msg": "订单不存在"
}
```

### 支付状态说明

| 状态码 | 说明 |
|--------|------|
| WAIT_BUYER_PAY | 交易创建，等待买家付款 |
| TRADE_CLOSED | 未付款交易超时关闭，或支付完成后全额退款 |
| TRADE_SUCCESS | 交易支付成功 |
| TRADE_FINISHED | 交易结束，不可退款 |

---

## 公共说明

### 基础路径
```
http://your-domain.com/app/ali-payment
```

### 请求头
```
Content-Type: application/json
```

### 注意事项

1. **订单号格式**：订单号必须唯一，建议使用系统生成的订单编号
2. **幂等性**：同一订单号多次调用创建接口，返回相同的支付信息
3. **超时处理**：支付订单创建后，建议在15分钟内完成支付
4. **状态查询**：建议在支付完成后通过回调通知处理业务逻辑，状态查询接口用于补充查询
5. **安全性**：生产环境建议添加签名验证和请求频率限制

### 业务流程

```
1. 用户发起租借 → 系统创建订单
2. 调用创建支付接口 → 返回支付二维码
3. 用户扫码支付 → 支付宝处理支付
4. 支付宝回调通知 → 系统更新订单状态
5. 前端轮询状态接口 → 确认支付结果
6. 支付成功 → 触发开锁逻辑
```

---

## 联系方式

如有问题，请联系技术支持团队。

**文档版本**：v1.0  
**最后更新**：2025-12-23  
**维护人员**：开发团队