开发指引
更新时间：2025.04.231、开发前配置
开发前，开发者需要完成如下两个步骤：配置开发参数和配置产品功能。
1.1、设置安全联系人
微信支付日常安全监测发现技术异常时，会向安全联系人和超级管理员发送风险提醒。请商户超级管理员尽快设置技术同事为安全联系人，确保能及时接收异常信息评估业务风险，详见安全联系人设置指引。
1.2、熟悉微信支付接口规则
1.3、准备开发参数
在发起接口请求时，开发者需传入必要参数，如商户号、appid、密钥及证书序列号等，获取方式详见：普通商户模式开发必要参数说明。
使用品牌红包还需要如下参数：
参数 | 用途和获取说明 |
|---|---|
brand_id | 品牌ID是品牌在微信支付进行品牌认证后的唯一标识。获取方式见无门店品牌使用指引。 |
template_id | 品牌主配置的品牌红包模板ID，用于指定红包触达用户的展示模板；获取路径：登录商户平台→品牌红包→模板配置。 |
1.4、配置产品功能
在发放品牌红包前，必须设置请求来源IP 。仅设定IP可调用品牌商户发放红包API，具体可详见：设置接口安全IP
2、详细开发指引
2.1、整体业务开发流程概览
商户系统调用品牌商户发放红包API发起品牌红包发放，单次发放可以指定多个用户。
2.2、详细开发步骤说明
2.2.1、商户发放品牌红包
商户批量发放品牌红包给指定用户，商户系统调用品牌商户发放红包API发起品牌红包批次发放请求，微信支付受理后返回受理结果，此时不代表发放成功。
商户每次发放需要创建一个批次单和1至10个明细单，批次单记录商户号，品牌号，appid等品牌和商户相关信息。明细单记录接收用户openid，姓名等用户信息
|
2.2.2、商户查询品牌红包发放批次
微信支付受理商户的品牌红包发放请求成功后，将在1小时内完成批量付款。商户应当间隔1分钟以上调用商家批次单号查询批次单API或微信支付批次单号查询批次单API以跟踪品牌红包批次发放状态。
|
2.2.3、商户查询品牌红包发放明细
品牌红包发放完成后，批次单状态为“FINISHED”，商户才可调用商家明细单号查询明细单API或微信支付明细单号查询明细单API确认明细单状态，根据明细单状态确认明细红包的发放结果。如果发放失败，可根据对应的失败原因进行处理。
|
2.3、批次单状态流转图
1、从品牌红包批次单创建开始计算，24小时内商户未进行付款确认或者商户余额不足系统会自动关单。若品牌红包未发放完成，商户应查询批次单状态确认已关单，否则请勿换单重试。
2、以下两种状态为终态
FINISHED：品牌红包批次处理完成
CLOSE：品牌红包批次关闭
2.4、明细单状态流转图
1、用户收款账户异常会导致发放失败，应当引导用户确认收款账户。
2、以下两种状态为终态
DETAIL_SUCCESS：发放成功
DETAIL_FAIL：已失败
