# flutter_paydemo 支付技术文档

Flutter 支付演示 Demo 的技术文档集，覆盖 7 种主流支付方式的前后端集成方案。

## 支付方式索引

| 文档 | 支付方式 | 适用端 | 说明 |
| --- | --- | --- | --- |
| [支付宝支付](alipay.md) | Alipay App 支付 / PC 支付 / 手机网站支付 | iOS / Android / Web | 中国大陆主流，支持 App 内拉起支付宝、扫码、H5 |
| [微信支付](wechat_pay.md) | WeChat Pay APP / JSAPI / Native / H5 | iOS / Android / Web / 公众号 | 中国大陆主流，支持 App 内拉起微信、扫码、公众号内支付 |
| [银联云闪付](unionpay.md) | UnionPay App 支付 / 手机网站支付 | iOS / Android / Web | 银联移动支付，覆盖全部银联卡，RSA2 签名 + `tn` 拉起云闪付 |
| [Apple Pay](apple_pay.md) | Apple Pay（PassKit / StoreKit） | iOS / Web（Safari） | Apple 生态，基于 Token 化银行卡支付 |
| [Google Pay](google_pay.md) | Google Pay | Android / Web（Chrome） | Google 生态，基于 Token 化银行卡支付 |
| [Stripe](stripe.md) | Stripe PaymentIntent / Checkout / PaymentSheet | 全平台（含海外） | 全球主流，聚合多支付方式，支持 3DS |
| [网页支付](web_payment.md) | 网页收银台（Native 扫码 / 支付宝 PC / Stripe Checkout） | Web | 无 App 场景下的聚合支付收银台方案 |

## 总体架构

```
┌──────────────────────────────────────────────────────────────────┐
│                          客户端 (Flutter)                          │
│  iOS / Android / Web                                              │
│  · 微信支付：fluwx                                                │
│  · 支付宝：flutter_alipay / 阿里云开放平台 SDK                      │
│  · 云闪付：uppay:// scheme / 银联官方 SDK                          │
│  · Apple Pay：pay(flutter) / flutter_stripe                       │
│  · Google Pay：pay(flutter) / flutter_stripe                      │
│  · Stripe：flutter_stripe                                        │
└───────────────────────────────┬──────────────────────────────────┘
                                │ HTTPS / JSON
┌───────────────────────────────▼──────────────────────────────────┐
│                          业务后端                                  │
│  Node.js(Express) / Java(Spring Boot) / Python(FastAPI)           │
│  · 订单服务：创建订单、支付状态查询                                │
│  · 支付服务：调起各支付平台"统一下单"接口、生成调起参数            │
│  · 回调服务：接收支付平台异步通知，验签、更新订单、发货            │
└───────────────┬──────────────────────────────┬───────────────────┘
                │  HTTPS                       │  异步通知
┌───────────────▼───────────────┐   ┌──────────▼───────────────────┐
│  支付平台服务端                  │   │  支付平台异步通知（回调）       │
│  支付宝 / 微信 / Stripe /       │   │  Webhook → 验签 → 幂等处理     │
│  Apple / Google               │   └──────────────────────────────┘
└───────────────────────────────┘
```

## 通用约定

### 前后端职责划分（所有支付方式通用）

| 职责 | 端 | 说明 |
| --- | --- | --- |
| 创建订单、计算金额 | 后端 | 金额必须以服务端为准，禁止信任客户端传入金额 |
| 调起支付、生成签名 | 后端 | 统一下单接口由服务端调用支付平台，密钥不落客户端 |
| 展示支付渠道、拉起收银台 | 前端 | 拿到后端返回的调起参数，拉起原生支付/支付页面 |
| 支付结果确认 | 后端 | 以支付平台**异步通知 + 主动查询**双通道确认结果 |
| 更新订单、发货/发放权益 | 后端 | 在回调中完成，需保证幂等 |

### 统一订单/支付流程（时序图）

```mermaid
sequenceDiagram
    participant Client as Flutter App
    participant Backend as 业务后端
    participant Gateway as 支付平台(支付宝/微信/Stripe...)

    Client->>Backend: 1. 提交订单 POST /api/orders
    Backend->>Backend: 创建订单(状态: 待支付)
    Backend->>Gateway: 2. 统一下单(金额/订单号/回调地址)
    Gateway-->>Backend: 返回支付调起参数(orderStr/prepay_id/client_secret)
    Backend-->>Client: 3. 返回调起参数
    Client->>Gateway: 4. 拉起支付(拉起App/收银台/PaymentSheet)
    Gateway->>Backend: 5. 异步通知(回调地址, 带签名)
    Backend->>Backend: 验签 + 幂等处理 + 更新订单(已支付) + 发货
    Client->>Backend: 6. 主动查询订单状态(轮询/进入页面时)
    Backend-->>Client: 返回最终支付结果
```

### 约定接口风格

各支付文档中的后端接口遵循统一 RESTful 风格，与 `lib/service/pay_service.dart` 中现有调用对应：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/v1/payment/{channel}/` | 创建支付（channel: wechatpay/alipay/unionpay/stripe/apple/google） |
| `GET` | `/v1/payment/{payment_id}` | 查询支付状态 |
| `POST` | `/v1/payment/notify/{channel}` | 支付平台异步通知回调 |
| `POST` | `/v1/payment/refund` | 退款（可选） |

### 安全通用原则

1. **密钥永不下发客户端**：支付平台密钥（appSecret、APIv3 Key、签名私钥）仅存后端。
2. **金额服务端为准**：下单金额由后端计算并签名，客户端不可修改。
3. **回调必须验签**：任何异步通知先验签/验签失败即丢弃，再处理业务。
4. **回调处理需幂等**：同一笔订单重复通知时只成功处理一次（按订单号加锁或状态机）。
5. **统一错误码**：支付类错误建议统一错误码，便于前端提示（见各文档）。

## 各文档包含内容

每份支付文档均包含：

- 支付方式概述与适用场景
- 申请与配置（商户号、密钥、证书、沙箱）
- 完整支付流程图（mermaid 时序图）
- **后端集成**（以 Node.js/Express 为参考，附 Java/Python 说明）
  - 统一下单 / 生成调起参数
  - 签名与验签
  - 异步回调处理（幂等）
  - 主动查询 / 退款
- **前端集成**（Flutter）
  - 依赖与初始化
  - 拉起支付代码示例
  - 结果处理
- RESTful 接口定义（请求/响应示例）
- 安全注意事项
- 沙箱与测试
- 常见问题

## 快速开始

```bash
# 1. 添加依赖（以 Stripe 为例）
flutter pub add flutter_stripe

# 2. 阅读对应支付文档，按步骤申请密钥并配置后端
# 3. 后端实现 /v1/payment/{channel}/ 与 /v1/payment/notify/{channel}
# 4. 前端实现 拉起支付 → 查询结果
```

---

> 本文档目录：`docs/`，后端参考代码以 Node.js(Express) 为主，其余技术栈（Java/Python）仅在关键差异处说明。