商家券场景
=====

#### 场景介绍

商家券是华为支付为商户提供的电子优惠券解决方案，通过该产品实现商家优惠券创建、投放、领取、核销及券查询等管理操作，商家券优惠规则和玩法由商家自定义，商家可将自有营销体系的优惠券同步到华为流量场景（日日有礼、搜索、品牌专区、支付成功页等）和商家自有流量进行发放和运营。

有开发意愿的商户或者服务商可使用API接口完成商家券创建、发放、领取、核销、券查询等全链路操作。

支持商户模型：直连商户、平台类商户、服务商。

用户在华为钱包卡包可见的商家券样式（参考下图，商家自定义）。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a5/v3/4IzsoTX8R9mXuqGipgsBKg/zh-cn_image_0000002664208995.png?HW-CC-KV=V1&HW-CC-Date=20260709T132641Z&HW-CC-Expire=86400&HW-CC-Sign=D1F148E8CAE60597AD6A135C7A5867F8980421F0AFFA4F3F06AA23A55D07324A)

#### 接入前置条件

1.  商家有营销系统以及具备开发能力且存在应用/元服务。
    
2.  商家在华为支付完成[商户入网](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-merc-regist-apply)。
    

#### 业务模式

#### \[h2\]支持的券类型

可支持满减券、折扣券和换购券三种优惠类型的商家券。

| 类型 | 说明 |
| :-- | :-- |
| 满减券 | 满X元减X元（例如：满10元减5元券），商户可在券的使用说明字段里向用户说明，券的适用商品情况（例如：全场商品适用，特价商品除外或XX品牌商品适用）。 |
| 折扣券 | 满X元享受X折（例如：满10元享5折），商户可在券的使用说明字段里向用户说明，券的适用商品情况（例如：全场商品适用，特价商品除外或XX品牌商品适用），包装出全场折扣券或者指定单品折扣券。 |
| 换购券 | 满X元换商品（例如：原价10元打车券，特价5元），商户可以用换购券包装出免费兑换券或减至券。在券的使用说明字段里向用户说明，券的适用商品情况（例如：XX品牌商品适用，不适用于XX商品）。 |

#### \[h2\]支持的券码类型

商家券Code码可支持随机Code和商户自定义Code两类。其中，商户自定义Code支持导入Code模式和发放时指定Code模式。

| **模式** | 说明 |
| :-- | :-- |
| 随机Code | 商家无需提前预上传券Code，在调用商家券发放接口时由华为支付随机生成券Code分配给商家券。 |
| 导入Code | 商家需预先向华为支付上传券Code，当券在发放时，华为支付自动从已导入的Code中随机取值（不能指定），派发给用户。该模式更多适用在华为支付平台流量场景（例如：华为支付精选权益页）中投放的商家券。 |
| 指定Code | 商家无需提前预上传券Code，在调用商家券发放接口中填入需给用户派发的Code信息。该模式更多适用在商家自有流量场景（例如：应用/元服务）中投放商家券。 |

#### \[h2\]支持的发放渠道

当前商家券支持的发放渠道有商家自有流量场景、平台流量场景。

| **场景** | 说明 |
| :-- | :-- |
| 商家自有流量 | 支持在应用/元服务中派发商家券。 |
| 平台流量 | 
支持在日日有礼、搜索、品牌专区、支付成功页等场地中派发商家券。

