208 lines
4.3 KiB
Markdown
208 lines
4.3 KiB
Markdown
# 支付宝支付接口文档
|
||
|
||
## 接口概述
|
||
本文档描述支付宝支付相关的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
|
||
**维护人员**：开发团队
|
||
|