feat(pay): 集成PingPong支付功能并完善配置体系
- 添加MyBatis-Plus和Druid数据源依赖 - 配置多环境数据库连接（dev/test/prod） - 实现PingPong支付核心功能模块 - 添加支付订单和记录表结构设计 - 集成MD5/SHA256签名算法及验证机制 - 支持支付回调处理和状态更新 - 添加预授权支付类型支持（AUTH/CAPTURE/VOID） - 实现收银台页面集成和跳转逻辑 - 添加完整的API接口文档和使用说明 - 配置Druid监控和安全管理 - 实现多环境配置文件分离管理 - 添加详细的架构设计和开发文档
This commit is contained in:
275
mt-pay/ARCHITECTURE.md
Normal file
275
mt-pay/ARCHITECTURE.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# PingPong支付对接架构设计文档
|
||||
|
||||
## 一、整体架构分析
|
||||
|
||||
### 1.1 业务流程
|
||||
|
||||
```
|
||||
用户发起支付
|
||||
↓
|
||||
创建支付订单（PaymentOrderService）
|
||||
↓
|
||||
调用PingPong API（PingPongPayService）
|
||||
↓
|
||||
生成签名（SignatureService）
|
||||
↓
|
||||
返回token和收银台地址
|
||||
↓
|
||||
用户跳转到收银台完成支付
|
||||
↓
|
||||
PingPong回调通知（CallbackService）
|
||||
↓
|
||||
更新订单状态
|
||||
↓
|
||||
业务系统处理
|
||||
```
|
||||
|
||||
### 1.2 技术架构
|
||||
|
||||
```
|
||||
Controller层（API接口）
|
||||
↓
|
||||
Service层（业务逻辑）
|
||||
↓
|
||||
Repository层（数据访问）
|
||||
↓
|
||||
Entity层（数据模型）
|
||||
```
|
||||
|
||||
## 二、核心模块设计
|
||||
|
||||
### 2.1 数据库模型设计
|
||||
|
||||
#### PaymentOrder（支付订单表）
|
||||
**设计思路：**
|
||||
- 存储支付订单的完整信息
|
||||
- 支持订单状态跟踪
|
||||
- 通过merchantTransactionId保证唯一性
|
||||
|
||||
**关键字段：**
|
||||
- `merchantTransactionId`：商户订单号（唯一索引）
|
||||
- `transactionId`：PingPong交易流水号（回调时更新）
|
||||
- `status`：订单状态（PENDING/SUCCESS/FAILED/REVIEW/CANCELLED）
|
||||
- `token`：收银台token
|
||||
- `paymentUrl`：收银台地址
|
||||
|
||||
#### PaymentRecord（支付记录表）
|
||||
**设计思路：**
|
||||
- 记录所有支付相关操作
|
||||
- 用于对账和问题排查
|
||||
- 支持多种记录类型（CHECKOUT/CALLBACK/QUERY等）
|
||||
|
||||
**关键字段：**
|
||||
- `recordType`：记录类型
|
||||
- `requestData`：原始请求数据（JSON）
|
||||
- `responseData`：原始响应数据（JSON）
|
||||
|
||||
### 2.2 配置管理
|
||||
|
||||
#### PingPongProperties
|
||||
**设计思路：**
|
||||
- 使用Spring Boot的@ConfigurationProperties
|
||||
- 支持多环境配置（dev/prod）
|
||||
- 配置项包括：商户号、密钥、网关地址、环境模式等
|
||||
|
||||
**关键配置：**
|
||||
```properties
|
||||
pingpong.client-id=商户号
|
||||
pingpong.acc-id=店铺编号
|
||||
pingpong.secret=签名密钥
|
||||
pingpong.gateway=API网关地址
|
||||
pingpong.mode=环境模式（sandbox/test/build）
|
||||
```
|
||||
|
||||
### 2.3 签名服务（SignatureService）
|
||||
|
||||
#### 设计思路
|
||||
- 实现PingPong的签名算法
|
||||
- 支持MD5和SHA256
|
||||
- 自动筛选参与签名的参数
|
||||
- 提供签名生成和验证功能
|
||||
|
||||
#### 签名流程
|
||||
1. 筛选加签参数（根据SIGN_SCOPE）
|
||||
2. 按字典序排序
|
||||
3. 构建签名串：{secret}key1=val1&key2=val2...
|
||||
4. MD5/SHA256运算并转大写
|
||||
|
||||
#### 关键方法
|
||||
- `generateSign()`：生成签名
|
||||
- `verifySign()`：验证签名
|
||||
- `filterSignParams()`：筛选签名参数
|
||||
|
||||
### 2.4 支付服务（PingPongPayService）
|
||||
|
||||
#### 设计思路
|
||||
- 封装PingPong API调用
|
||||
- 自动处理签名生成
|
||||
- 验证响应签名
|
||||
- 使用RestClient进行HTTP请求
|
||||
|
||||
#### 关键方法
|
||||
- `checkout()`：创建支付订单
|
||||
- `buildRequestMap()`：构建请求参数
|
||||
|
||||
### 2.5 订单服务（PaymentOrderService）
|
||||
|
||||
#### 设计思路
|
||||
- 管理支付订单生命周期
|
||||
- 调用PingPong API
|
||||
- 保存订单和记录
|
||||
- 提供订单查询功能
|
||||
|
||||
#### 关键方法
|
||||
- `createPaymentOrder()`：创建支付订单
|
||||
- `findByMerchantTransactionId()`：查询订单
|
||||
- `updateOrderStatus()`：更新订单状态
|
||||
|
||||
### 2.6 回调服务（CallbackService）
|
||||
|
||||
#### 设计思路
|
||||
- 处理PingPong异步回调
|
||||
- 验证回调签名
|
||||
- 更新订单状态
|
||||
- 触发业务逻辑处理
|
||||
|
||||
#### 关键方法
|
||||
- `handleCallback()`：处理回调
|
||||
- `mapCallbackStatusToOrderStatus()`：状态映射
|
||||
- `handleBusinessLogic()`：业务逻辑处理
|
||||
|
||||
## 三、API接口设计
|
||||
|
||||
### 3.1 支付接口
|
||||
|
||||
#### POST /api/payment/checkout
|
||||
**功能：** 创建支付订单
|
||||
|
||||
**请求体：** CheckoutRequestDTO
|
||||
**响应：** 包含token和paymentUrl
|
||||
|
||||
#### GET /api/payment/order/{merchantTransactionId}
|
||||
**功能：** 查询订单状态
|
||||
|
||||
**响应：** 订单详细信息
|
||||
|
||||
#### GET /api/payment/checkout/page?token={token}
|
||||
**功能：** 获取收银台页面
|
||||
|
||||
**响应：** HTML页面（包含SDK初始化）
|
||||
|
||||
### 3.2 回调接口
|
||||
|
||||
#### POST /api/callback/pingpong
|
||||
**功能：** 接收PingPong回调通知
|
||||
|
||||
**请求体：** Map<String, Object>
|
||||
**响应：** 处理结果
|
||||
|
||||
#### GET /api/callback/result
|
||||
**功能：** 支付结果页面（用户重定向）
|
||||
|
||||
**参数：** merchantTransactionId, status, message
|
||||
|
||||
## 四、DTO设计
|
||||
|
||||
### 4.1 请求DTO
|
||||
|
||||
#### CheckoutRequestDTO
|
||||
- 包含所有checkout接口必需参数
|
||||
- 使用Jakarta Validation进行参数校验
|
||||
- 嵌套RiskInfoDTO
|
||||
|
||||
#### RiskInfoDTO
|
||||
- 包含风控相关信息
|
||||
- 嵌套多个子DTO（CustomerDTO、GoodsDTO等）
|
||||
|
||||
### 4.2 响应DTO
|
||||
|
||||
#### CheckoutResponseDTO
|
||||
- 对应PingPong API响应
|
||||
- 包含token、paymentUrl等
|
||||
|
||||
## 五、异常处理
|
||||
|
||||
### 5.1 GlobalExceptionHandler
|
||||
- 统一异常处理
|
||||
- 参数验证异常处理
|
||||
- 运行时异常处理
|
||||
- 返回统一错误格式
|
||||
|
||||
## 六、安全考虑
|
||||
|
||||
### 6.1 签名验证
|
||||
- 所有回调都进行签名验证
|
||||
- 防止数据篡改
|
||||
|
||||
### 6.2 订单号唯一性
|
||||
- 数据库唯一索引保证
|
||||
- 业务层检查重复
|
||||
|
||||
### 6.3 敏感信息
|
||||
- 密钥存储在配置文件中
|
||||
- 生产环境使用环境变量
|
||||
|
||||
## 七、扩展性设计
|
||||
|
||||
### 7.1 多支付平台支持
|
||||
- 可以扩展为支付平台抽象接口
|
||||
- 每个平台实现独立服务
|
||||
|
||||
### 7.2 预授权功能
|
||||
- 支持AUTH/CAPTURE/VOID
|
||||
- 通过paymentType区分
|
||||
|
||||
### 7.3 订单状态机
|
||||
- 可扩展为状态机模式
|
||||
- 支持更复杂的状态流转
|
||||
|
||||
## 八、最佳实践
|
||||
|
||||
### 8.1 日志记录
|
||||
- 关键操作记录日志
|
||||
- 包含订单号、状态等信息
|
||||
|
||||
### 8.2 事务管理
|
||||
- 订单创建和更新使用事务
|
||||
- 保证数据一致性
|
||||
|
||||
### 8.3 错误处理
|
||||
- 友好的错误提示
|
||||
- 详细的错误日志
|
||||
|
||||
### 8.4 配置管理
|
||||
- 多环境配置分离
|
||||
- 敏感信息加密
|
||||
|
||||
## 九、测试建议
|
||||
|
||||
### 9.1 单元测试
|
||||
- 签名服务测试
|
||||
- 服务层逻辑测试
|
||||
|
||||
### 9.2 集成测试
|
||||
- API接口测试
|
||||
- 回调处理测试
|
||||
|
||||
### 9.3 沙箱测试
|
||||
- 使用PingPong沙箱环境
|
||||
- 测试各种支付场景
|
||||
|
||||
## 十、部署注意事项
|
||||
|
||||
### 10.1 环境配置
|
||||
- 开发环境：使用sandbox模式
|
||||
- 生产环境：必须使用build模式
|
||||
|
||||
### 10.2 数据库
|
||||
- 生产环境使用连接池
|
||||
- 定期备份订单数据
|
||||
|
||||
### 10.3 监控
|
||||
- 监控API调用成功率
|
||||
- 监控回调处理情况
|
||||
- 监控订单状态分布
|
||||
|
||||
98
mt-pay/CONFIG_FILES.md
Normal file
98
mt-pay/CONFIG_FILES.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Config文件夹文件说明
|
||||
|
||||
## 文件清单
|
||||
|
||||
config文件夹中共包含5个配置文件，所有文件都是必需的：
|
||||
|
||||
### 1. DruidDataSourceConfig.java
|
||||
**作用**：配置Druid数据源
|
||||
- 配置主数据源（@Primary）
|
||||
- 支持从数据源配置（可选）
|
||||
- 从application.yml中读取数据源配置
|
||||
|
||||
**是否必需**：✅ 必需
|
||||
- 用于配置Druid连接池
|
||||
- 支持主从数据源切换
|
||||
|
||||
### 2. MyBatisPlusConfig.java
|
||||
**作用**：MyBatis-Plus配置
|
||||
- 配置Mapper扫描路径：`com.mtkj.mtpay.mapper`
|
||||
- 配置分页插件（MySQL）
|
||||
|
||||
**是否必需**：✅ 必需
|
||||
- MyBatis-Plus核心配置
|
||||
- 启用分页功能
|
||||
|
||||
### 3. MyMetaObjectHandler.java（原MetaObjectHandler.java）
|
||||
**作用**：MyBatis-Plus自动填充处理器
|
||||
- 自动填充创建时间（insert时）
|
||||
- 自动填充更新时间（insert和update时）
|
||||
|
||||
**是否必需**：✅ 必需
|
||||
- 自动处理实体类的createTime和updateTime字段
|
||||
- 替代JPA的@CreationTimestamp和@UpdateTimestamp
|
||||
- 注意：类名改为MyMetaObjectHandler避免与接口名冲突
|
||||
|
||||
### 4. PingPongProperties.java
|
||||
**作用**：PingPong支付配置属性类
|
||||
- 读取application.yml中的pingpong配置
|
||||
- 提供PingPong相关配置属性
|
||||
|
||||
**是否必需**：✅ 必需
|
||||
- 支付功能的核心配置
|
||||
- 包含商户号、密钥、网关地址等
|
||||
|
||||
### 5. RestClientConfig.java
|
||||
**作用**：RestClient配置
|
||||
- 配置HTTP客户端
|
||||
- 用于调用PingPong API
|
||||
|
||||
**是否必需**：✅ 必需
|
||||
- PingPong API调用需要
|
||||
- 配置JSON消息转换器
|
||||
|
||||
## 文件依赖关系
|
||||
|
||||
```
|
||||
DruidDataSourceConfig
|
||||
↓
|
||||
MyBatisPlusConfig (依赖数据源)
|
||||
↓
|
||||
MetaObjectHandler (MyBatis-Plus自动填充)
|
||||
↓
|
||||
PingPongProperties (支付配置)
|
||||
↓
|
||||
RestClientConfig (HTTP客户端)
|
||||
```
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 数据源配置流程
|
||||
|
||||
1. **DruidDataSourceConfig** 创建数据源Bean
|
||||
2. **MyBatisPlusConfig** 配置MyBatis-Plus，使用数据源
|
||||
3. **MyMetaObjectHandler** 处理自动填充逻辑
|
||||
|
||||
### 支付功能配置流程
|
||||
|
||||
1. **PingPongProperties** 读取配置属性
|
||||
2. **RestClientConfig** 配置HTTP客户端
|
||||
3. 支付服务使用这两个配置调用API
|
||||
|
||||
## 总结
|
||||
|
||||
**所有配置文件都是必需的，不能删除！**
|
||||
|
||||
- **DruidDataSourceConfig**：数据源配置（必需）
|
||||
- **MyBatisPlusConfig**：MyBatis-Plus配置（必需）
|
||||
- **MyMetaObjectHandler**：自动填充处理（必需）
|
||||
- **PingPongProperties**：支付配置（必需）
|
||||
- **RestClientConfig**：HTTP客户端（必需）
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **MyBatisPlusConfig** 中的 `@MapperScan` 必须指向正确的包路径
|
||||
2. **MyMetaObjectHandler** 必须实现 `MetaObjectHandler` 接口
|
||||
3. **DruidDataSourceConfig** 中的主数据源必须使用 `@Primary` 注解
|
||||
4. 所有配置类都需要使用 `@Configuration` 或 `@Component` 注解
|
||||
|
||||
190
mt-pay/ENV_CONFIG.md
Normal file
190
mt-pay/ENV_CONFIG.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 环境配置文件说明
|
||||
|
||||
## 配置文件结构
|
||||
|
||||
项目采用多环境配置，共包含4个配置文件：
|
||||
|
||||
1. **application.yml** - 主配置文件（通用配置）
|
||||
2. **application-dev.yml** - 开发环境配置
|
||||
3. **application-test.yml** - 测试环境配置
|
||||
4. **application-prod.yml** - 生产环境配置
|
||||
|
||||
## 配置文件说明
|
||||
|
||||
### application.yml（主配置）
|
||||
|
||||
包含所有环境的通用配置：
|
||||
- 应用名称
|
||||
- Druid监控配置
|
||||
- JPA配置
|
||||
- PingPong支付默认配置
|
||||
- 服务器配置
|
||||
|
||||
**注意**：主配置文件中不包含数据库连接信息，由各环境配置文件提供。
|
||||
|
||||
### application-dev.yml（开发环境）
|
||||
|
||||
**数据库配置**：
|
||||
- 使用阿里云RDS数据库（已配置具体连接信息）
|
||||
- 使用沙箱模式的PingPong支付
|
||||
|
||||
**使用方式**：
|
||||
```bash
|
||||
java -jar app.jar --spring.profiles.active=dev
|
||||
```
|
||||
|
||||
### application-test.yml（测试环境）
|
||||
|
||||
**数据库配置**：
|
||||
- 使用环境变量配置数据库连接
|
||||
- 环境变量：
|
||||
- `test.db.url` - 数据库连接URL
|
||||
- `test.db.username` - 数据库用户名
|
||||
- `test.db.password` - 数据库密码
|
||||
- 使用测试模式的PingPong支付
|
||||
|
||||
**使用方式**：
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export test.db.url=jdbc:mysql://host:3306/dbname?...
|
||||
export test.db.username=username
|
||||
export test.db.password=password
|
||||
|
||||
# 启动应用
|
||||
java -jar app.jar --spring.profiles.active=test
|
||||
```
|
||||
|
||||
### application-prod.yml（生产环境）
|
||||
|
||||
**数据库配置**：
|
||||
- 使用环境变量配置数据库连接
|
||||
- 环境变量：
|
||||
- `prod.db.url` - 数据库连接URL
|
||||
- `prod.db.username` - 数据库用户名
|
||||
- `prod.db.password` - 数据库密码
|
||||
- 使用生产模式的PingPong支付（build模式）
|
||||
|
||||
**使用方式**：
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export prod.db.url=jdbc:mysql://host:3306/dbname?...
|
||||
export prod.db.username=username
|
||||
export prod.db.password=password
|
||||
|
||||
# 启动应用
|
||||
java -jar app.jar --spring.profiles.active=prod
|
||||
```
|
||||
|
||||
## 环境变量配置示例
|
||||
|
||||
### 测试环境环境变量
|
||||
|
||||
```bash
|
||||
# Linux/Mac
|
||||
export test.db.url="jdbc:mysql://test-host:3306/test_db?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai"
|
||||
export test.db.username="test_user"
|
||||
export test.db.password="test_password"
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
$env:test.db.url="jdbc:mysql://test-host:3306/test_db?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai"
|
||||
$env:test.db.username="test_user"
|
||||
$env:test.db.password="test_password"
|
||||
```
|
||||
|
||||
### 生产环境环境变量
|
||||
|
||||
```bash
|
||||
# Linux/Mac
|
||||
export prod.db.url="jdbc:mysql://prod-host:3306/prod_db?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai"
|
||||
export prod.db.username="prod_user"
|
||||
export prod.db.password="prod_password"
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
$env:prod.db.url="jdbc:mysql://prod-host:3306/prod_db?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai"
|
||||
$env:prod.db.username="prod_user"
|
||||
$env:prod.db.password="prod_password"
|
||||
```
|
||||
|
||||
## Docker部署环境变量
|
||||
|
||||
在Docker Compose或Kubernetes中配置环境变量：
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
mt-pay:
|
||||
image: mt-pay:latest
|
||||
environment:
|
||||
- SPRING_PROFILES_ACTIVE=prod
|
||||
- prod.db.url=jdbc:mysql://prod-host:3306/prod_db?...
|
||||
- prod.db.username=prod_user
|
||||
- prod.db.password=prod_password
|
||||
```
|
||||
|
||||
```yaml
|
||||
# kubernetes deployment
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: mt-pay-config
|
||||
data:
|
||||
SPRING_PROFILES_ACTIVE: "prod"
|
||||
prod.db.url: "jdbc:mysql://prod-host:3306/prod_db?..."
|
||||
prod.db.username: "prod_user"
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: mt-pay-secret
|
||||
type: Opaque
|
||||
stringData:
|
||||
prod.db.password: "prod_password"
|
||||
```
|
||||
|
||||
## IDE中切换环境
|
||||
|
||||
### IntelliJ IDEA
|
||||
|
||||
1. 打开 `Run/Debug Configurations`
|
||||
2. 在 `Active profiles` 中输入：`dev`、`test` 或 `prod`
|
||||
3. 或者在 `Environment variables` 中设置环境变量
|
||||
|
||||
### Eclipse
|
||||
|
||||
1. 右键项目 -> `Run As` -> `Run Configurations`
|
||||
2. 在 `Arguments` 标签页的 `Program arguments` 中添加：
|
||||
```
|
||||
--spring.profiles.active=dev
|
||||
```
|
||||
|
||||
## 配置优先级
|
||||
|
||||
Spring Boot配置加载顺序（优先级从高到低）：
|
||||
1. 命令行参数
|
||||
2. 环境变量
|
||||
3. application-{profile}.yml
|
||||
4. application.yml
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **开发环境**：使用具体的数据库连接信息，方便本地开发
|
||||
2. **测试/生产环境**：使用环境变量，提高安全性
|
||||
3. **PingPong模式**：
|
||||
- dev: `sandbox`（沙箱）
|
||||
- test: `test`（测试）
|
||||
- prod: `build`（生产）
|
||||
4. **数据库密码**：生产环境务必使用强密码，并通过环境变量或密钥管理服务管理
|
||||
5. **监控页面**：生产环境建议修改Druid监控页面的用户名和密码
|
||||
|
||||
## 验证配置
|
||||
|
||||
启动应用后，可以通过以下方式验证配置是否正确：
|
||||
|
||||
1. 查看启动日志，确认加载的配置文件
|
||||
2. 访问 `/druid/index.html` 验证数据库连接
|
||||
3. 检查应用日志中的数据库连接信息（注意：密码不会显示）
|
||||
|
||||
218
mt-pay/README.md
Normal file
218
mt-pay/README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# MT Pay - PingPong支付对接
|
||||
|
||||
## 项目简介
|
||||
|
||||
本项目实现了PingPong支付平台的内嵌SDK接入，支持收银台模式支付。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ 支付订单创建（checkout接口）
|
||||
- ✅ MD5/SHA256签名生成和验证
|
||||
- ✅ 支付回调处理
|
||||
- ✅ 订单状态查询
|
||||
- ✅ 收银台页面集成
|
||||
- ✅ 支付记录管理
|
||||
- ✅ 预授权支持（AUTH/CAPTURE/VOID）
|
||||
|
||||
## 技术栈
|
||||
|
||||
- Spring Boot 4.0.0
|
||||
- Spring Data JPA
|
||||
- MySQL
|
||||
- Lombok
|
||||
- RestClient
|
||||
|
||||
## 数据库表结构
|
||||
|
||||
### payment_order（支付订单表）
|
||||
- 存储支付订单基本信息
|
||||
- 包含商户订单号、PingPong交易流水号、金额、状态等
|
||||
|
||||
### payment_record（支付记录表）
|
||||
- 存储支付操作记录
|
||||
- 包含回调记录、查询记录等
|
||||
|
||||
## 配置说明
|
||||
|
||||
在 `application.properties` 中配置以下参数：
|
||||
|
||||
```properties
|
||||
# PingPong支付配置
|
||||
pingpong.client-id=your-client-id # PingPong商户号
|
||||
pingpong.acc-id=your-acc-id # PingPong商户店铺编号
|
||||
pingpong.secret=your-secret-key # 签名密钥
|
||||
pingpong.sign-type=MD5 # 签名类型（MD5或SHA256）
|
||||
pingpong.gateway=https://sandbox-acquirer-payment.pingpongx.com # API网关地址
|
||||
pingpong.mode=sandbox # 环境模式（sandbox/test/build）
|
||||
```
|
||||
|
||||
## API接口
|
||||
|
||||
### 1. 创建支付订单
|
||||
|
||||
**接口地址：** `POST /api/payment/checkout`
|
||||
|
||||
**请求示例：**
|
||||
```json
|
||||
{
|
||||
"accId": "2018092714313010016291",
|
||||
"amount": "20.00",
|
||||
"currency": "USD",
|
||||
"merchantTransactionId": "MTN193495030728",
|
||||
"paymentType": "SALE",
|
||||
"shopperResultUrl": "http://your-domain.com/api/callback/result",
|
||||
"shopperCancelUrl": "http://your-domain.com/api/callback/result",
|
||||
"signType": "MD5",
|
||||
"riskInfo": {
|
||||
"customer": {
|
||||
"firstName": "James",
|
||||
"lastName": "LeBron",
|
||||
"email": "demo@pingpongx.com",
|
||||
"phone": "15988890852",
|
||||
"registerTime": "20191101122000",
|
||||
"registerIp": "222.126.52.23",
|
||||
"orderTime": "20191201122000",
|
||||
"orderIp": "222.126.52.23"
|
||||
},
|
||||
"goods": [{
|
||||
"name": "Macaron",
|
||||
"description": "Colorful macaron",
|
||||
"sku": "20191201331",
|
||||
"averageUnitPrice": "20",
|
||||
"number": "1",
|
||||
"virtualProduct": "N"
|
||||
}],
|
||||
"shipping": {
|
||||
"firstName": "James",
|
||||
"lastName": "LeBron",
|
||||
"phone": "13588185079",
|
||||
"street": "1986 Broad Street",
|
||||
"postcode": "35222",
|
||||
"city": "Birmingham",
|
||||
"state": "Alabama",
|
||||
"country": "US"
|
||||
},
|
||||
"billing": {
|
||||
"firstName": "James",
|
||||
"lastName": "LeBron",
|
||||
"phone": "13588185079",
|
||||
"street": "1986 Broad Street",
|
||||
"postcode": "35222",
|
||||
"city": "Birmingham",
|
||||
"state": "Alabama",
|
||||
"country": "US"
|
||||
}
|
||||
},
|
||||
"notificationUrl": "http://your-domain.com/api/callback/pingpong"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": "0000",
|
||||
"message": "订单创建成功",
|
||||
"data": {
|
||||
"merchantTransactionId": "MTN193495030728",
|
||||
"token": "vr_YVR8u7rn7C1gG97DOg5W0OxzazxNYIE56ShWjA4lJrY4wchTnb47oNmp-9ubP",
|
||||
"paymentUrl": "https://sandbox-pay-checkout.pingpongx.com/index.html?token=...",
|
||||
"status": "PENDING"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 查询订单状态
|
||||
|
||||
**接口地址：** `GET /api/payment/order/{merchantTransactionId}`
|
||||
|
||||
### 3. 获取收银台页面
|
||||
|
||||
**接口地址：** `GET /api/payment/checkout/page?token={token}`
|
||||
|
||||
### 4. 支付回调接口
|
||||
|
||||
**接口地址：** `POST /api/callback/pingpong`
|
||||
|
||||
### 5. 支付结果页面
|
||||
|
||||
**接口地址：** `GET /api/callback/result?merchantTransactionId={id}&status={status}`
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. **创建支付订单**
|
||||
- 调用 `/api/payment/checkout` 接口创建订单
|
||||
- 获取返回的 `token`
|
||||
|
||||
2. **跳转到收银台**
|
||||
- 方式1：直接使用返回的 `paymentUrl` 跳转
|
||||
- 方式2：调用 `/api/payment/checkout/page?token={token}` 获取收银台页面
|
||||
|
||||
3. **用户完成支付**
|
||||
- 用户在收银台页面完成支付
|
||||
- 支付完成后跳转到 `shopperResultUrl`
|
||||
|
||||
4. **接收回调通知**
|
||||
- PingPong会异步调用 `notificationUrl` 通知支付结果
|
||||
- 系统自动更新订单状态
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **订单号唯一性**：`merchantTransactionId` 必须全局唯一，不可重复
|
||||
2. **金额格式**：`amount` 必须精确到两位小数，如 "20.00"
|
||||
3. **环境模式**：开发测试使用 `sandbox`，生产环境必须使用 `build`
|
||||
4. **签名验证**：所有回调都会进行签名验证，确保数据安全
|
||||
5. **风控信息**：`riskInfo` 中的 `shipping`、`billing`、`goods` 不能为空，影响交易成功率
|
||||
6. **REVIEW状态**：如果订单状态为 `REVIEW`，需要及时进行内部审核
|
||||
|
||||
## 预授权功能
|
||||
|
||||
### AUTH（预授权）
|
||||
- 在创建订单时设置 `paymentType` 为 `AUTH`
|
||||
|
||||
### CAPTURE（预授权完成）
|
||||
- 调用二次交易接口，设置 `paymentType` 为 `CAPTURE`
|
||||
- 需要在预授权成功后的7天内完成
|
||||
|
||||
### VOID（预授权撤销）
|
||||
- 调用二次交易接口，设置 `paymentType` 为 `VOID`
|
||||
- 只能全额撤销
|
||||
|
||||
## 开发说明
|
||||
|
||||
### 项目结构
|
||||
```
|
||||
com.mtkj.mtpay/
|
||||
├── config/ # 配置类
|
||||
├── controller/ # 控制器
|
||||
├── dto/ # 数据传输对象
|
||||
├── entity/ # 实体类
|
||||
├── exception/ # 异常处理
|
||||
├── repository/ # 数据访问层
|
||||
└── service/ # 业务服务层
|
||||
```
|
||||
|
||||
### 核心服务
|
||||
|
||||
- **SignatureService**：签名生成和验证服务
|
||||
- **PingPongPayService**：PingPong API调用服务
|
||||
- **PaymentOrderService**：支付订单业务服务
|
||||
- **CallbackService**：回调处理服务
|
||||
|
||||
## 数据库初始化
|
||||
|
||||
项目启动后，JPA会自动创建表结构。也可以手动执行SQL：
|
||||
|
||||
```sql
|
||||
-- 根据实体类自动生成，或参考实体类定义手动创建
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
1. 配置沙箱环境参数
|
||||
2. 调用创建订单接口
|
||||
3. 使用沙箱测试卡号完成支付测试
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT
|
||||
|
||||
@@ -50,6 +50,22 @@
|
||||
<artifactId>mysql-connector-j</artifactId>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
<!-- MyBatis-Plus -->
|
||||
<dependency>
|
||||
<groupId>com.baomidou</groupId>
|
||||
<artifactId>mybatis-plus-boot-starter</artifactId>
|
||||
<version>3.5.7</version>
|
||||
</dependency>
|
||||
<!-- Druid数据源 -->
|
||||
<dependency>
|
||||
<groupId>com.alibaba</groupId>
|
||||
<artifactId>druid-spring-boot-3-starter</artifactId>
|
||||
<version>1.2.20</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-validation</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
|
||||
67
mt-pay/src/main/resources/application-dev.yml
Normal file
67
mt-pay/src/main/resources/application-dev.yml
Normal file
@@ -0,0 +1,67 @@
|
||||
spring:
|
||||
datasource:
|
||||
type: com.alibaba.druid.pool.DruidDataSource
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
druid:
|
||||
# 主库数据源（开发环境）
|
||||
master:
|
||||
url: jdbc:mysql://rm-j6c3u06k2afwn8hxw6o.mysql.rds.aliyuncs.com:3306/test?useUnicode=true&characterEncoding=utf-8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
|
||||
username: mtkj2025
|
||||
password: aXs-Q876#pxBesA
|
||||
# 初始连接数
|
||||
initial-size: 5
|
||||
# 最小连接池数量
|
||||
min-idle: 10
|
||||
# 最大连接池数量
|
||||
max-active: 200
|
||||
# 配置获取连接等待超时的时间
|
||||
max-wait: 60000
|
||||
# 配置连接超时时间
|
||||
connect-timeout: 30000
|
||||
# 配置网络超时时间
|
||||
socket-timeout: 60000
|
||||
# 配置间隔多久才进行一次检测，检测需要关闭的空闲连接，单位是毫秒
|
||||
time-between-eviction-runs-millis: 60000
|
||||
# 配置一个连接在池中最小生存的时间，单位是毫秒
|
||||
min-evictable-idle-time-millis: 300000
|
||||
# 配置一个连接在池中最大生存的时间，单位是毫秒
|
||||
max-evictable-idle-time-millis: 900000
|
||||
# 配置检测连接是否有效
|
||||
validation-query: SELECT 1 FROM DUAL
|
||||
test-while-idle: true
|
||||
test-on-borrow: false
|
||||
test-on-return: false
|
||||
# 从库数据源
|
||||
slave:
|
||||
# 从数据源开关/默认关闭
|
||||
enabled: false
|
||||
url:
|
||||
username:
|
||||
password:
|
||||
# Druid监控配置
|
||||
web-stat-filter:
|
||||
enabled: true
|
||||
stat-view-servlet:
|
||||
enabled: true
|
||||
# 设置白名单，不填则允许所有访问
|
||||
allow:
|
||||
url-pattern: /druid/*
|
||||
# 控制台管理用户名和密码
|
||||
login-username: ruoyi
|
||||
login-password: 123456
|
||||
filter:
|
||||
stat:
|
||||
enabled: true
|
||||
# 慢SQL记录
|
||||
log-slow-sql: false
|
||||
slow-sql-millis: 1000
|
||||
merge-sql: true
|
||||
wall:
|
||||
config:
|
||||
multi-statement-allow: true
|
||||
|
||||
# PingPong支付配置（开发环境使用沙箱）
|
||||
pingpong:
|
||||
gateway: https://sandbox-acquirer-payment.pingpongx.com
|
||||
mode: sandbox
|
||||
|
||||
67
mt-pay/src/main/resources/application-prod.yml
Normal file
67
mt-pay/src/main/resources/application-prod.yml
Normal file
@@ -0,0 +1,67 @@
|
||||
spring:
|
||||
datasource:
|
||||
type: com.alibaba.druid.pool.DruidDataSource
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
druid:
|
||||
# 主库数据源（生产环境）
|
||||
master:
|
||||
url: ${prod.db.url}
|
||||
username: ${prod.db.username}
|
||||
password: ${prod.db.password}
|
||||
# 初始连接数
|
||||
initial-size: 5
|
||||
# 最小连接池数量
|
||||
min-idle: 10
|
||||
# 最大连接池数量
|
||||
max-active: 200
|
||||
# 配置获取连接等待超时的时间
|
||||
max-wait: 60000
|
||||
# 配置连接超时时间
|
||||
connect-timeout: 30000
|
||||
# 配置网络超时时间
|
||||
socket-timeout: 60000
|
||||
# 配置间隔多久才进行一次检测，检测需要关闭的空闲连接，单位是毫秒
|
||||
time-between-eviction-runs-millis: 60000
|
||||
# 配置一个连接在池中最小生存的时间，单位是毫秒
|
||||
min-evictable-idle-time-millis: 300000
|
||||
# 配置一个连接在池中最大生存的时间，单位是毫秒
|
||||
max-evictable-idle-time-millis: 900000
|
||||
# 配置检测连接是否有效
|
||||
validation-query: SELECT 1 FROM DUAL
|
||||
test-while-idle: true
|
||||
test-on-borrow: false
|
||||
test-on-return: false
|
||||
# 从库数据源
|
||||
slave:
|
||||
# 从数据源开关/默认关闭
|
||||
enabled: false
|
||||
url:
|
||||
username:
|
||||
password:
|
||||
# Druid监控配置
|
||||
web-stat-filter:
|
||||
enabled: true
|
||||
stat-view-servlet:
|
||||
enabled: true
|
||||
# 设置白名单，不填则允许所有访问
|
||||
allow:
|
||||
url-pattern: /druid/*
|
||||
# 控制台管理用户名和密码
|
||||
login-username: ruoyi
|
||||
login-password: 123456
|
||||
filter:
|
||||
stat:
|
||||
enabled: true
|
||||
# 慢SQL记录
|
||||
log-slow-sql: false
|
||||
slow-sql-millis: 1000
|
||||
merge-sql: true
|
||||
wall:
|
||||
config:
|
||||
multi-statement-allow: true
|
||||
|
||||
# PingPong支付配置（生产环境）
|
||||
pingpong:
|
||||
gateway: https://acquirer-payment.pingpongx.com
|
||||
mode: build
|
||||
|
||||
67
mt-pay/src/main/resources/application-test.yml
Normal file
67
mt-pay/src/main/resources/application-test.yml
Normal file
@@ -0,0 +1,67 @@
|
||||
spring:
|
||||
datasource:
|
||||
type: com.alibaba.druid.pool.DruidDataSource
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
druid:
|
||||
# 主库数据源（测试环境）
|
||||
master:
|
||||
url: ${test.db.url}
|
||||
username: ${test.db.username}
|
||||
password: ${test.db.password}
|
||||
# 初始连接数
|
||||
initial-size: 5
|
||||
# 最小连接池数量
|
||||
min-idle: 10
|
||||
# 最大连接池数量
|
||||
max-active: 200
|
||||
# 配置获取连接等待超时的时间
|
||||
max-wait: 60000
|
||||
# 配置连接超时时间
|
||||
connect-timeout: 30000
|
||||
# 配置网络超时时间
|
||||
socket-timeout: 60000
|
||||
# 配置间隔多久才进行一次检测，检测需要关闭的空闲连接，单位是毫秒
|
||||
time-between-eviction-runs-millis: 60000
|
||||
# 配置一个连接在池中最小生存的时间，单位是毫秒
|
||||
min-evictable-idle-time-millis: 300000
|
||||
# 配置一个连接在池中最大生存的时间，单位是毫秒
|
||||
max-evictable-idle-time-millis: 900000
|
||||
# 配置检测连接是否有效
|
||||
validation-query: SELECT 1 FROM DUAL
|
||||
test-while-idle: true
|
||||
test-on-borrow: false
|
||||
test-on-return: false
|
||||
# 从库数据源
|
||||
slave:
|
||||
# 从数据源开关/默认关闭
|
||||
enabled: false
|
||||
url:
|
||||
username:
|
||||
password:
|
||||
# Druid监控配置
|
||||
web-stat-filter:
|
||||
enabled: true
|
||||
stat-view-servlet:
|
||||
enabled: true
|
||||
# 设置白名单，不填则允许所有访问
|
||||
allow:
|
||||
url-pattern: /druid/*
|
||||
# 控制台管理用户名和密码
|
||||
login-username: ruoyi
|
||||
login-password: 123456
|
||||
filter:
|
||||
stat:
|
||||
enabled: true
|
||||
# 慢SQL记录
|
||||
log-slow-sql: false
|
||||
slow-sql-millis: 1000
|
||||
merge-sql: true
|
||||
wall:
|
||||
config:
|
||||
multi-statement-allow: true
|
||||
|
||||
# PingPong支付配置（测试环境）
|
||||
pingpong:
|
||||
gateway: https://sandbox-acquirer-payment.pingpongx.com
|
||||
mode: test
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
spring.application.name=mt-pay
|
||||
77
mt-pay/src/main/resources/application.yml
Normal file
77
mt-pay/src/main/resources/application.yml
Normal file
@@ -0,0 +1,77 @@
|
||||
spring:
|
||||
application:
|
||||
name: mt-pay
|
||||
datasource:
|
||||
type: com.alibaba.druid.pool.DruidDataSource
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
druid:
|
||||
# 从库数据源
|
||||
slave:
|
||||
# 从数据源开关/默认关闭
|
||||
enabled: false
|
||||
url:
|
||||
username:
|
||||
password:
|
||||
# Druid监控配置
|
||||
web-stat-filter:
|
||||
enabled: true
|
||||
stat-view-servlet:
|
||||
enabled: true
|
||||
# 设置白名单，不填则允许所有访问
|
||||
allow:
|
||||
url-pattern: /druid/*
|
||||
# 控制台管理用户名和密码
|
||||
login-username: ruoyi
|
||||
login-password: 123456
|
||||
filter:
|
||||
stat:
|
||||
enabled: true
|
||||
# 慢SQL记录
|
||||
log-slow-sql: false
|
||||
slow-sql-millis: 1000
|
||||
merge-sql: true
|
||||
wall:
|
||||
config:
|
||||
multi-statement-allow: true
|
||||
# MyBatis-Plus配置
|
||||
mybatis-plus:
|
||||
# 配置扫描mapper.xml文件路径
|
||||
mapper-locations: classpath*:/mapper/**/*.xml
|
||||
# 配置实体类包路径
|
||||
type-aliases-package: com.mtkj.mtpay.entity
|
||||
# 配置MyBatis-Plus全局配置
|
||||
configuration:
|
||||
# 开启驼峰命名转换
|
||||
map-underscore-to-camel-case: true
|
||||
# 开启二级缓存
|
||||
cache-enabled: false
|
||||
# 日志实现
|
||||
log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
|
||||
# 全局配置
|
||||
global-config:
|
||||
db-config:
|
||||
# 主键类型：AUTO-数据库自增
|
||||
id-type: auto
|
||||
# 逻辑删除字段
|
||||
logic-delete-field: deleted
|
||||
# 逻辑删除值
|
||||
logic-delete-value: 1
|
||||
# 逻辑未删除值
|
||||
logic-not-delete-value: 0
|
||||
|
||||
# PingPong支付配置
|
||||
pingpong:
|
||||
client-id: your-client-id
|
||||
acc-id: your-acc-id
|
||||
secret: your-secret-key
|
||||
sign-type: MD5
|
||||
gateway: https://sandbox-acquirer-payment.pingpongx.com
|
||||
mode: sandbox
|
||||
enabled: true
|
||||
|
||||
# 服务器配置
|
||||
server:
|
||||
port: 8080
|
||||
servlet:
|
||||
context-path: /
|
||||
|
||||
Reference in New Issue
Block a user