# 基础概念及业务介绍

## 一、角色（接入模式）

| | 普通商户 | 服务商 | 平台服务商（收付通） | 品牌商户 | 特约商户 |
| --- | --- | --- | --- | --- | --- |
| **一句话介绍** | 自己申请商户号，自己对接微信支付 API 收款 | 代特约商户对接微信支付；也可受品牌方委托代调品牌经营平台接口 | 先成为服务商，且底下不能有子商户，然后申请收付通权限；适用于电商/O2O 等平台类业务 | 拥有 `brand_id`，通过品牌经营平台（商家名片 / 摇优惠 / 商品券等）做用户运营 | 由服务商进件创建，获得 `sub_mchid`。特约商户可自行登录商户平台申请证书和密钥，用 `sub_mchid` 调用普通商户接口收款（电商子商户、小微/小商户、间连子商户除外） |
| **商户号** | `mchid` | `sp_mchid` | `sp_mchid` | 无独立商户号，标识为 `brand_id` | `sub_mchid` |
| **资金关系** | 结算到自己的商户账户 | 资金结算到特约商户，服务商通过分账获取佣金 | 资金先进入平台待分账账户，由平台发起分账到二级商户 | 品牌经营不涉及资金结算，属营销与用户运营 | 结算到自己的账户 |
| **角色关系** | 独立运作，无上下级 | 一个服务商可管理多个特约商户；也可受多个品牌方委托 | 一个平台服务商下有多个二级商户 | 可由品牌独立接入，也可委托服务商代接（需在品牌经营平台授权） | 归属于某个服务商，由服务商进件创建 |

---

## 二、API 版本

微信支付有三个文档/接口体系，各自独立鉴权：

| 文档分支 | API 版本 | 鉴权方式 |
| --- | --- | --- |
| **APIv2** | V2（存量维护） | API 密钥签名（MD5 / HMAC-SHA256），XML 报文 |
| **APIv3** | V3（主力版本） | 签名：商户API证书或私钥（`WECHATPAY2-SHA256-RSA2048`）；验签：微信支付公钥（推荐）或平台证书。JSON 报文 |
| **brand** | 品牌经营专用 | 签名：品牌API证书或私钥（`WECHATPAY-BRAND-SHA256-RSA2048`）；验签：微信支付公钥（推荐）或平台证书。JSON 报文 |

V2 存量维护，不再新增功能，V3 是主力版本。**默认使用 V3**，仅当产品/接口只有 V2 版本时才用 V2。若用户未指定版本，一律按 V3 提供，**严禁主动推荐或引导用户使用 V2**。

---

## 三、产品版本偏好

除 API 版本（V2/V3）外，部分产品本身也存在新旧版本迭代（如商家转账升级版、移动医保支付 2.0 等）。**当同一产品存在多个版本时，默认按最新版本提供文档**；若用户使用旧版本，提示有新版本可升级。

---

## 四、核心 ID 及其关系

| ID | 含义 | 归属 | 获取方式 | 与其他 ID 的关系 | 绑定操作 | 注意事项 |
| --- | --- | --- | --- | --- | --- | --- |
| `mchid` | 普通商户号 | 普通商户 | 在商户平台自行申请 | 与 `appid` **多对多**绑定，绑定后方可发起支付 | 商户平台「账户中心-账户设置-APPID授权管理」发起绑定，appid 所在平台确认后生效 | 绑定后**不可解绑** |
| `sp_mchid` | 服务商商户号 | 服务商 / 平台服务商 | 在商户平台申请服务商资质 | 与 `sub_mchid` 一对多；与 `mchid` 一对多（一个服务商可管理多个特约商户和普通商户） | 服务商平台「产品中心-APPID账号管理-我关联的APPID账号」新增关联 | — |
| `sub_mchid` | 特约商户号 | 特约商户 | 由服务商通过进件接口创建 | 归属于 `sp_mchid`（一对多） | 服务商调用进件接口时自动创建归属关系，无需手动操作 | — |
| `appid` | 应用 ID | 公众号 / 小程序 / 移动应用 / 网站应用 | 在公众平台或开放平台创建应用获得 | 与 `mchid` 多对多；与 `brand_id` **多对多**（一个品牌可关联多个 appid，一个 appid 也可关联多个品牌） | 品牌关联：品牌经营平台「账号管理-下单appid管理」；服务商关联：服务商平台「产品中心-APPID账号管理-我关联的APPID账号」 | appid 需先完成认证才能关联；未关联时调接口报 `AppID非法` |
| `brand_id` | 品牌 ID | 品牌商户 | 在品牌经营平台申请/创建 | 与 `appid` 多对多；与 `mchid` 多对多（服务商代接时，一个服务商可服务多个品牌，一个品牌也可授权多个服务商） | 服务商代接：品牌在品牌经营平台授权服务商 | 未授权报 `NO_AUTH` |
| `openid` | 用户标识 | 用户 × appid | 用户授权某个 appid 后生成 | 同一用户在不同 appid 下 openid 不同；与 `appid` 一一对应，下单时 openid 必须属于所传的 appid | 通过用户授权获取：H5/JSAPI 走网页授权、小程序走 `wx.login`、App 走开放平台授权 | openid 与 appid 不匹配会报错 |

---

## 五、证书与密钥

