开发指引
更新时间:2025.08.181、开发前准备
1.1、熟悉微信支付接口规则
1.2、准备开发参数
在发起接口请求时,开发者还需传入一些必要参数,如brand_id(品牌ID)、品牌API证书私钥、公钥等,获取方式详见:品牌商户模式开发必要参数说明。
2、整体业务开发流程概览
商家名片会员是商家名片的功能之一,在接入前需先申请开通商家名片功能,开通后即可创建会员卡模版。
创建会员卡模版后,可引导新用户入会或对存量会员信息进行导入,具体方式可参考下方概览图中的「用户入会」流程。
用户入会成功后,即可查询、修改、作废用户会员卡。
用户入会成功后,可在商家名片会员卡同步并展示用户会员动态信息,具体方式可参考下方概览图中的「会员卡动态信息同步」流程:
3、详细步骤说明
3.1、管理会员卡模版
时序图中绿色步骤可参考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文档中对应的接口。
|
3.2.4、【存量会员】通过下单同步入会
商家可通过在微信支付下单接口的attach字段传入会员卡code( user_card_code
)来导入未开通会员的用户。下单用户若此前未开通会员卡,通过此方式可实时添加会员并自动生效一张会员卡,详细指引请参考:实时动态传入的方式
时序图中绿色步骤可参考API文档中对应的接口。
|
3.3、管理用户会员卡
商户系统可以通过API管理用户会员卡:包括查询列表、查询详情、修改、作废等操作。
时序图中绿色步骤可参考API文档中对应的接口。
3.4、会员动态信息同步
a、商户系统可通过下单同步用户实时动态能力导入会员卡实时动态信息。
b、商户系统可通过API导入会员卡异步动态信息。
时序图中绿色步骤可参考API文档中对应的接口。
|
3.5、用户会员卡状态流转图
以下2个状态为终态:
已过期
已失效
4、接口接入说明
类型 | 接口名 | 接口说明 |
必须接入 | 创建会员卡模板 | 通过调用「创建会员卡模板」接口可以创建一张会员卡模板,创建成功将获得会员卡模板ID。 |
会员卡事件通知 | 当用户的会员卡发生变化时,微信支付商家名片会把相关事件结果和用户信息发送给商户。 | |
同步会员开通结果 | 用户通过入会组件和商家名片开卡后,微信支付会回调通知给商家,且商家必须调用「同步会员开通结果」接口把开卡结果同步给微信支付侧才算开卡成功(注意:通过API导入和下单同步等方式无需同步开卡结果)。在同步开卡结果时商家可修改部分会员卡信息。 | |
按需接入 | 入会组件预授权 | 通过调用「入会组件预授权」接口可以生成用于商家小程序或 H5 拉起入会组件的品牌预授权凭证。 |
H5/小程序拉起品牌会员入会组件 | 商户可基于自身需求选择H5(公众号端)或小程序的方式引导用户完成入会流程
| |
查询会员卡模板列表 | 通过调用「查询会员卡模板列表」接口可查询指定某品牌的所有会员卡模板列表。 | |
查询会员卡模板信息 | 通过调用「查询会员卡模板信息」接口可查询指定会员卡模板的所有信息。 | |
修改会员卡模板信息 | 通过调用「修改会员卡模板信息」接口可更新会员卡的信息,包括基本信息、储值信息、开卡信息等 | |
作废会员卡模板 | 通过调用「作废会员卡模板」接口可作废会员卡模板。作废后,商家将无法通过任何渠道再投放该会员卡。 | |
查询用户会员卡信息 | 通过调用「查询用户会员卡信息」接口可查询指定用户会员卡的信息,如会员积分、储值余额、开卡信息等。 | |
查询用户在品牌下所有会员卡 | 通过调用「查询用户在品牌下所有会员卡」接口可查询用户在当前品牌下领取的会员卡列表。 | |
修改用户会员卡信息 | 通过调用「修改用户会员卡信息」接口可更新指定用户的会员卡背景图、会员卡号、等级等信息。 | |
作废用户会员卡 | 通过调用「作废用户会员卡」接口可将用户的会员卡设置为作废状态。
| |
根据OPENID导入用户会员卡 | 对于经营会员生意的商家来说,存量会员的注册渠道广泛,包括但不限于线下渠道、微信渠道、App及其他线上渠道。因而,在商家名片经营会员时会遇到两类问题: 用户OpenID对应的AppID,需要和会员卡所属的品牌号绑定。 | |
创建用户动态信息 | 通过调用「创建用户动态信息」接口可同步非微信支付渠道的会员动态信息到微信支付商家名片会员。 | |
图片上传 | 通过调用「图片上传」接口上传图片后可获得图片URL地址。图片URL可在微信支付商家名片会员相关的API使用,包括会员卡模板、用户会员卡等。 |