**说明：** 对于品牌专区支持平台流量，需要开发者进行[配置](https://developer.huawei.com/consumer/cn/doc/service/intents-kit315-0000002505659156)。

 |

#### \[h2\]支持的核销方式

线上应用/元服务核销。用户领取商家券后可通过卡包点击去使用，跳转至商家应用/元服务。商家查询到用户已领取的所有商家券信息，再根据商家优惠规则进行使用判断，用户使用商家券并支付完成后，商家调用核销接口将用户钱包卡包里的商家券状态标为已核销。

#### \[h2\]券插入钱包卡包、临期消息通知

用户领取商家券后，券会自动插入钱包卡包。券过期前，用户会收到商家券即将过期通知。

#### 接入流程

| 步骤 | 说明 |
| :-- | :-- |
| [商户入网](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-merc-regist-apply) | 在准备开发前，开发者需要在华为支付商户平台入网。商户入网成功后，需要为[商户号绑定AppID](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-binding-appid-to-merc)。 |
| [准备证书](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-certificates-config) | 商户成功登录商户平台后，须在证书管理中上传商户证书，上传完商户证书后商户方可进行交易，证书必须与商户号相匹配且是有效的。 |
| 商家券接入 | 根据[开发步骤](#开发步骤)完成商家券接入。 |

#### 业务流程

#### \[h2\]华为随机Code发放场景

如果系统对商家券Code无特殊要求，则使用随机Code模式（HWPAY\_MODE），华为在代发商家券时，随机生成券码给用户发券，发券成功后会回调通知本次发券所使用的券码。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b9/v3/1i19o2DyTaqb0b7wNssaIg/zh-cn_image_0000002664329055.png?HW-CC-KV=V1&HW-CC-Date=20260709T132641Z&HW-CC-Expire=86400&HW-CC-Sign=1A0D8B40F93C737F1EE1F5204E7127735D52BC201B954C6360F9702D3DE2713E)

**券批次管理**

1.  商户服务端调Payment Kit服务端[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口创建批次。
    
2.  批次创建成功后，Payment Kit服务端返回批次号信息。
    
3.  如果商户服务端没有记录批次信息，需要调用[查询商家券批次详情](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-query)接口获取批次库存信息，用于构造修改批次预算接口请求体。
    
4.  Payment Kit服务端给商户返回批次详情信息。
    
5.  商户服务端调Payment Kit服务端[修改商家券批次预算](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upbudge)接口修改批次预算。
    
6.  Payment Kit服务端返回批次预算修改结果。
    

**券管理**

在商户没有券系统记录用户券列表的情况下，交互流程如下：

1.  用户在华为流量场景领券。
    
2.  华为流量场景调Payment Kit服务端接口给用户发券。
    
3.  Payment Kit服务端通过批次上设置的回调地址给商户服务端发送[发券事件回调通知](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-callback-distribute)。
    
4.  用户在华为流量场景点击“去使用”。
    
5.  用户点击“去使用”后，引导用户跳转到商户服务端使用券。
    
6.  商户服务端调Payment Kit服务端[查询用户优惠券列表](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-query)查询用户优惠券列表。
    
7.  Payment Kit服务端返回优惠券列表。
    
8.  用户在商户服务端选择优惠券并下单后，商户服务端调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。
    
9.  Payment Kit服务端券核销成功后，把核销结果返回给商户服务端。
    
10.  用户在商户服务端上进行退单。
     
11.  商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券。
     
12.  Payment Kit服务端退券处理完后，把退券结果返回给商户服务端。
     

在商户服务端记录用户券列表的情况下，交互流程如下：

1.  用户在华为流量场景领券。
    
2.  华为流量场景调Payment Kit服务端接口给用户发券。
    
3.  Payment Kit服务端通过批次上设置的回调地址给商户服务端发送[发券事件回调通知](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-callback-distribute)。
    
4.  商户服务端将发出去的券码与自有系统券码做映射。
    
5.  用户在华为流量场景点击“去使用”。
    
6.  用户点击“去使用”后，引导用户跳转到商户服务端使用券。
    
7.  商户服务端在下单成功后，调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。
    
8.  Payment Kit服务端券状态刷新后，把核销结果返回给商户服务端。
    
9.  用户在商户服务端上进行退单。
    
10.  商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券。
     
11.  Payment Kit服务端退券处理完后，把退券结果返回给商户服务端。
     

#### \[h2\]华为导入Code发放场景

如果华为商家券系统中对商家券Code有特殊要求，希望华为流量场景代发券时使用自有券码，则在创建券批次时选用MERCHANT\_UPLOAD模式，并把自有券码通过[上传券预存Code](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upload)接口同步到华为商家券系统。华为商家券系统在代发商家券时，随机选取已上传的券码给用户发券，发券成功后会回调通知本次发放所使用的券码。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cc/v3/KogfiCDIRP6cniNH_prawA/zh-cn_image_0000002633849944.png?HW-CC-KV=V1&HW-CC-Date=20260709T132641Z&HW-CC-Expire=86400&HW-CC-Sign=5B15436C43EE7D2DFDCDE6B64AB7A6356076FCDE7374173E3C022B8F83F7DB62)

**券批次管理**

1.  商户服务端调Payment Kit服务端[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口创建批次。
    
2.  批次创建成功后，Payment Kit服务端返回批次号信息。
    
3.  商户服务端调Payment Kit服务端[上传券预存Code](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upload)接口上传Code。
    
4.  Payment Kit服务端返回预存Code结果。
    
5.  如果商户服务端没有记录批次信息，需要调用[查询商家券批次详情](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-query)接口获取批次库存信息，用于构造修改批次预算接口请求体。
    
6.  Payment Kit服务端给商户返回批次详情信息。
    
7.  商户服务端调Payment Kit服务端[修改商家券批次预算](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upbudge)接口修改批次预算。
    
8.  Payment Kit服务端返回批次预算修改结果。
    

**券管理**

1.  用户在华为流量场景领券。
    
2.  华为流量场景调Payment Kit服务端接口给用户发券。
    
3.  Payment Kit服务端通过[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口设置的回调地址给商户服务端发送[发券事件回调通知](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-callback-distribute)。
    
4.  用户在华为流量场景点击“去使用”。
    
5.  用户点击“去使用”后，引导用户跳转到商户服务端使用券。
    
6.  商户服务端在下单成功后，调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。
    
7.  Payment Kit服务端券状态刷新后，把核销结果返回给商户服务端。
    
8.  用户在商户服务端上进行退单。
    
9.  商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券。
    
10.  Payment Kit服务端退券处理完后，把退券结果返回给商户服务端。
     

#### \[h2\]商户指定Code发放场景

如果系统对商家券Code有特殊要求，仅希望在华为流量场景中展示用户在自有应用中领取到的券，则使用商户平台发券和指定券Code（MERCHANT\_API）模式，在调用“发放优惠券”接口时，把券码同步到华为商家券系统。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ad/v3/E90bEX8NTuyb33wBMF3eIg/zh-cn_image_0000002634009848.png?HW-CC-KV=V1&HW-CC-Date=20260709T132641Z&HW-CC-Expire=86400&HW-CC-Sign=4DB5966BE31E87EB5C59563240C0B38CBE300A742ACF6DC883F98A1BC714E6AB)

**券批次管理**

1.  商户服务端调Payment Kit服务端[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口创建批次。
    
2.  批次创建成功后，Payment Kit服务端返回批次号信息。
    
3.  如果商户服务端没有记录批次信息，需要调用[查询商家券批次详情](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-query)接口获取批次库存信息，用于构造修改批次预算接口请求体。
    
4.  Payment Kit服务端给商户返回批次详情信息。
    
5.  商户服务端调Payment Kit服务端[修改商家券批次预算](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upbudge)接口修改批次预算。
    
6.  Payment Kit服务端返回批次预算修改结果。
    

**券管理**

1.  用户在商户服务端商户平台领券。
    
2.  商户服务端调Payment Kit服务端[发放优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-distribute)接口给用户发券。
    
3.  Payment Kit服务端处理完后响应商户平台发券结果。
    
4.  用户在华为流量场景点击“去使用”。
    
5.  用户点击“去使用”后，引导用户跳转到商户服务端使用券。
    
6.  商户服务端在下单成功后，调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。
    
7.  Payment Kit服务端券状态刷新后，把核销结果返回给商户服务端。
    
8.  用户在商户服务端上进行退单。
    
9.  商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券。
    
10.  Payment Kit服务端退券处理完后，把退券结果返回给商户服务端。
     

#### 开发步骤

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5a/v3/87z8xc9oRMixEKYz8T-lQA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132641Z&HW-CC-Expire=86400&HW-CC-Sign=123FDCF221AAA1B97C60ABA51B89AB8D9E99F22CE15F2BEE06CEAAFF4170B0E8)

*   以下开发步骤仅涉及服务端开发，业务接口请求示例代码可参考[业务接口请求](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-server-connect#业务接口请求)。
    
*   [发券事件回调通知](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-callback-distribute)回调地址是开发者调用[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口时通过notifyConfig字段设置的回调地址，接收到回调通知后商户服务端可先对返回的支付信息进行[SM2验签](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-rest-overview#验签规则)处理。
    

#### \[h2\]华为随机Code发放场景

**券批次管理（服务端开发）**

开发者调用[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口创建券批次。成功后调用[修改商家券批次预算](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upbudge)接口修改批次预算。

**券管理（服务端开发）**

1.  华为流量场景调Payment Kit服务端接口给用户发券后（使用随机Code模式，随机生成券码给用户发券），会给商户服务端发送发券事件回调，回调详细信息请参见[发券事件回调通知](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-callback-distribute)（商户服务端将发出去的券码与自有系统券码做映射）。
    
2.  商户服务端调Payment Kit服务端[查询用户优惠券列表](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-query)查询用户优惠券列表，用户在商户服务端选择优惠券并下单后，调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。如果用户在商户服务端上进行退单，商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券，把退券结果返回给商户服务端。
    

#### \[h2\]华为导入Code发放场景

**券批次管理（服务端开发）**

开发者调用[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口创建券批次。创建券批次成功后调用[上传券预存Code](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upload)接口上传Code，券code上传成功后调用[修改商家券批次预算](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upbudge)接口修改批次预算。

**券管理（服务端开发）**

1.  华为流量场景给用户发券后会给商户服务端发送发券事件回调，回调详细信息请参见[发券事件回调通知](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-callback-distribute)。
    
2.  商户服务端在下单成功后，调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。用户如果在商户服务端上进行退单，商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券，把退券结果返回给商户服务端。
    

#### \[h2\]商户指定Code发放场景

**券批次管理（服务端开发）**

开发者调用[创建商家券批次](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-create)接口创建券批次，成功后调用[修改商家券批次预算](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-upbudge)接口修改批次预算。

**券管理（服务端开发）**

1.  商户服务端调Payment Kit服务端[发放优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-distribute)接口给用户发券（使用指定Code模式，在调用接口时把券码同步到华为商家券系统），Payment Kit服务端处理完后响应商户平台发券结果。
    
2.  商户服务端在下单成功后，调用[核销优惠券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-use)接口核销券，把券状态同步给Payment Kit服务端。用户如果在商户服务端上进行退单，商户服务端退单过程中调用华为支付[申请退券](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-refund)接口退券，把退券结果返回给商户服务端。
    

#### 测试和上线

1.  开发者收集好测试人员华为账号对应的手机号。
    
2.  [联系华为运营人员](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/payment-service-support)添加允许清单手机号进行测试并提供测试结果录屏，录屏内容包括商家券领取、展示以及核销完整流程。
    
3.  华为运营人员审核测试录屏，无问题后配置全网上线。
    

#### 延伸和拓展

当开发者完成上述能力之后，可以调用以下API接口完成其他相关操作。

[修改商家券批次基本信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-update)、[使券失效](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-deactivate)、[查询用户单张优惠券详情](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-ucoup-query-one)、[设置回调通知地址](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-callbackurl-update)、[查询回调通知地址](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/payment-api-common-promotion-service-merc-coup-coupbatch-callbackurl-select)