新版官网模板
This commit is contained in:
387
docs/payment-integration.md
Normal file
387
docs/payment-integration.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# 支付与订单闭环实现指南
|
||||
|
||||
## 📦 已完成的前端实现
|
||||
|
||||
### 1. 支付 API 模块 (`app/api/payment/index.ts`)
|
||||
|
||||
提供统一的支付接口封装：
|
||||
|
||||
```typescript
|
||||
import {
|
||||
createWechatJsapiPay, // 微信 JSAPI 支付
|
||||
createWechatH5Pay, // 微信 H5 支付
|
||||
createWechatNativePay, // 微信 Native 扫码支付
|
||||
createAlipayPay, // 支付宝网页支付
|
||||
queryPayStatus, // 查询支付状态
|
||||
detectPayEnvironment, // 检测支付环境
|
||||
isWechatBrowser, // 检测微信浏览器
|
||||
isAlipayBrowser // 检测支付宝浏览器
|
||||
} from '@/api/payment'
|
||||
```
|
||||
|
||||
### 2. 支付组件 (`app/components/payment/PaymentModal.vue`)
|
||||
|
||||
开箱即用的支付弹窗组件，支持：
|
||||
- **微信 JSAPI** - 微信内置浏览器调起微信支付
|
||||
- **微信 H5** - 非微信浏览器跳转微信H5支付页面
|
||||
- **微信 Native** - 扫码支付，显示二维码
|
||||
- **支付宝 WAP** - 跳转支付宝支付页面
|
||||
- **余额支付** - 平台余额直接扣款
|
||||
|
||||
使用方式：
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<PaymentModal
|
||||
v-model:visible="payModalVisible"
|
||||
:order-no="order.orderNo"
|
||||
:order-id="order.orderId"
|
||||
:pay-price="order.payPrice"
|
||||
:available-methods="{ wechat: true, alipay: true, balance: false }"
|
||||
@success="onPaySuccess"
|
||||
/>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import PaymentModal from '@/components/payment/PaymentModal.vue'
|
||||
|
||||
const payModalVisible = ref(false)
|
||||
|
||||
function openPay(order) {
|
||||
payModalVisible.value = true
|
||||
}
|
||||
|
||||
function onPaySuccess(result) {
|
||||
console.log('支付成功', result)
|
||||
// 刷新订单列表等操作
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### 3. 订单页面集成 (`app/pages/orders.vue`)
|
||||
|
||||
已完善 `goPay()`、`applyRefund()`、`cancelOrder()` 功能：
|
||||
- 点击"去支付"打开支付弹窗
|
||||
- 点击"申请退款"弹出确认框
|
||||
- 点击"取消订单"弹出确认框
|
||||
|
||||
---
|
||||
|
||||
## 🔧 后端需要实现的接口
|
||||
|
||||
### 1. 微信 JSAPI 支付
|
||||
|
||||
```
|
||||
POST /api/system/wx-jsapi-pay/unified-order
|
||||
```
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"orderNo": "订单号",
|
||||
"openId": "用户 OpenId",
|
||||
"subject": "商品描述",
|
||||
"body": "商品详情",
|
||||
"totalAmount": 100, // 金额（分）
|
||||
"returnUrl": "支付完成跳转URL"
|
||||
}
|
||||
```
|
||||
|
||||
**返回参数：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"prepayId": "预支付交易会话标识",
|
||||
"codeUrl": "公众号 AppId",
|
||||
"mwebUrl": "H5支付链接"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 微信 H5 支付
|
||||
|
||||
```
|
||||
POST /api/system/wx-h5-pay/unified-order
|
||||
```
|
||||
|
||||
**请求参数：** 同 JSAPI
|
||||
**返回参数：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"mwebUrl": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 微信 Native 支付
|
||||
|
||||
```
|
||||
POST /api/system/wx-native-pay/unified-order
|
||||
```
|
||||
|
||||
**返回参数：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"codeUrl": "weixin://wxpay/bizpayurl?..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 支付宝网页支付
|
||||
|
||||
```
|
||||
POST /api/system/alipay/unified-order
|
||||
```
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"orderNo": "订单号",
|
||||
"subject": "商品标题",
|
||||
"body": "商品描述",
|
||||
"totalAmount": 100, // 金额（元）
|
||||
"returnUrl": "支付完成跳转URL"
|
||||
}
|
||||
```
|
||||
|
||||
**返回参数：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"paymentUrl": "https://openapi.alipay.com/gateway.do?..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 查询支付状态
|
||||
|
||||
```
|
||||
GET /api/system/payment/query-status?orderNo=xxx
|
||||
```
|
||||
|
||||
**返回参数：**
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"paid": true,
|
||||
"payStatus": 1,
|
||||
"orderStatus": 1,
|
||||
"payTime": "2024-01-01 12:00:00",
|
||||
"transactionId": "微信/支付宝交易号"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 取消订单
|
||||
|
||||
```
|
||||
POST /api/system/order/cancel
|
||||
```
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"orderId": 123
|
||||
}
|
||||
```
|
||||
|
||||
### 7. 申请退款
|
||||
|
||||
```
|
||||
POST /api/system/order/refund
|
||||
```
|
||||
|
||||
**请求参数：**
|
||||
```json
|
||||
{
|
||||
"orderId": 123,
|
||||
"reason": "退款原因"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 微信支付配置
|
||||
|
||||
### 1. 微信商户平台配置
|
||||
|
||||
登录 [微信商户平台](https://pay.weixin.qq.com)，获取以下信息：
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|--------|------|
|
||||
| AppID | 公众号应用ID |
|
||||
| MchID | 商户号 |
|
||||
| API Key | APIv2 密钥 |
|
||||
| APIv3 Key | APIv3 密钥 |
|
||||
| 证书 | 商户证书（用于退款等敏感操作） |
|
||||
| AppSecret | 公众号应用密钥 |
|
||||
|
||||
### 2. 后端配置示例
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
wechat:
|
||||
pay:
|
||||
app-id: wx1234567890abcdef
|
||||
mch-id: 1234567890
|
||||
api-key: xxxxxxxx
|
||||
api-v3-key: xxxxxxxx
|
||||
notify-url: https://your-domain.com/api/payment/notify
|
||||
refund-url: https://your-domain.com/api/payment/refund-notify
|
||||
cert-path: /path/to/apiclient_cert.p12
|
||||
```
|
||||
|
||||
### 3. JSAPI 支付配置
|
||||
|
||||
需要在微信公众平台配置：
|
||||
- **JS接口安全域名** - 发起支付的页面域名
|
||||
- **网页授权域名** - 用于获取 OpenId
|
||||
|
||||
---
|
||||
|
||||
## 🔐 支付宝配置
|
||||
|
||||
### 1. 支付宝开放平台配置
|
||||
|
||||
登录 [支付宝开放平台](https://open.alipay.com)，创建应用并获取：
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|--------|------|
|
||||
| AppID | 应用ID |
|
||||
| PrivateKey | 应用私钥 |
|
||||
| AlipayPublicKey | 支付宝公钥 |
|
||||
|
||||
### 2. 后端配置示例
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
alipay:
|
||||
app-id: 2021000000000000
|
||||
private-key: xxxxxxxx
|
||||
alipay-public-key: xxxxxxxx
|
||||
notify-url: https://your-domain.com/api/payment/alipay-notify
|
||||
return-url: https://your-domain.com/api/payment/alipay-return
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 支付流程
|
||||
|
||||
### 微信 JSAPI 支付流程
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ 用户下单 │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ 后端创建订单 │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 前端调用 createWechatJsapiPay │
|
||||
│ (传入 openId、订单信息) │
|
||||
└──────┬────────────────────────────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ 后端统一下单 │
|
||||
│ 返回 prepayId │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ 前端调起 │
|
||||
│ WeixinJSBridge │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ 用户输入密码 │
|
||||
│ 完成支付 │
|
||||
└──────┬──────┘
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 微信回调后端 + 前端轮询 queryPayStatus │
|
||||
└──────┬────────────────────────────┘
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ 显示支付成功 │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### 支付结果通知
|
||||
|
||||
后端需要实现支付结果回调：
|
||||
|
||||
```
|
||||
POST /api/system/payment/notify (微信)
|
||||
POST /api/system/payment/alipay-notify (支付宝)
|
||||
```
|
||||
|
||||
收到回调后：
|
||||
1. 验证签名
|
||||
2. 更新订单状态
|
||||
3. 返回 success 给支付方
|
||||
|
||||
---
|
||||
|
||||
## 🎯 快速开始
|
||||
|
||||
### 1. 完成后端接口
|
||||
|
||||
按照"后端需要实现的接口"章节实现各个支付接口。
|
||||
|
||||
### 2. 配置密钥
|
||||
|
||||
在微信商户平台和支付宝开放平台完成配置，获取必要的密钥。
|
||||
|
||||
### 3. 更新 API 路径
|
||||
|
||||
如果后端接口路径与设计不同，更新 `app/api/payment/index.ts` 中的接口路径。
|
||||
|
||||
### 4. 测试支付
|
||||
|
||||
1. 启动前端：`pnpm dev`
|
||||
2. 登录后进入订单页面
|
||||
3. 点击"去支付"测试支付流程
|
||||
|
||||
---
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
### 1. 金额单位
|
||||
|
||||
- **前端传给后端**：元（保留2位小数）或 分（整数）
|
||||
- **微信/支付宝**：通常使用**分**
|
||||
- 建议前端统一传元，后端转为分
|
||||
|
||||
### 2. 订单号
|
||||
|
||||
- 建议使用业务方生成的唯一订单号
|
||||
- 避免重复支付
|
||||
- 建议格式：`PAY + 时间戳 + 随机数`
|
||||
|
||||
### 3. 回调通知
|
||||
|
||||
- 必须实现支付结果回调
|
||||
- 回调地址需要公网可访问
|
||||
- 注意防止重复处理
|
||||
|
||||
### 4. 安全建议
|
||||
|
||||
- 所有支付相关接口需要登录验证
|
||||
- 金额计算在后端完成
|
||||
- 签名验证在前端不做，后端完成
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关资源
|
||||
|
||||
- [微信支付开发文档](https://pay.weixin.qq.com/wiki/doc/apiv3/index.shtml)
|
||||
- [支付宝支付文档](https://opendocs.alipay.com/open/270)
|
||||
- [JSSDK 使用说明](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html)
|
||||
Reference in New Issue
Block a user