开发指引

更新时间:2025.08.18

1、开发前准备

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

正式进入开发前,开发者需要先阅读基本规则如何签名和验签了解调用微信支付接口的基本规则和签名、验签规则。

1.2、准备开发参数

在发起接口请求时,开发者还需传入一些必要参数,如brand_id(品牌ID)、品牌API证书私钥、公钥等,获取方式详见:品牌商户模式开发必要参数说明

 

2、整体业务开发流程概览

  • 商家名片会员是商家名片的功能之一,在接入前需先申请开通商家名片功能,开通后即可创建会员卡模版。

  • 创建会员卡模版后,可引导新用户入会对存量会员信息进行导入,具体方式可参考下方概览图中的「用户入会」流程。

  • 用户入会成功后,即可查询、修改、作废用户会员卡。

  • 用户入会成功后,可在商家名片会员卡同步并展示用户会员动态信息,具体方式可参考下方概览图中的「会员卡动态信息同步」流程:

 

3、详细步骤说明

3.1、管理会员卡模版

商户系统可以通过API管理会员卡模板:包括创建查询列表查询详情修改作废等操作。

时序图中绿色步骤可参考API文档中对应的接口。

 

3.2、用户入会

3.2.1、【新用户】通过商家小程序/H5入会

用户可通过小程序或H5页面进入微信支付提供的开卡组件发起入会流程,核心流程如下:

时序图中绿色步骤可参考API文档中对应的接口。

 

 

 

3.2.2、【新用户】通过商家名片入会

商户通过创建会员卡模板接口创建的会员卡模块如符合条件(卡模板状态为生效、valid_date_information在有效期内且该用户未参与过入会)在商家名片会展示入会入口。商家可以通过need_pinned参数置顶某张卡模板。用户通过微信支付的商家名片发起入会流程时核心流程如下:

时序图中绿色步骤可参考API文档中对应的接口。

3.2.2.1 普通会员卡

注意:

普通会员,需完成 “ 会员开通” 闭环。用户在商家名片完成开通,然后由微信支付通知商户系统开通结果,最后由商户系统同步微信支付开通结果后才能结束流程。

  

3.2.2.2 付费会员卡(暂未上线)

注意:

  • 付费会员,需完成 “支付 + 会员开通” 闭环。用户在商家小程序完成支付和会员开通,然后由商户系统同步微信支付开通结果后才能结束流程。

  • 付费会员,该功能暂未上线。

 

3.2.3、【存量会员】通过API导入

针对存量会员,商家可通过用户的OpenID或手机号,将存量会员通过API导入至微信支付的商家名片,核心流程如下:

时序图中绿色步骤可参考API文档中对应的接口。

注意:

  • 通过API导入用户会员卡时,必须传入会员卡code字段(user_card_code)。

  • 根据手机号导入用户会员卡,该功能暂未上线。

 

3.2.4、【存量会员】通过下单同步入会

商家可通过在微信支付下单接口的attach字段传入会员卡code( user_card_code)来导入未开通会员的用户。下单用户若此前未开通会员卡,通过此方式可实时添加会员并自动生效一张会员卡,详细指引请参考:实时动态传入的方式

时序图中绿色步骤可参考API文档中对应的接口。

注意:

通过下单同步入会时,必须传入会员卡code字段(user_card_code)。

 

 

3.3、管理用户会员卡

商户系统可以通过API管理用户会员卡:包括查询列表、查询详情、修改、作废等操作。

时序图中绿色步骤可参考API文档中对应的接口。

 

3.4、会员动态信息同步

a、商户系统可通过下单同步用户实时动态能力导入会员卡实时动态信息。

b、商户系统可通过API导入会员卡异步动态信息。

时序图中绿色步骤可参考API文档中对应的接口。

注意:

该API用于记录在非微信支付渠道订单产生的会员动态信息。

 

3.5、用户会员卡状态流转图

 

以下2个状态为终态:

  • 已过期

  • 已失效

4、接口接入说明

类型

接口名

接口说明

必须接入

创建会员卡模板

通过调用创建会员卡模板接口可以创建一张会员卡模板,创建成功将获得会员卡模板ID。

会员卡事件通知

当用户的会员卡发生变化时,微信支付商家名片会把相关事件结果和用户信息发送给商户

同步会员开通结果

用户通过入会组件和商家名片开卡后,微信支付会回调通知给商家,且商家必须调用「同步会员开通结果」接口把开卡结果同步给微信支付侧才算开卡成功(注意:通过API导入和下单同步等方式无需同步开卡结果)。在同步开卡结果时商家可修改部分会员卡信息。

按需接入

入会组件预授权

通过调用「入会组件预授权」接口可以生成用于商家小程序或 H5 拉起入会组件的品牌预授权凭证。

H5/小程序拉起品牌会员入会组件

商户可基于自身需求选择H5(公众号端)小程序的方式引导用户完成入会流程

查询会员卡模板列表

通过调用「查询会员卡模板列表」接口可查询指定某品牌的所有会员卡模板列表。

查询会员卡模板信息

通过调用「查询会员卡模板信息」接口可查询指定会员卡模板的所有信息。

修改会员卡模板信息

通过调用「修改会员卡模板信息」接口可更新会员卡的信息,包括基本信息、储值信息、开卡信息等

作废会员卡模板

通过调用「作废会员卡模板」接口可作废会员卡模板。作废后,商家将无法通过任何渠道再投放该会员卡。

查询用户会员卡信息

通过调用「查询用户会员卡信息」接口可查询指定用户会员卡的信息,如会员积分、储值余额、开卡信息等。

查询用户在品牌下所有会员卡

通过调用「查询用户在品牌下所有会员卡」接口可查询用户在当前品牌下领取的会员卡列表。

修改用户会员卡信息

通过调用「修改用户会员卡信息」接口可更新指定用户的会员卡背景图、会员卡号、等级等信息。

作废用户会员卡

通过调用「作废用户会员卡」接口可将用户的会员卡设置为作废状态。

注意:

  • 设置卡券作废的操作不可逆,即无法将设置为作废的卡调回有效状态,商家须慎重调用该接口。

  • 商家调用作废接口前须与顾客事先告知并取得同意,否则因此带来的顾客投诉,微信将会按照《微信运营处罚规则》进行处罚。

根据OPENID导入用户会员卡

对于经营会员生意的商家来说,存量会员的注册渠道广泛,包括但不限于线下渠道、微信渠道、App及其他线上渠道。因而,在商家名片经营会员时会遇到两类问题:
(1)存量会员的身份难统一识别;
(2)在应用入会活动能力时,容易对存量(但未同步身份至商家名片侧的)老会员重复补贴。
因而,针对存量会员,商家可通过用户在微信公众号/小程序内的OpenID,调用「根据OPENID导入用户会员卡」接口将存量会员通过接口导入至商家名片。

注意:

用户OpenID对应的AppID,需要和会员卡所属的品牌号绑定。

创建用户动态信息

通过调用「创建用户动态信息」接口可同步非微信支付渠道的会员动态信息到微信支付商家名片会员。

图片上传

通过调用图片上传接口上传图片后可获得图片URL地址。图片URL可在微信支付商家名片会员相关的API使用,包括会员卡模板、用户会员卡等。