| 维度 | 商户 API 证书 | 平台证书 | 微信支付公钥 | APIv3 密钥 | APIv2 密钥 | 品牌 API 证书 |
| --- | --- | --- | --- | --- | --- | --- |
| **概述** | 证明商户身份，生成请求签名 | 验证微信支付身份、加密敏感字段 | 平台证书的替代方案，功能一致，长期有效更易维护，推荐使用 | 解密 V3 回调通知数据 | V2 请求签名与验签（对称加密，MD5/HMAC-SHA256） | 证明品牌商户身份，生成 brand 接口请求签名。在品牌经营平台申请，与商户 API 证书是两套独立的证书和私钥，**不能混用** |
| **数据形式** | apiclient_cert.pem + apiclient_key.pem + .p12 | wechatpay_xxx.pem（带有效期） | pub_key.pem（无有效期） | 32 位字母数字字符串 | 32 位字母数字字符串 | pem 格式（独立的证书序列号和私钥） |
| **适用场景** | V3/V2 普通商户及服务商接口 | V3 验签应答/回调、加密姓名证件号等敏感字段（与微信支付公钥二选一） | V3 验签应答/回调、加密敏感字段（与平台证书二选一） | V3 回调通知解密 | V2 全部接口签名验签 | 仅用于 brand 品牌经营接口（签名类型 `WECHATPAY-BRAND-SHA256-RSA2048`），不能调 V3/V2 普通接口 |

V2 和 V3 是两套独立体系，同一个商户号，两套体系可并存：

- V2：APIv2 密钥 + 商户 API 证书
- V3：APIv3 密钥 + 商户 API 证书 + 平台证书/微信支付公钥

---

## 六、营销业务全景与选型

微信支付营销的核心是三大券能力，配合发券/投放工具触达用户：

| 维度 | 商品券 | 代金券 | 商家券 |
| --- | --- | --- | --- |
| **定位** | 品牌优惠券全链路方案；单券（`stock`，单次核销）与多次优惠（`stock_bundle`，3-15 次阶梯核销）两种券型；可投放平台流量与商家自有流量 | 官方满减/单品换购工具；支付前发放、支付中自动核销（实付=订单金额−券额）；分预充值与免充值；支持全员/新人/抽奖等场景；卡包过期提醒+防刷 | 满减/换购/折扣三种券型；券码可微信生成或商户自定义（适配已有 Code 体系）；支持线上小程序核销与线下扫码核销。**已存量维护、不再迭代**（2025-12-15 起不受理新接入） |
| **发券工具/渠道** | 摇一摇有优惠（平台流量）；向用户发放商品券 API 或小程序发券组件（商品券独有，和小程序发券插件是两套API）（自有流量） | 商户自有任意场景 API 发券（小程序/H5/App）、小程序发券插件 | H5发券、小程序发券插件、支付有礼（已升级至摇一摇） |
| **区别点** | 微信平台流量、支付完成页互动领券；含单券/多次优惠 | 官方满减/折扣券，支付前发放、**支付中自动核销**（无需主动核销） | 已被商品券替代 |
| **接口版本（接入模式）** | APIv3（服务商）/ brand（品牌） | APIv3（普通商户 / 服务商） | APIv3（普通商户 / 服务商） |
| **功能状态** | **主力**（新接入推荐） | 在用 | **存量·不再迭代** |

---

## 七、重点：商品券

### 7.1 两种发放场景

商品券有两种发放场景，共享同一套品牌经营底座（`brand_id` + 商品券券源），区别在于触达入口与所需功能：

**摇一摇有优惠（平台流量）**：用户支付完成后在微信侧"摇一摇·支付完成页"曝光领券。

- 前置：品牌入驻(`brand_id`) + 商家名片或品牌门店（二选一，决定用户入口/按位置投放）+ 投放计划（选商品券 + 价格批次）
- 服务商模式额外前提：品牌服务商授权(BM)
- 接入流程：品牌入驻拿 `brand_id` → 建商家名片或品牌门店（二选一）→ 创建商品券 → 建投放计划（选券 + 价格批次）→ 摇一摇支付完成页曝光领券

**商户API发券（自有流量）**：商户在小程序/H5/App 等场景主动发券，核心只需 `品牌入驻(brand_id)` + 创建商品券；无需投放计划，商家名片/品牌门店仅按需（按指定门店投放时才需建门店并关联批次）。

- 接入流程：品牌入驻拿 `brand_id` → 创建商品券 → 自有场景调用「向用户发放商品券 API」或「小程序发券组件」发放 → 用户使用后调用「核销商品券」核销

> 两种场景均可按「品牌直连」或「服务商代运营」接入：
>
> - 品牌直连：品牌用自己的 `brand_id` 操作，仅需关联下单 appid（BA 关系），无需 BM 授权。
> - 服务商代运营：服务商用自己的 `mchid` 调用 APIv3 合作伙伴接口、请求携带目标 `brand_id` 代品牌操作；必须先经品牌授权（BM 关系）。

### 7.2 核心概念

**商品信息 vs 批次信息**：商品券由两层组成，首次创建会**同时创建**商品信息及第一个批次，后续可在同一商品券下追加批次（多批次属同一商品券，一个批次仅属一个商品券）。

- **商品信息**（跨批次共享）：基础信息（券名称、商品图片、原价、展示信息）+ 优惠模式（优惠范围：全场/部分商品可用；券类型：满减/折扣/兑换；使用模式：单券/多次优惠）。
- **批次信息**（每次投放可变）：优惠规则（可用时间、力度）+ 发放规则（券码分配、发放规则、可用门店范围）+ 使用展示规则。

> 修改：商品层改用「修改商品券」，批次层改用「修改商品券批次」/「修改商品券批次组」；修改仅对新发券生效。

**批次 vs 批次组**：

- **批次**（仅单券模式）：一个批次发一张券、用一次即失效。有效期按单批次维度、各批次可独立设置。
- **批次组**（仅多次优惠模式）：多个批次的有序集合，一次发放含多张券的"券组"。按顺序核销 3-15 次，每核销一轮微信侧再发下一轮券并回调领券结果。