230 lines
6.2 KiB
Markdown
230 lines
6.2 KiB
Markdown
# IJPay 使用指南
|
||
|
||
## 一、IJPay 简介
|
||
|
||
IJPay 是一个简洁易用的 Java 聚合支付 SDK，支持微信支付、支付宝支付、银联支付等多种支付方式。
|
||
|
||
项目已集成 IJPay-AliPay 模块，用于支付宝支付功能。
|
||
|
||
## 二、项目中的 IJPay 使用方式
|
||
|
||
### 1. 依赖配置
|
||
|
||
在 `pom.xml` 中已添加 IJPay 依赖：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.github.javen205</groupId>
|
||
<artifactId>IJPay-AliPay</artifactId>
|
||
<version>2.9.12.1</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 2. 代码使用方式
|
||
|
||
项目中主要通过 `AlipayController.java` 使用 IJPay 的 `AliPayApi` 类进行支付操作。
|
||
|
||
#### 2.1 扫码支付（QR码支付）
|
||
|
||
```java
|
||
@PostMapping("/qr-pay")
|
||
public ResponseEntity<Map<String, Object>> qrPay(...) {
|
||
AlipayTradePrecreateModel model = new AlipayTradePrecreateModel();
|
||
model.setOutTradeNo(outTradeNo);
|
||
model.setTotalAmount(totalAmount);
|
||
model.setSubject(subject);
|
||
model.setBody(body);
|
||
|
||
// 使用 IJPay 的 AliPayApi 调用预创建接口
|
||
String qrCode = AliPayApi.tradePrecreatePayToResponse(model, notifyUrl).getBody();
|
||
// 返回二维码字符串
|
||
}
|
||
```
|
||
|
||
#### 2.2 PC网页支付
|
||
|
||
```java
|
||
@PostMapping("/pc-pay")
|
||
public void pcPay(...) {
|
||
AlipayTradePagePayModel model = new AlipayTradePagePayModel();
|
||
model.setOutTradeNo(outTradeNo);
|
||
model.setProductCode("FAST_INSTANT_TRADE_PAY");
|
||
model.setTotalAmount(totalAmount);
|
||
model.setSubject(subject);
|
||
|
||
// 使用 IJPay 的 AliPayApi 进行页面跳转
|
||
AliPayApi.tradePage(response, model, notifyUrl, returnUrl);
|
||
}
|
||
```
|
||
|
||
#### 2.3 手机网页支付
|
||
|
||
```java
|
||
@PostMapping("/wap-pay")
|
||
public void wapPay(...) {
|
||
AlipayTradeWapPayModel model = new AlipayTradeWapPayModel();
|
||
model.setOutTradeNo(outTradeNo);
|
||
model.setProductCode("QUICK_WAP_PAY");
|
||
model.setTotalAmount(totalAmount);
|
||
|
||
// 使用 IJPay 的 AliPayApi 进行手机支付
|
||
AliPayApi.wapPay(response, model, returnUrl, notifyUrl);
|
||
}
|
||
```
|
||
|
||
#### 2.4 APP支付
|
||
|
||
```java
|
||
@PostMapping("/app-pay")
|
||
public ResponseEntity<Map<String, Object>> appPay(...) {
|
||
AlipayTradeAppPayModel model = new AlipayTradeAppPayModel();
|
||
model.setOutTradeNo(outTradeNo);
|
||
model.setProductCode("QUICK_MSECURITY_PAY");
|
||
model.setTotalAmount(totalAmount);
|
||
|
||
// 使用 IJPay 的 AliPayApi 获取 APP 支付订单信息
|
||
String orderInfo = AliPayApi.appPayToResponse(model, notifyUrl).getBody();
|
||
// 返回订单信息给 APP
|
||
}
|
||
```
|
||
|
||
#### 2.5 订单查询
|
||
|
||
```java
|
||
@GetMapping("/query")
|
||
public ResponseEntity<Map<String, Object>> queryOrder(...) {
|
||
AlipayTradeQueryModel model = new AlipayTradeQueryModel();
|
||
model.setOutTradeNo(outTradeNo);
|
||
|
||
// 使用 IJPay 的 AliPayApi 查询订单
|
||
String result = AliPayApi.tradeQueryToResponse(model).getBody();
|
||
// 返回查询结果
|
||
}
|
||
```
|
||
|
||
#### 2.6 退款
|
||
|
||
```java
|
||
@PostMapping("/refund")
|
||
public ResponseEntity<Map<String, Object>> refund(...) {
|
||
AlipayTradeRefundModel model = new AlipayTradeRefundModel();
|
||
model.setOutTradeNo(outTradeNo);
|
||
model.setRefundAmount(refundAmount);
|
||
model.setRefundReason(refundReason);
|
||
|
||
// 使用 IJPay 的 AliPayApi 发起退款
|
||
String result = AliPayApi.tradeRefundToResponse(model).getBody();
|
||
// 返回退款结果
|
||
}
|
||
```
|
||
|
||
#### 2.7 异步通知处理
|
||
|
||
```java
|
||
@PostMapping("/notify")
|
||
public String notifyUrl(HttpServletRequest request) {
|
||
// 使用 IJPay 的 AliPayApi 将请求参数转换为 Map
|
||
Map<String, String> params = AliPayApi.toMap(request);
|
||
|
||
// 验证签名
|
||
boolean verifyResult = AlipaySignature.rsaCertCheckV1(
|
||
params, aliPayConfig.getAliPayCertPath(), "UTF-8", "RSA2");
|
||
|
||
if (verifyResult) {
|
||
// 处理支付成功逻辑
|
||
return "success";
|
||
} else {
|
||
return "failure";
|
||
}
|
||
}
|
||
```
|
||
|
||
## 三、IJPay 配置说明
|
||
|
||
### 3.1 配置方式
|
||
|
||
IJPay 的 `AliPayApi` 类内部会自动读取系统属性或配置文件中的支付宝配置。
|
||
|
||
需要配置的参数包括：
|
||
- `appId`: 支付宝应用ID
|
||
- `privateKey`: 应用私钥
|
||
- `publicKey`: 支付宝公钥
|
||
- `gatewayUrl`: 支付宝网关地址
|
||
- `charset`: 字符编码（通常为 UTF-8）
|
||
- `signType`: 签名类型（通常为 RSA2）
|
||
|
||
### 3.2 配置文件
|
||
|
||
配置在 `application-dev.properties` 或 `application-prod.properties` 中：
|
||
|
||
```properties
|
||
# 支付宝配置
|
||
alipay.app-id=你的APPID
|
||
alipay.private-key=你的应用私钥
|
||
alipay.public-key=支付宝公钥
|
||
alipay.gateway-url=https://openapi.alipaydev.com/gateway.do
|
||
alipay.charset=UTF-8
|
||
alipay.sign-type=RSA2
|
||
alipay.notify-url=回调通知地址
|
||
alipay.return-url=同步返回地址
|
||
```
|
||
|
||
### 3.3 IJPay 初始化（可选）
|
||
|
||
如果需要显式初始化 IJPay，可以在应用启动时配置：
|
||
|
||
```java
|
||
@Configuration
|
||
public class IJPayConfig {
|
||
|
||
@Autowired
|
||
private AliPayConfig aliPayConfig;
|
||
|
||
@PostConstruct
|
||
public void init() {
|
||
// IJPay 的 AliPayApi 会自动读取配置
|
||
// 如果需要显式配置，可以使用 AliPayApiConfigKit
|
||
// 注意：具体初始化方式取决于 IJPay 版本
|
||
}
|
||
}
|
||
```
|
||
|
||
## 四、IJPay vs 原生 Alipay SDK
|
||
|
||
项目中同时使用了两种方式：
|
||
|
||
1. **IJPay (AliPayApi)** - 在 `AlipayController.java` 中使用
|
||
- 优点：封装更简洁，使用更方便
|
||
- 缺点：需要额外依赖 IJPay 库
|
||
|
||
2. **原生 Alipay SDK (DefaultAlipayClient)** - 在 `AlipayService.java` 中使用
|
||
- 优点：官方 SDK，功能完整
|
||
- 缺点：需要手动创建客户端和处理响应
|
||
|
||
## 五、常见问题
|
||
|
||
### Q1: IJPay 如何初始化？
|
||
|
||
A: IJPay 的 `AliPayApi` 类内部会自动读取配置，通常不需要显式初始化。如果遇到配置问题，可以检查：
|
||
1. 配置文件中的参数是否正确
|
||
2. 系统属性是否设置
|
||
3. 环境变量是否配置
|
||
|
||
### Q2: 如何切换到 IJPay？
|
||
|
||
A: 如果当前使用原生 Alipay SDK，可以：
|
||
1. 修改 `AlipayService.java`，使用 `AliPayApi` 替代 `DefaultAlipayClient`
|
||
2. 或者直接使用 `AlipayController` 中的接口
|
||
|
||
### Q3: IJPay 和原生 SDK 的区别？
|
||
|
||
A: IJPay 是对原生 SDK 的封装，提供了更简洁的 API。底层实现仍然使用支付宝官方 SDK。
|
||
|
||
## 六、参考文档
|
||
|
||
- IJPay 官方文档：https://github.com/Javen205/IJPay
|
||
- IJPay 示例项目：https://github.com/Javen205/IJPay-Demo
|
||
- 支付宝开放平台：https://open.alipay.com
|
||
|
||
|