---
url: "https://pay.weixin.qq.com/doc/brand/4016060894.md"
title: "开发指引"
doc_id: 4016060894
---

>更新时间：2026.06.10

## 1、开发前准备

### 1.1、熟悉微信支付接口规则

正式进入开发前，开发者需要先阅读[基本规则](https://pay.weixin.qq.com/doc/brand/4015407525.md)、[如何签名和验签](https://pay.weixin.qq.com/doc/brand/4015407568.md)了解调用微信支付接口的基本规则和签名、验签规则。

### 1.2、准备开发参数

在发起接口请求时，开发者还需传入一些必要参数，如brand\_id(品牌ID)、品牌API证书私钥、公钥等，获取方式详见：[品牌商户模式开发必要参数说明](https://pay.weixin.qq.com/doc/brand/4015415289.md)。

注意事项：

1、开发联调阶段，调用接口后，建议在日志中保留应答的HTTP头 `Request-ID` 值， `Request-ID` 作为[请求的唯一标识](https://pay.weixin.qq.com/doc/brand/4015407525.md#%E8%AF%B7%E6%B1%82%E7%9A%84%E5%94%AF%E4%B8%80%E6%A0%87%E8%AF%86)，在调用接口遇到问题时，可向微信侧提供该值用于快速定位到请求记录，协助排查问题原因。

2、品牌API接入示例可参考[快速调通第一个品牌API](https://pay.weixin.qq.com/doc/brand/4016151253.md)

### 1.3、商品券Skills

微信支付商品券提供了配套的Skill，支持券类型选型、API代码示例、开发参数校验、接口报错排查和上线质量检查，详见：[商品券接入SKill](https://pay.weixin.qq.com/doc/brand/4018922755.md)。

## 2、业务基础概念

### 2.1、基础概念定义

| 概念 | 定义 | 关联关系 |
| --- | --- | --- |
| 品牌 | 所有券的归属主体，统一管理商品券、批次、回调地址。开发时通过 brand\_id 标识品牌，需配置 API 证书进行接口调用 | 1个品牌可创建多个商品券，统一配置1个回调通知地址 |
| 商品券 | 券的母版，定义券名称、使用规则、有效期类型等共性规则，统一管理所有批次（如"满100减20"的券模板） | 1个商品券可包含多个批次 |
| 商品券批次 | 基于商品券创建的发放单元，定义优惠规则、券码方式、发放预算、有效时间、可用门店等配置（如"双11限量1000张全国可用"、"新用户专享每人限领1张"） | 1个批次关联1个商品券，1个批次可发放多个用户商品券 |
| 用户商品券 | 用户商品券：用户领取后持有的实例券，包含券码、券状态、生效时间、核销状态等信息（如用户A领到的"满100减20"双11活动券） | 1个批次可发放多个用户商品券 |
| 门店 | 品牌的线下经营场所，包含门店名称、地址、经纬度、营业时间、服务电话等信息，可被批次关联用于限制券的使用范围 | 1个品牌可创建多个门店，1个批次可关联多个门店 |

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/96057139ad753048db211d461d8dddaf.svg)

### 2.2、券类型与应用场景

| 商户应用场景（示例） | 优惠模式<br>（usage\_mode） | 适用范围<br>（scope） | 券类型<br>（type） | 快速接入 |
| --- | --- | --- | --- | --- |
| 全场满x元x折 / 全场x折支持0门槛<br>新会员全场9折券：新用户注册即送全场9折券，首单使用，有效期7天 | 单券<br>（ `SINGLE`） | 全场商品可用券<br>（ `ALL`） | 折扣券<br>（ `DISCOUNT`） | [【单券-全场-折扣券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755503.md) |
| 全场满x减x / 全场立减x支持0门槛<br>双11满减券：全场满200减50，不限品类，活动期间每人限领1张<br>开业立减券：新店开业全场立减10元，无消费门槛，每人限领1张 | 单券<br>（ `SINGLE`） | 全场商品可用券<br>（ `ALL`） | 满减券<br>（ `NORMAL`） | [【单券-全场-满减券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755504.md) |
| 指定品类或品类组合满x元x折 / x折支持0门槛<br>新品尝鲜7折券：指定新品拿铁7折特惠，每人限购1杯，限量1000份 | 单券<br>（ `SINGLE`） | 部分商品可用券<br>（ `SINGLE`） | 折扣券<br>（ `DISCOUNT`） | [【单券-单品-折扣券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755505.md) |
| 指定品类或品类组合满x减x / 立减x支持0门槛<br>超值套餐立减券：汉堡+可乐套餐满30减5，搭配更划算<br>招牌奶茶立减券：招牌奶茶系列立减3元，无消费门槛，新客专享 | 单券<br>（ `SINGLE`） | 部分商品可用券<br>（ `SINGLE`） | 满减券<br>（ `NORMAL`） | [【单券-单品-满减券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755506.md) |
| 指定品类或品类组合兑换x支持0门槛<br>生日三选一兑换券：会员生日赠礼三选一，免费兑换 A.招牌奶茶 B.蛋糕 C.橙汁<br>新人礼包兑换券：新用户注册即送，免费兑换指定小蛋糕1份 | 单券<br>（ `SINGLE`） | 部分商品可用券<br>（ `SINGLE`） | 兑换券<br>（ `EXCHANGE`） | [【单券-单品-兑换券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755507.md) |

## 3、接入全流程

### 3.1、核心接入流程

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/93f651d6a0c269958996b452f338eb0f.svg)

#### 3.1.1、品牌入驻（非API）

品牌入驻是开启品牌经营的第一步，商家可访问微信支付品牌经营平台完成注册流程： [品牌入驻](https://pay.weixin.qq.com/doc/brand/4016389539.md)

注意：

1、注册时的扫码者将成为品牌管理员，拥有成员管理、所有功能的访问和编辑、设置API密钥等最高权限。

2、入驻时需提交管理员信息、主体信息、品牌基础信息及商标资料，管理员姓名和身份证信息需与扫码微信的实名一致。

3、若品牌名称或Logo已注册商标，需上传对应的商标注册证；若商标注册人与主体名称/法人不一致，还需额外提供商标使用许可授权书；若选择"无商标"，则不可使用已注册商标作为品牌名称和Logo。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 品牌经营平台 as 品牌经营平台

    rect rgb(255, 250, 240)
    Note over 品牌方,品牌经营平台: 一、品牌入驻

    Note right of 品牌经营平台: 入驻API暂未开放<br/>需在品牌经营平台页面注册

    品牌方->>品牌经营平台: 1. 管理员微信扫码，点击"我要注册品牌"
    Note right of 品牌方: 扫码者即为品牌管理员<br/>拥有最高权限

    品牌方->>品牌经营平台: 2. 填写管理员信息
    Note right of 品牌方: 姓名、身份证、手机号、邮箱<br/>需与微信实名信息一致

    品牌方->>品牌经营平台: 3. 填写品牌注册信息
    Note right of 品牌方: 品牌基础信息：<br/>主体类型、主体名称、统一社会信用代码<br/>品牌形象：<br/>品牌名称、品牌Logo<br/>商标认证：<br/>商标注册证、商标名称、注册号等

    alt 管理员是企业法人
        品牌方->>品牌经营平台: 4. 直接提交申请
    else 管理员非企业法人
        品牌方->>品牌经营平台: 4. 主体意愿确认
        Note right of 品牌方: 方式一：法人微信扫码确认<br/>方式二：企业公户打款验证
        品牌方->>品牌经营平台: 提交申请
    end

    品牌经营平台->>品牌经营平台: 审核(约3个工作日以内)
    品牌经营平台-->>品牌方: 审核通过，入驻成功

    品牌方->>品牌经营平台: 5. 微信扫码登录品牌经营平台

    品牌方->>品牌经营平台: 6. 成员管理
    Note right of 品牌方: 岗位管理：添加/修改/删除岗位<br/>成员管理：添加/修改/删除成员
    end
```

#### 3.1.2、创品牌门店（API，可选）

品牌门店是连接商家线下经营场景的基础数据，商家可通过API或品牌经营平台管理门店信息： [品牌经营平台管理品牌门店](https://pay.weixin.qq.com/doc/brand/4016689815.md)

注意：

1、商家完整录入真实线下门店信息后，在营销投放时可基于门店位置进行精准定位，提升领券转化率；同时在商家名片等场景向用户展示门店位置和经营信息。

2、创建门店后需经过平台审核，审核通过后门店状态变为"营业中"；若被驳回需根据原因修改信息后重新提交。

3、门店已生效后修改信息，门店营业状态不受影响，仅修改内容进入审核流程；审核驳回不会改变门店当前的营业状态。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 微信支付 as 微信支付<br/>商品券系统

    rect rgb(255, 250, 240)
    Note over 品牌方,微信支付: 二、创建品牌门店

    品牌方->>微信支付: 创建品牌门店
    微信支付-->>品牌方: 返回store_id<br/>门店状态=CREATING(创建中)<br/>审核状态=PROCESSING(审核中)

    Note over 微信支付: 平台审核(机审约1工作日，人审约7工作日)

    alt 审核通过
        微信支付-->>品牌方: 门店状态=OPEN(营业中)<br/>审核状态=SUCCESS(通过)
    else 审核驳回
        微信支付-->>品牌方: 审核状态=REJECTED(驳回)<br/>返回驳回原因
        品牌方->>微信支付: 调用「更新品牌门店」接口修改后重新提交
    end
    end
```

#### 3.1.3、创交易连接名片（非API，可选）

交易连接名片可通过品牌经营平台进行配置： [商家名片配置指引](https://pay.weixin.qq.com/doc/brand/4016401750.md)

注意：

1、配置交易连接前，需先完成商家名片的创建、基础信息及服务列表的配置，并通过审核发布。

2、配置交易连接后，用户支付成功时支付链路将展示品牌头像和名称，支付凭证点击后可跳转至商家名片页面。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 品牌经营平台 as 品牌经营平台

    rect rgb(255, 250, 240)
    Note over 品牌方,品牌经营平台: 三、交易连接名片

    Note right of 品牌经营平台: 交易连接名片API暂未开放<br/>需在品牌经营平台页面配置

    Note right of 品牌方: 前提条件：<br/>商家名片已完成配置并发布

    品牌方->>品牌经营平台: 进入「品牌经营平台-名片管理-交易连接名片」

    Note right of 品牌方: 根据实际业务场景配置以下一种或多种：

    品牌方->>品牌经营平台: **小程序支付**：勾选交易小程序AppID
    品牌方->>品牌经营平台: **APP支付**：勾选交易App
    品牌方->>品牌经营平台: **付款码支付**：勾选收款商户号（支持批量上传）
    品牌方->>品牌经营平台: **支付分**：输入支付分服务ID

    品牌经营平台-->>品牌方: 配置成功
    end
```

#### 3.1.4、创建商品券（API）

商户系统可以通过API管理商品券：包括 [创建商品券](https://pay.weixin.qq.com/doc/brand/4015736297.md)、 [修改商品券](https://pay.weixin.qq.com/doc/brand/4015736325.md)、 [查询商品券](https://pay.weixin.qq.com/doc/brand/4015736321.md)、 [失效商品券](https://pay.weixin.qq.com/doc/brand/4015736315.md) 的操作，创券示例代码可以参考： [【单券-全场-折扣券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755503.md)、 [【单券-全场-满减券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755504.md)、 [【单券-单品-折扣券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755505.md)、 [【单券-单品-满减券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755506.md)、 [【单券-单品-兑换券】API请求示例](https://pay.weixin.qq.com/doc/brand/4016755507.md)。

注意：

1、创建商品券的同时也会创建一个商品券批次，若需创建更多批次需另外调用「 [添加商品券批次](https://pay.weixin.qq.com/doc/brand/4015736342.md)」接口。

2、修改后的商品券信息只会对新发的券生效，历史已经发放给用户的券信息不会改变。

3、商品券失效时，商品券下所有批次都会失效。并且会同步终止该商品券所有投放渠道和活动，不会有新的用户领券事件，但历史已经通过该商品券对应的批次发放的用户券仍然有效。

4、图片必须通过「 [图片上传](https://pay.weixin.qq.com/doc/brand/4015736285.md)」接口获取URL，不支持外部链接。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 微信支付 as 微信支付<br/>商品券系统

    rect rgb(255, 250, 240)
    Note over 品牌方,微信支付: 四、创建商品券

    品牌方->>微信支付: 创建商品券

    Note left of 微信支付: 注意事项：<br/>━━━━━━━━━━━━━━━━━━━━<br/>1. 图片必须通过【图片上传API】获取URL<br/>   不支持外部链接<br/>━━━━━━━━━━━━━━━━━━━━<br/>2. AppID必须先通过"交易连接名片"<br/>   与品牌关联，否则报AppID非法<br/>━━━━━━━━━━━━━━━━━━━━<br/>3. 空值参数不允许传递<br/>   如空数组[]、空字符串""

    微信支付->>微信支付: 机审(耗时极短)
    微信支付-->>品牌方: 返回商品券ID、默认批次ID<br/>商品券状态=EFFECTIVE(生效中)

    opt 后续操作(可选)
        品牌方->>微信支付: 修改商品券(仅对新发放的券生效)
        品牌方->>微信支付: 查询商品券
        品牌方->>微信支付: 失效商品券<br/>(所有批次失效，已发放的用户券仍有效)
    end

    end
```

商品券状态流转图：

```mermaid
%%{init: {'themeVariables':{'edgeLabelBackground':'#ffffff'}}}%%
stateDiagram-v2
    direction LR
    state "审批中[1]" as S1
    state "生效中[2]" as S2
    state "已失效[3]" as S3

    [*] --> S1
    S1 --> S2: 审批通过
    S2 --> S3: 品牌方调用商品券失效接口
    S3 --> [*]
```

1、品牌方调用「 [创建商品券](https://pay.weixin.qq.com/doc/brand/4015736297.md)」接口创建成功后，商品券会流转为“审批中”(state：AUDITING)状态。

2、微信侧审批方式为机器审核，耗时极短，审批通过后商品券流转为“生效中”(state：EFFECTIVE)状态。

3、品牌方调用「 [失效商品券](https://pay.weixin.qq.com/doc/brand/4015736315.md)」接口后，商品券流转为“已失效”(state：DEACTIVATED)状态。

以下状态为终态：

- “已失效”(state：DEACTIVATED)


#### 3.1.5、创建商品券批次（API）

商户系统可以通过API管理商品券批次：包括 [添加商品券批次](https://pay.weixin.qq.com/doc/brand/4015736342.md)、 [修改商品券批次](https://pay.weixin.qq.com/doc/brand/4015736391.md)、 [查询商品券指定批次](https://pay.weixin.qq.com/doc/brand/4015736373.md)、 [失效商品券批次](https://pay.weixin.qq.com/doc/brand/4015736352.md)、 [批次关联门店](https://pay.weixin.qq.com/doc/brand/4015736339.md) 等的操作。

注意：

1、「 [修改商品券批次](https://pay.weixin.qq.com/doc/brand/4015736391.md)」接口仅能修改批次的基本信息，包括展示信息、通知配置，如需修改预算请调用「 [修改商品券批次发放预算](https://pay.weixin.qq.com/doc/brand/4015736398.md)」接口。修改后的商品券批次信息只会对新发的券生效，历史已经发放给用户的券信息不会改变。

2、「 [修改商品券批次发放预算](https://pay.weixin.qq.com/doc/brand/4015736398.md)」接口每次调用只能调整一个维度的投放预算，如果你需要调整多个维度的预算，请多次调用本接口。

3、「 [失效商品券批次](https://pay.weixin.qq.com/doc/brand/4015736352.md)」接口只会使单个商品券批次失效，不会影响到其他批次。失效后，该批次不会有新的用户领券事件，但历史已经通过该批次发放的用户券仍然有效。。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 微信支付 as 微信支付<br/>商品券系统

    rect rgb(255, 250, 240)
    Note over 品牌方,微信支付: 五、添加商品券批次

    Note right of 微信支付: 批次用于控制发放数量、时间、门店范围<br/>一个商品券可有多个批次

    Note right of 品牌方: 前置条件:<br/>商品券状态为EFFECTIVE(生效中)

    品牌方->>微信支付: 添加商品券批次
    微信支付-->>品牌方: 返回批次ID<br/>批次状态=AUDITING(审批中)
    微信支付->>微信支付: 机器审核(耗时极短)
    微信支付-->>品牌方: 批次状态=SENDING(发放中)

    opt 批次关联门店(store_scope=SPECIFIC时必须)
        品牌方->>微信支付: 批次关联门店
        品牌方->>微信支付: 批次取消关联门店
    end

    opt 批次后续操作(可选)
        Note right of 品牌方: 需批次状态为SENDING或PAUSED
        品牌方->>微信支付: 修改批次信息(仅对新发放的券生效)
        品牌方->>微信支付: 修改批次发放预算(每次只能调整一个维度)
        品牌方->>微信支付: 查询批次
        品牌方->>微信支付: 失效批次(不影响其他批次，已发放的用户券仍有效)
    end

    end
```

商品券批次状态流转图：

```mermaid
%%{init: {'themeVariables':{'edgeLabelBackground':'#ffffff'}}}%%
stateDiagram-v2
    direction LR
    state "审批中[1]" as S1
    state "发放中[2]" as S2
    state "已停止[3]" as S3
    state "已暂停[4]" as S4
    state "已失效[5]" as S5

    [*] --> S1
    S1 --> S2: 审批通过
    S2 --> S3: 批次过期
    S3 --> [*]
    S2 --> S4: 商品券暂停/商品券批次暂停
    S2 --> S5: 商品券作废/商品券批次作废
    S5 --> [*]
    S4 --> S2: 商品券恢复/商品券批次重启
```

1、品牌方调用「 [添加商品券批次](https://pay.weixin.qq.com/doc/brand/4015736342.md)」接口添加新批次到商品券后，批次会流转为“审批中”(state：AUDITING)状态。

2、微信侧审批方式为机器审核，耗时极短，审批通过后批次流转为“发放中”(state：SENDING)状态。

3、批次在发放中”(state：EFFECTIVE)状态时，以下操作会使商品券批次流转为不同的状态：

- 品牌方如果调用「 [失效商品券](https://pay.weixin.qq.com/doc/brand/4015736315.md)/ [失效商品券批次](https://pay.weixin.qq.com/doc/brand/4015736352.md)」接口，批次会流转为“已失效”(state：DEACTIVATED)状态；

- 批次过期后，批次会流转为“已停止”(state：STOPPED)状态；


以下两个状态为终态：

- “已停止”(state：STOPPED)

- “已失效”(state：DEACTIVATED)


#### 3.1.6、创活动（非API）

投放计划是"摇一摇有优惠"活动的创建工具，商家可通过品牌经营平台进行配置： [投放计划配置指引](https://pay.weixin.qq.com/doc/brand/4016080826.md)。

注意：

1、创建投放计划时需选择商品券及价格批次，价格批次库存需大于等于10000，且仅支持"线上小程序核销"或"微信支付付款码核销"方式。

2、投放计划创建后需经过审核，审核周期通常为2个工作日；审核中仅支持终止操作，驳回后可修改重新提交。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 品牌经营平台 as 品牌经营平台

    rect rgb(255, 250, 240)
    Note over 品牌方,品牌经营平台: 六、创建并测试投放计划

    Note right of 品牌经营平台: 投放计划API暂未开放<br/>需在品牌经营平台页面配置

    Note right of 品牌方: 校验项:<br/>批次库存≥10000<br/>投放时间≥5天<br/>投放结束时间早于批次结束时间

    品牌方->>品牌经营平台: 创建投放计划
    品牌经营平台-->>品牌方: 创建成功，进入审核流程

    品牌经营平台->>品牌经营平台: 审核(约2个工作日)
    品牌经营平台-->>品牌方: 审核通过→投放中<br/>审核驳回→返回驳回原因，修改后重新提交

    Note over 品牌方,品牌经营平台: 测试投放计划

    品牌方->>品牌经营平台: 进入「品牌优惠-投放计划-投放计划管理-体验设置」
    品牌方->>品牌经营平台: 配置体验人员微信号(最多10个)
    品牌方->>品牌经营平台: 点击预览按钮，获取体验二维码
    品牌方->>品牌方: 微信扫码预览活动效果

    Note right of 品牌方: 注意:<br/>预览活动仅供测试，实际曝光展示将由推荐算法决定
    end
```

#### 3.1.7、发券（API）

商户系统可以通过API管理用户的商品券：包括 [向用户发放商品券](https://pay.weixin.qq.com/doc/brand/4015736390.md)、 [查询用户商品券详情](https://pay.weixin.qq.com/doc/brand/4015736414.md)、 [退券](https://pay.weixin.qq.com/doc/brand/4015736429.md)、 [失效用户商品券](https://pay.weixin.qq.com/doc/brand/4015736411.md) 等的操作。

注意

1、调用发券接口前要确认已调用「 [设置商品券事件通知地址](https://pay.weixin.qq.com/doc/brand/4015736293.md)」接口。

2、商品券有多个发券渠道，可以由微信支付提供的营销渠道（摇一摇有优惠、商家名片等）发券，品牌方也可以调用「 [向用户发放商品券](https://pay.weixin.qq.com/doc/brand/4015736390.md)」接口主动发券，不论由何渠道发放，微信支付均会发送「 [商品券回调通知](https://pay.weixin.qq.com/doc/brand/4015755761.md)」给品牌方，品牌方需调用「 [确认发放用户商品券](https://pay.weixin.qq.com/doc/brand/4015736403.md)」接口确认发放成功，用户的券才会生效。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 微信支付 as 微信支付<br/>商品券系统

    rect rgb(255, 250, 240)
    Note over 品牌方,微信支付: 七、发券
    Note right of 品牌方: 前置条件:<br/>已调用「设置商品券事件通知地址」接口

    alt 方式一: 用户通过"摇一摇有优惠"领券
        Note right of 品牌方: 用户在微信内通过<br/>"摇一摇有优惠"领取商品券
        微信支付->>微信支付: 发放商品券<br/>用户券状态为「待确认」
        微信支付--)品牌方: 商品券回调通知(PRODUCT_COUPON.SEND)<br/>包含coupon_id、coupon_code
        品牌方->>品牌方: 商户内部给用户发券
        品牌方->>微信支付: 确认发放用户商品券
        微信支付-->>品牌方: 券状态=EFFECTIVE(已生效)<br/>或PENDING(待生效，未到可用时间)
    else 方式二: 预发券+小程序领券组件(用户主动领取)
        品牌方->>微信支付: 向用户预发放商品券
        微信支付-->>品牌方: 返回token(5分钟有效)
        Note right of 品牌方: 此时券尚未发放<br/>仅完成资格校验和预占库存
        品牌方->>品牌方: 小程序调用wx.openBusinessView<br/>传入token打开领券组件
        Note right of 品牌方: 用户在组件内看到券信息<br/>点击"立即领取"完成发券
        微信支付--)品牌方: 商品券回调通知(PRODUCT_COUPON.SEND)<br/>包含coupon_id、coupon_code
        Note right of 品牌方: 用户可点击"去使用"<br/>组件返回productPath跳转下单页
        品牌方->>微信支付: 确认发放用户商品券
        Note right of 品牌方: 必须调用 否则用户券无法使用<br/>建议在处理发券回调时同步完成
        微信支付-->>品牌方: 券状态=EFFECTIVE(已生效)<br/>或PENDING(待生效，未到可用时间)
    else 方式三: API直接发券(后台静默发券)
        品牌方->>微信支付: 向用户发放商品券
        微信支付-->>品牌方: 返回coupon_id、coupon_code<br/>券状态=CONFIRMING(待确认)
        Note right of 品牌方: 券直接进入用户卡包<br/>用户无需操作
        微信支付--)品牌方: 商品券回调通知(PRODUCT_COUPON.SEND)
        品牌方->>微信支付: 确认发放用户商品券
        Note right of 品牌方: 必须调用 否则用户券无法使用<br/>建议在处理发券回调时同步完成
        微信支付-->>品牌方: 券状态=EFFECTIVE(已生效)<br/>或PENDING(待生效，未到可用时间)
    end
    end
```

用户商品券状态流转图：

```mermaid
%%{init: {'themeVariables':{'edgeLabelBackground':'#ffffff'}}}%%
stateDiagram-v2
    direction LR
    state "待确认发券[1]" as S1
    state "待生效[2]" as S2
    state "已生效[3]" as S3
    state "已核销[4]" as S4
    state "已过期[5]" as S5
    state "已删除[6]" as S6
    state "已失效[7]" as S7

    [*] --> S1: 发券
    S1 --> S2: 已确认发券但尚未到达可用开始时间
    S1 --> S3: 已确认发券且到达可用开始时间
    S3 --> S4: 已核销
    S3 --> S5: 超过有效期
    S3 --> S6: 用户删除商品券
    S2 --> S3
    S4 --> S3: 退券
    S3 --> S7: 品牌方调用接口失效券
    S5 --> [*]
    S6 --> [*]
    S7 --> [*]
```

1、微信支付提供的营销渠道（摇一摇有优惠、商家名片等）向用户发券，品牌方也可以调用「 [向用户发放商品券](https://pay.weixin.qq.com/doc/brand/4015736390.md)」接口主动向用户发券，发券后微信会向品牌方发送「 [商品券回调通知](https://pay.weixin.qq.com/doc/brand/4015755761.md)」，此时用户商品券会流转为“待确认发券”(coupon\_state：CONFIRMING)的状态。

2、品牌方收到「 [商品券回调通知](https://pay.weixin.qq.com/doc/brand/4015755761.md)」后，需调用「 [确认发放用户商品券](https://pay.weixin.qq.com/doc/brand/4015736403.md)」接口确认发放成功，确认完成后：

- 若当前时间未到达用户商品券的可用开始时间，用户商品券会从“待确认发券”(coupon\_state：CONFIRMING)流转为“待生效”(coupon\_state：PENDING)的状态；

- 若当前时间到达用户商品券的可用开始时间，用户商品券会从“待确认发券”(coupon\_state：CONFIRMING)或“待生效”(coupon\_state：PENDING)流转为“已生效”(coupon\_state：EFFECTIVE)的状态。


3、用户商品券处于“已生效”(coupon\_state：EFFECTIVE)的状态时，以下操作会使用户商品券流转为不同的状态：

- 品牌方可调用「 [核销用户商品券](https://pay.weixin.qq.com/doc/brand/4015736433.md)」接口进行核销，此时用户商品券会流转为“已核销”(coupon\_state：USED)的状态；

- 用户商品券超过有效期未核销，用户商品券会流转为“已过期”(coupon\_state：EXPIRED)的状态；

- 用户商品券被用户在客户端主动删除后，用户商品券会流转为“已删除”(coupon\_state：DELETED)的状态；

- 品牌方如果调用「 [失效用户商品券](https://pay.weixin.qq.com/doc/brand/4015736411.md)」接口，用户商品券会流转为“已失效”(coupon\_state：DEACTIVATED)的状态。


4、用户商品券核销后，品牌方如果调用「 [退券](https://pay.weixin.qq.com/doc/brand/4015736429.md)」接口，此时用户商品券会从“已核销”(coupon\_state：USED)流转为“已生效”(coupon\_state：EFFECTIVE)的状态。

以下三个状态为终态：

- “已过期”(coupon\_state：EXPIRED)

- “已删除”(coupon\_state：DELETED)

- “已失效”(coupon\_state：DEACTIVATED)


#### 3.1.8、核销（API）

品牌方可通过API核销已发放给用户的商品券： [核销用户商品券](https://pay.weixin.qq.com/doc/brand/4015736433.md)。

注意

1、核销前需确保已成功给用户发券，且用户商品券当前状态为可用；已过期或不存在的券无法核销。

2、核销时需关联订单信息，支持关联微信支付订单（transaction\_id或out\_trade\_no）或微信支付分订单（order\_id或out\_order\_no），二选一。

```mermaid
sequenceDiagram
    participant 品牌方
    participant 微信支付 as 微信支付<br/>商品券系统

    rect rgb(255, 250, 240)
    Note over 品牌方,微信支付: 八、核销

    alt 方式一: API直接核销(品牌方主动发起)
        Note right of 品牌方: 适用: 线下扫码、后台系统核销
        品牌方->>微信支付: 核销用户商品券
        微信支付-->>品牌方: 券状态=USED(已核销)
    else 方式二: 小程序核销组件(用户主动发起)
        Note right of 品牌方: 适用: 摇一摇有优惠跳转小程序
        品牌方->>品牌方: 调用wx.openBusinessView拉起核销组件
        Note right of 品牌方: 用户在组件内选择商品并确认使用
        品牌方->>微信支付: 核销用户商品券
        微信支付-->>品牌方: 券状态=USED(已核销)
    end
    end
```

## 4、接口接入说明

### 4.1、必接接口

| API类型 | API名称 | 接口是否与多次优惠共用 | 描述 |
| --- | --- | --- | --- |
| 商品券管理 | 创建商品券 | 是 | 品牌方可以通过该接口创建商品券和批次。微信支付创建成功后，会返回此次创建的商品券以及批次。品牌方可在【经营平台】上配置【活动】对商品券进行投放。<br>频率限制：接口级限制1000/min<br>注意：由于该接口参数较多，故按“单券”和“多次优惠”模式的传参要求拆分成了两个文档，实际接口为同一个 |
| 商品券管理 | 修改商品券 | 是 | 品牌方可以通过该接口修改商品券信息。注：修改只会对新发的券生效，历史已经发放给用户的券不会改变。<br>前置条件：已创建商品券 |
| 商品券管理 | 失效商品券 | 是 | 品牌方可以通过该接口使某个商品券失效。<br>注意：<br>- 失效商品券会失效商品券所有批次。<br>  <br>- 失效商品券会同步终止该商品券所有投放渠道和活动，不会有新的用户领券事件，但历史已经通过该商品券对应的批次发放的用户券仍然有效。<br>  <br>前置条件：已创建商品券 |
| 商品券批次管理 | 添加商品券批次 | 否 | 品牌方可以通过该接口为已有的商品券添加更多批次，多个批次可以实现品牌方多样化的投放需求。<br>前置条件：已创建商品券 |
| 商品券批次管理 | 修改商品券批次 | 否 | 品牌方可以通过该接口修改商品券批次的基本信息，包括展示信息、通知配置。<br>如果你需要调整批次的投放预算，请使用【修改商品券批次发放预算API】<br>前置条件：已创建商品券批次 |
| 商品券批次管理 | 修改商品券批次发放预算 | 否 | 品牌方可以通过本接口修改商品券批次的投放预算。<br>注：本接口每次调用只能调整一个维度的投放预算，如果你需要调整多个维度的预算，请多次调用本接口。<br>前置条件：已创建商品券批次 |
| 商品券批次管理 | 失效商品券批次 | 否 | 品牌方可以通过该接口使已经创建的某个商品券批次失效。<br>注意：<br>- 调用本接口只会失效单个批次，商品券本身以及其他商品券批次不受影响。<br>  <br>- 失效商品券批次后，该批次不会有新的用户领券事件，但历史已经通过该批次发放的用户券仍然有效。<br>  <br>前置条件：已创建商品券批次 |
| 商品券批次管理 | 批次关联门店 | 否 | 品牌方可以通过该接口将品牌的门店列表与商品券批次关联<br>前置条件：已创建商品券批次且批次的 `store_scope` 为 `SPECIFIC` |
| 商品券批次管理 | 批次取消关联门店 | 否 | 品牌方可以通过该接口取消品牌的门店列表与商品券批次的关联关系<br>前置条件：已创建商品券批次且批次的 `store_scope` 为 `SPECIFIC` |
| 用户商品券管理 | 向用户发放商品券 | 否 | 品牌方可以通过本接口向用户发放指定商品券批次，能否发放受限于商品券批次的发放限额：<br>1. 商品券批次总预算<br>   <br>2. 商品券批次每日预算（如果有）<br>   <br>3. 商品券批次每人限领（如果有）<br>   <br>前置条件：已创建商品券批次，商品券批次处于 `SENDING` 状态 |
| 用户商品券管理 | 确认发放用户商品券 | 是 | 给用户发券后，微信支付会给品牌发送「商品券发放通知」，此时品牌应调用本接口确认发放成功。<br>注：商品券有多个发券渠道，可以由微信支付提供的营销渠道（摇一摇有优惠、商家名片等）发券，品牌方也可以调用商品券本身的发券API主动发券，不论由何渠道发放，微信支付均会发送该通知给品牌方，品牌方均需调用本接口确认发放成功。 |
| 用户商品券管理 | 核销用户商户券 | 是 | 品牌方可以通过本接口核销已经发放给用户的商品券<br>前置条件：已经给用户发券成功，且用户券当前可用 |
| 用户商品券管理 | 失效用户商品券 | 否 | 品牌方可以通过本接口将用户的商品券失效<br>前置条件：已经给用户发券成功 |
| 用户商品券管理 | 退券 | 是 | 品牌方可以通过本接口将已经核销用户的商品券退回给用户<br>前置条件：已经给用户发券成功，且用户券当前已核销 |
| 商品券回调通知配置 | 设置商品券事件通知地址 | 是 | 品牌方可以通过本接口设置商品券相关事件的回调地址，该地址配置为品牌维度配置，该品牌下的所有商品券相关事件均会通知到该地址。 |
| 商品券回调通知配置 | 获取商品券事件通知地址 | 是 | 品牌方可以通过本接口查询商品券相关事件的回调地址，该地址配置为品牌维度配置，该品牌下的所有商品券相关事件均会通知到该地址。<br>前置条件：品牌已经配置商品券事件通知地址 |
| 商品券回调通知配置 | 商品券回调通知 | 是 | 用户商品券发放成功后，微信支付会将相关领券结果与用户信息发送给品牌方，品牌方需要接收处理，在品牌侧内部系统为用户发放同样的券。品牌侧发券完成后，还需要调用【 [确认发放用户商品券](https://pay.weixin.qq.com/doc/brand/4015736403.md)】接口进行确认。<br>回调地址设置方式： 回调地址通过【 [设置商品券事件通知地址](https://pay.weixin.qq.com/doc/brand/4015736293.md)】接口中的 `notify_url` 参数设置，回调地址的设置规范请参考文档： [回调通知注意事项](https://pay.weixin.qq.com/doc/brand/4015407551.md)<br>注意：<br>- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。<br>  <br>- 商户系统对于开启结果通知的内容一定要做签名验证，并校验通知的信息是否与商户侧的信息一致，防止数据泄露导致出现“假通知”，造成资金损失。 |

### 4.2、选接接口

|     |     |     |     |
| --- | --- | --- | --- |
| 商品券管理 | 查询商品券 | 是 | 品牌方可以通过该接口查询商品券的详细信息，但不包括商品券的批次信息。如果要查询商品券的批次列表，请使用【查询商品券批次列表API】<br>前置条件：已创建商品券 |
| 商品券批次管理 | 查询商品券批次列表 | 是 | 品牌方可以通过该接口分页查询某个商品券的批次列表。<br>前置条件：已创建商品券 |
| 商品券批次管理 | 查询商品券指定批次 | 是 | 品牌方可以通过该接口查询某个商品券批次的详情。<br>前置条件：已创建商品券批次 |
| 商品券批次管理 | 查询批次关联门店列表 | 是 | 品牌方可以通过该接口分页查询商品券批次所关联的门店列表<br>前置条件：已创建商品券批次且批次的 `store_scope` 为 `SPECIFIC` |
| 商品券批次管理 | 预上传券CODE | 是 | 品牌方可以通过该接口为商品券批次预上传券Code<br>前置条件：已创建商品券批次，商品券批次的 `coupon_code_mode` 配置为 `UPLOAD` |
| 用户商品券管理 | 查询用户商品券详情 | 是 | 品牌方可以通过本接口查询已经发放给用户的商品券详情<br>前置条件：已经给用户发券成功 |
| 用户商品券管理 | 指定券状态查询用户商品券列表 | 是 | 品牌方可以通过本接口查询已经发放给用户的特定状态的商品券<br>前置条件：已经给用户发券成功 |

## 5、附录

### 5.1、 常见问题FAQ

高频疑问汇总（如 ：调用“创建商品券”接口报错：appid非法）请参考： [常见问题](https://pay.weixin.qq.com/doc/brand/4016950448.md)