localizer
parent
99c86f5d2e
commit
e8c1580de7
|
|
@ -1,295 +0,0 @@
|
|||
# PaymentController 接口文档
|
||||
|
||||
## 概述
|
||||
PaymentController 是支付相关的控制器，提供订单支付、微信支付、退款等功能。
|
||||
|
||||
## 基础信息
|
||||
- **基础路径**: `/payment`
|
||||
- **控制器**: `PaymentController`
|
||||
- **包路径**: `com.njzscloud.supervisory.order.controller`
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 1. 发起支付
|
||||
**接口路径**: `POST /payment/pay`
|
||||
|
||||
**功能描述**: 发起订单支付，支持公司支付和微信支付两种方式
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"orderId": 123456,
|
||||
"paymentCategory": "company|wx",
|
||||
"settleTotalMoney": 100.00,
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"expenseItemName": "运费",
|
||||
"settleMoney": 50.00
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| orderId | Long | 是 | 订单ID |
|
||||
| paymentCategory | String | 是 | 支付方式：company(公司支付)、wx(微信支付) |
|
||||
| settleTotalMoney | BigDecimal | 是 | 结算总金额 |
|
||||
| items | Array | 是 | 支付清单项 |
|
||||
| items[].id | Long | 是 | 费用项ID |
|
||||
| items[].expenseItemName | String | 是 | 费用项名称 |
|
||||
| items[].settleMoney | BigDecimal | 是 | 结算金额 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"success": true,
|
||||
"msg": "成功",
|
||||
"data": {
|
||||
"prepayId": "wx123456789",
|
||||
"timeStamp": "1234567890",
|
||||
"nonceStr": "abc123",
|
||||
"package": "prepay_id=wx123456789",
|
||||
"signType": "RSA",
|
||||
"paySign": "signature"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误码**:
|
||||
- 参数不完整或支付总金额小于0
|
||||
- 支付清单项不合法
|
||||
- 支付方式不合法
|
||||
- 订单不存在
|
||||
- 公司账户余额不足
|
||||
|
||||
---
|
||||
|
||||
### 2. 微信支付回调
|
||||
**接口路径**: `POST /payment/wechat/callback`
|
||||
|
||||
**功能描述**: 微信支付结果回调接口
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"id": "event_id",
|
||||
"createTime": "2023-01-01T00:00:00+08:00",
|
||||
"eventType": "TRANSACTION.SUCCESS",
|
||||
"resource": {
|
||||
"originalType": "transaction",
|
||||
"ciphertext": "encrypted_data"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```
|
||||
SUCCESS
|
||||
```
|
||||
|
||||
**说明**: 此接口由微信支付平台调用，用于通知支付结果
|
||||
|
||||
---
|
||||
|
||||
### 3. 查询微信支付订单状态
|
||||
**接口路径**: `GET /payment/wechat/query/{outTradeNo}`
|
||||
|
||||
**功能描述**: 查询微信支付订单的支付状态
|
||||
|
||||
**路径参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| outTradeNo | String | 是 | 商户订单号 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"success": true,
|
||||
"msg": "成功",
|
||||
"data": {
|
||||
"tradeState": "SUCCESS",
|
||||
"tradeStateDesc": "支付成功",
|
||||
"transactionId": "wx123456789",
|
||||
"outTradeNo": "ORDER_123_1234567890"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 申请微信支付退款
|
||||
**接口路径**: `POST /payment/wechat/refund`
|
||||
|
||||
**功能描述**: 申请微信支付退款
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"outTradeNo": "ORDER_123_1234567890",
|
||||
"outRefundNo": "REFUND_123_1234567890",
|
||||
"total": 10000,
|
||||
"refund": 5000,
|
||||
"reason": "用户申请退款"
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| outTradeNo | String | 是 | 原商户订单号 |
|
||||
| outRefundNo | String | 是 | 商户退款单号 |
|
||||
| total | Integer | 是 | 原订单金额(分) |
|
||||
| refund | Integer | 是 | 退款金额(分) |
|
||||
| reason | String | 否 | 退款原因 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"success": true,
|
||||
"msg": "成功",
|
||||
"data": {
|
||||
"refundId": "wx_refund_123456789",
|
||||
"outRefundNo": "REFUND_123_1234567890",
|
||||
"status": "SUCCESS"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 绑定微信账号信息
|
||||
**接口路径**: `POST /payment/wechat/bind`
|
||||
|
||||
**功能描述**: 绑定用户微信账号信息，获取openId和unionId
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| userId | Long | 是 | 用户ID |
|
||||
| wxCode | String | 是 | 微信授权码 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"success": true,
|
||||
"msg": "微信账号绑定成功",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**错误处理**:
|
||||
- 用户不存在
|
||||
- 微信登录失败
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### PaymentParam (支付参数)
|
||||
```java
|
||||
public class PaymentParam {
|
||||
private Long orderId; // 订单ID
|
||||
private String paymentCategory; // 支付方式
|
||||
private BigDecimal settleTotalMoney; // 结算总金额
|
||||
private List<PaymentItemParam> items; // 支付清单
|
||||
}
|
||||
```
|
||||
|
||||
### PaymentItemParam (支付清单项)
|
||||
```java
|
||||
public class PaymentItemParam {
|
||||
private Long id; // 费用项ID
|
||||
private String expenseItemName; // 费用项名称
|
||||
private BigDecimal settleMoney; // 结算金额
|
||||
}
|
||||
```
|
||||
|
||||
### WechatPayCallbackDto (微信支付回调)
|
||||
```java
|
||||
public class WechatPayCallbackDto {
|
||||
private String id; // 事件ID
|
||||
private String createTime; // 创建时间
|
||||
private String eventType; // 事件类型
|
||||
private Resource resource; // 资源信息
|
||||
}
|
||||
```
|
||||
|
||||
### WechatPayRefundDto (微信退款参数)
|
||||
```java
|
||||
public class WechatPayRefundDto {
|
||||
private String outTradeNo; // 商户订单号
|
||||
private String outRefundNo; // 商户退款单号
|
||||
private Integer total; // 原订单金额(分)
|
||||
private Integer refund; // 退款金额(分)
|
||||
private String reason; // 退款原因
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 支付流程
|
||||
1. **参数校验**: 验证支付参数完整性
|
||||
2. **金额校验**: 验证支付金额与数据库一致
|
||||
3. **支付处理**:
|
||||
- 公司支付：直接扣减公司账户余额
|
||||
- 微信支付：创建微信支付订单
|
||||
4. **状态更新**: 更新订单支付状态
|
||||
|
||||
### 公司支付规则
|
||||
- 需要验证公司账户余额是否充足
|
||||
- 直接扣减公司账户余额
|
||||
- 记录资金变动明细
|
||||
- 支付成功后订单状态变更为已完成
|
||||
|
||||
### 微信支付规则
|
||||
- 创建微信支付订单
|
||||
- 订单状态变更为待支付
|
||||
- 等待微信支付回调确认支付结果
|
||||
- 支付成功后订单状态变更为已完成
|
||||
|
||||
### 退款规则
|
||||
- 只能对已支付的订单申请退款
|
||||
- 退款成功后订单状态变更为已退款
|
||||
- 支持部分退款
|
||||
|
||||
---
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 0 | 成功 |
|
||||
| 11111 | 系统异常 |
|
||||
| 40001 | 参数错误 |
|
||||
| 40002 | 业务异常 |
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **事务处理**: 支付接口使用`@Transactional`注解确保数据一致性
|
||||
2. **金额精度**: 所有金额计算使用`BigDecimal`类型
|
||||
3. **微信支付**: 金额需要转换为分（乘以100）
|
||||
4. **回调验证**: 微信支付回调需要验证签名
|
||||
5. **幂等性**: 支付接口需要保证幂等性，避免重复支付
|
||||
6. **日志记录**: 关键操作都有详细的日志记录
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
| 版本 | 日期 | 更新内容 |
|
||||
|------|------|----------|
|
||||
| 1.0.0 | 2024-01-01 | 初始版本，包含基础支付功能 |
|
||||
| 1.1.0 | 2024-01-15 | 新增微信账号绑定功能 |
|
||||
Loading…
Reference in New Issue