flutter_paydemo/docs/README.md

flutter_paydemo 支付技术文档

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

支付方式索引

文档	支付方式	适用端	说明
支付宝支付	Alipay App 支付 / PC 支付 / 手机网站支付	iOS / Android / Web	中国大陆主流，支持 App 内拉起支付宝、扫码、H5
微信支付	WeChat Pay APP / JSAPI / Native / H5	iOS / Android / Web / 公众号	中国大陆主流，支持 App 内拉起微信、扫码、公众号内支付
银联云闪付	UnionPay App 支付 / 手机网站支付	iOS / Android / Web	银联移动支付，覆盖全部银联卡，RSA2 签名 + tn 拉起云闪付
Apple Pay	Apple Pay（PassKit / StoreKit）	iOS / Web（Safari）	Apple 生态，基于 Token 化银行卡支付
Google Pay	Google Pay	Android / Web（Chrome）	Google 生态，基于 Token 化银行卡支付
Stripe	Stripe PaymentIntent / Checkout / PaymentSheet	全平台（含海外）	全球主流，聚合多支付方式，支持 3DS
网页支付	网页收银台（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               │   └──────────────────────────────┘
└───────────────────────────────┘

通用约定

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

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

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

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 接口定义（请求/响应示例）
• 安全注意事项
• 沙箱与测试
• 常见问题

快速开始

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

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

---

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