From e44a09e7e16d60b107bd344ec5a1e51114c8e0d5 Mon Sep 17 00:00:00 2001
From: ivan <ivan@qq.com>
Date: Wed, 22 Apr 2026 17:46:22 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=EF=BC=9A=E6=94=AF=E4=BB=98?=
 =?UTF-8?q?=E6=B5=81=E7=A8=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/payment_flow.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/payment_flow.md b/docs/payment_flow.md
index 9c5de4c..6c004ac 100644
--- a/docs/payment_flow.md
+++ b/docs/payment_flow.md
@@ -80,12 +80,28 @@
 
 ### 5.2 创建订单
 
-创建订单请求通常包含：
+创建订单请求通常包含（**逻辑字段名**）：
 
 - 应用标识（`app`）
 - 用户标识（`userId`）
 - 商品或活动标识（`activityId` / `productId`）
-- 支付方式（`paymentMethod`、可选 `paymentType`）
+- 支付主方式（`paymentMethod`）
+- 支付类型（`paymentType`，按渠道语义填写）
+- 子支付方式（`subPaymentMethod`，如卡种/钱包子通道）
+
+> 关键点：`subPaymentMethod` 是独立语义字段。  
+> 仅传 `paymentType` 不会自动补出 `subPaymentMethod`。
+
+#### 5.2.1 推荐入参组合（避免丢子支付方式）
+
+- 卡支付场景（示例）：
+  - `paymentMethod = MIFAPAY`
+  - `paymentType = MIFAPAY`（或按后端约定值）
+  - `subPaymentMethod = CreditCard`
+- 若传成 `paymentType = CreditCard` 且未传 `subPaymentMethod`，常见结果是：
+  - 有 `paymentMethod`
+  - 有 `paymentType`
+  - **缺少 `subPaymentMethod`**
 
 响应通常返回：
 
@@ -185,6 +201,15 @@
 - **常见原因**：上一笔交易未完成/未消费；
 - **排查建议**：执行补单恢复流程并确保完成/消费逻辑成功。
 
+### 10.4 创建订单请求缺少子支付方式字段
+
+- **现象**：抓包中 `createPayment` 入参有 `paymentMethod`，但缺少 `subPaymentMethod`；
+- **常见原因**：只传了 `paymentType`，没有传 `subPaymentMethod`；
+- **排查建议**：
+  - 检查应用侧建单调用是否显式传入 `subPaymentMethod`；
+  - 对照请求日志逐项核对三元组：`paymentMethod` / `paymentType` / `subPaymentMethod`；
+  - 若项目启用了字段映射，再额外确认映射配置与服务端契约一致。
+
 ---
 
 ## 11. 实施建议（多客户端复用）