# 越南支付对接Demo - Spring Boot版本

这是一个基于Spring Boot的越南支付对接Demo项目，提供了完整的支付接口示例和测试方法。

## 项目特点

- ✅ **一键启动** - 基于Spring Boot，内嵌Tomcat，无需额外配置
- ✅ **RESTful API** - 提供标准的REST接口，方便测试
- ✅ **完整示例** - 包含支付请求、异步通知等完整流程
- ✅ **详细文档** - 内置API文档页面，方便查看和测试

## 快速开始

### 1. 环境要求

- JDK 1.8+
- Maven 3.x+

### 2. 启动项目

```bash
# 进入项目目录
cd springboot-vnpay-demo

# 编译项目
mvn clean package

# 运行项目
mvn spring-boot:run

# 或者直接运行JAR包
java -jar target/springboot-vnpay-demo-1.0.0.jar
```

### 3. 访问项目

启动成功后，访问以下地址：

- **项目首页**: http://localhost:8080
- **测试接口**: http://localhost:8080/demo/test

## API接口说明

### 1. 测试接口

```
GET /demo/test
```

用于测试服务是否正常运行。

### 2. 支付接口

```
POST /demo/apiPay
Content-Type: application/x-www-form-urlencoded
```

**请求参数：**

| 参数名 | 必填 | 说明 | 示例值 |
|--------|------|------|--------|
| tradeType | 是 | 支付类型 | SCAN_PAY |
| version | 是 | 版本号 | 1.0 |
| channel | 是 | 支付渠道 | ALI_PAY |
| mchNo | 是 | 商户号 | M1234567890 |
| mchOrderNo | 是 | 商户订单号 | ORDER20240130001 |
| body | 是 | 商品描述 | 测试商品 |
| amount | 是 | 金额(分) | 10000 |
| currency | 是 | 货币类型 | VND |
| timePaid | 是 | 支付时间 | 20240130120000 |
| notifyUrl | 是 | 异步通知地址 | http://your-server.com/notify |
| paySecret | 是 | 支付密钥 | bf183091a6654c339b7b452a996c4ce5 |

### 3. 异步通知接口

```
POST /demo/notify/getPayInfo
Content-Type: application/json
```

**请求体示例：**

```json
{
    "mchNo": "M1234567890",
    "mchOrderNo": "ORDER20240130001",
    "amount": "10000",
    "status": "1",
    "sign": "XXXXXXXXXXXXXXXXXXXXX"
}
```

## Postman测试

### 导入Postman

1. 打开Postman
2. 创建新的请求
3. 设置请求方法为POST
4. URL: `http://localhost:8080/demo/apiPay`
5. Body选择`x-www-form-urlencoded`
6. 添加上述参数

### 测试示例

```bash
# 使用curl测试
curl -X POST http://localhost:8080/demo/apiPay \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "tradeType=SCAN_PAY&version=1.0&channel=ALI_PAY&mchNo=M1234567890&mchOrderNo=ORDER$(date +%Y%m%d%H%M%S)&body=测试商品&amount=10000&currency=VND&timePaid=$(date +%Y%m%d%H%M%S)&notifyUrl=http://localhost:8080/demo/notify/getPayInfo&paySecret=bf183091a6654c339b7b452a996c4ce5"
```

## 配置说明

配置文件位置：`src/main/resources/application.properties`

主要配置项：

```properties
# 服务端口
server.port=8080

# 商户支付KEY
payKey=64efebf7eb5b439d8fa213de9028392e

# 商户密钥
paySecret=bf183091a6654c339b7b452a996c4ce5

# API支付请求地址
apiPayUrl=http://localhost:8080/gateway/api/trade
```

## 项目结构

```
springboot-vnpay-demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/vnpay/demo/
│   │   │       ├── VnPayDemoApplication.java    # 启动类
│   │   │       ├── controller/                  # 控制器
│   │   │       │   ├── BaseController.java
│   │   │       │   └── DemoPayController.java
│   │   │       └── utils/                       # 工具类
│   │   │           ├── HttpUtil.java
│   │   │           ├── MD5Util.java
│   │   │           ├── MerchantApiUtil.java
│   │   │           ├── PayConfigUtil.java
│   │   │           └── StringUtil.java
│   │   └── resources/
│   │       ├── application.properties           # 配置文件
│   │       └── static/
│   │           └── index.html                   # API文档页面
├── pom.xml                                      # Maven配置
└── README.md                                    # 本文件
```

## 注意事项

1. **修改配置** - 请根据实际情况修改`application.properties`中的配置
2. **签名验证** - 所有请求都需要正确的签名，签名规则见API文档
3. **异步通知** - 确保`notifyUrl`可以被支付平台访问到
4. **安全提示** - 生产环境请妥善保管`paySecret`密钥

## 常见问题

### Q: 如何修改服务端口？
A: 修改`application.properties`中的`server.port`配置

### Q: 签名验证失败怎么办？
A: 检查参数排序和密钥是否正确，可以查看控制台日志中的签名前字符串

### Q: 如何查看详细日志？
A: 日志文件位于`logs/vnpay-demo.log`，或查看控制台输出

## 技术支持

如有问题，请参考项目中的API文档文件：
- `Api-V1.8.13 (19) (2).docx`
- `Api-V1.8.13EN.docx`

---

**版本**: 1.0.0  
**更新时间**: 2024-01-30