(接上)

# 8 管理会员卡

# 8.1 拉取会员信息(积分查询)接口

接口说明

支持开发者根据card_id和Code查询会员信息,包括激活资料、积分信息以及余额等信息。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=TOKEN

参数说明

参数 是否必须 说明
POST数据 JSON数据
access_token 调用接口凭证

POST数据

{
   "card_id": "pbLatjtZ7v1BG_ZnTjbW85GYc_E8",
   "code": "916679873278" 
}

参数名 是否必填 说明
cardid 查询会员卡的cardid
code 所查询用户领取到的code值

返回数据

{
    "errcode": 0,
    "errmsg": "ok",
    "openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
    "nickname": "Fourier",
    "membership_number": "316510891298",
    "bonus": 460,
    "sex": "MALE",
    "user_info": {
        "common_field_list": [
            {
                "name": "USER_FORM_INFO_FLAG_MOBILE",
                "value": "15521328888"
            },
            {
                "name": "USER_FORM_INFO_FLAG_NAME",
                "value": "微信"
            }
        ],
        "custom_field_list": []
    },
    "user_card_status": "NORMAL"
}

参数名 说明
errcode 错误码,0为正常
errmsg 错误信息
openid 用户在本公众号内唯一识别码
nickname 用户昵称
bonus 积分信息
balance 余额信息
sex 用户性别
user_info 会员信息
custom_field_list 开发者设置的会员卡会员信息类目,如等级。
name 会员信息类目名称
value 会员卡信息类目值,比如等级值等
user_card_status 当前用户会员卡状态,NORMAL 正常 EXPIRE 已过期 GIFTING 转赠中 GIFT_SUCC 转赠成功 GIFT_TIMEOUT 转赠超时 DELETE 已删除,UNAVAILABLE 已失效

# 8.2 更改会员卡信息接口

接口说明

支持更改会员卡卡面信息以及卡券属性信息。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/update?access_token=TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{
    "card_id": "ph_gmt7cUVrlRk8swPwx7aDyF-pg",
    "member_card": {
        "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
        "base_info": {
            "logo_url": "http:\/\/mmbiz.qpic.cn\/uploads\/allimg\/120216\/1_120216214725_1.jpg",
            "color": "Color010",
            "notice": "使用时向服务员出示此券",
            "service_phone": "020-88888888",
            "description": "不可与其他优惠同享\n如需团购券发票,请在消费时向商户提出\n店内均可使用,仅限堂食\n餐前不可打包,餐后未吃完,可打包\n本团购券不限人数,建议2人使用,超过建议人数须另收酱料费5元/位\n本单谢绝自带酒水饮料",
            "location_id_list": [
                123,
                12321,
                345345
            ]
        },
        "bonus_cleared": "aaaaaaaaaaaaaa",
        "bonus_rules": "aaaaaaaaaaaaaa",
        "prerogative": "",
        "auto_activate": true,
        //也可以填写wx_activate"activate_url":""
    }
}

支持修改字段:

base_info字段:

参数名 是否提审 类型 示例值 描述
title string(27) 微信会员卡 会员卡标题,字数上限为9个汉字
logo_url string(128) http://mmbiz .qpic.cn/ 卡券的商户logo,建议像素为300*300。
notice string(48) 请出示二维 码核销卡券。 使用提醒,字数上限为16个汉字。
description string(3072) 不可与其 他优惠同享 使用说明。
service_phone string(24) 40012234 客服电话。
color string(3072) Color010 卡券颜色。
location_id_list string(3072) 1234,2314 支持更新适用门店列表。
use_all_locations bool true 支持全部门店,填入后卡券门店跟随商户门店更新而更新
center_title string(18) 立即使用 会员卡中部的跳转按钮名称 ,建议用作使用用途
center_sub_title string(24) 到店后使用 会员卡中部按钮解释wording
center_url string(128) www.qq.com 会员卡中部按钮对应跳转的url
custom_url_name string(16) 立即使用 自定义跳转入口的名字。
custom_url string(128) www.qq.com 自定义跳转的URL。
custom_url_sub_title string(18) 更多惊喜 显示在入口右侧的提示语。
promotion_url_name string(16) 产品介绍。 营销场景的自定义入口名称。
promotion_url string(128) www.qq.com; 入口跳转外链的地址链接。
promotion_url_sub_title string(18) 卖场大优惠。 显示在营销入口右侧的提示语。
code_type string(16) CODE_TYPE _TEXT。 Code码展示类型, "CODE_TYPE_TEXT" 文本 "CODE_TYPE_BARCODE"一维码 "CODE_TYPE_QRCODE 二维码 "CODE_TYPE_ONLY_QRCODE" 仅显示二维码 "CODE_TYPE_ONLY_BARCODE" 仅显示一维码 "CODE_TYPE_NONE" 不显示任何码型
pay_info string(128) -- 支付功能结构体,swipe_card结构
swipe_card string(128) -- 刷卡功能结构体,包含is_swipe_card字段
is_swipe_card bool true 是否设置该会员卡支持拉出微信支付刷卡界面
is_pay_and_qrcode bool true 是否设置该会员卡中部的按钮同时支持微信支付刷卡和会员卡二维码
get_limit int 1 每人可领券的数量限制
can_share bool false 卡券原生领取页面是否可分享
can_give_friend bool false 卡券是否可转赠
date_info Json结构 见上述示例 使用日期,有效期的信息,有效期时间修改仅支持有效区间的扩大
type int 1 有效期类型,仅支持更改type为1的时间戳,不支持填入2
begin_timestamp unsigned int 14300000 固定日期区间专用,表示起用时间。(单位为秒)
end_timestamp unsigned int 15300000 固定日期区间专用,表示结束时间。结束时间仅支持往后延长。

会员卡专属字段修改:

特别注意,以下支持更新的字段不在基本信息base_info的结构中。

参数名 是否提审 类型 描述
background_pic_url string(128) 会员卡自定义卡面背景图
supply_bonus bool 是否支持积分,仅支持从false变为true,默认为false
bonus_cleared string(3072) 积分清零规则。
bonus_rules string(3072) 积分规则。
bonus_url string(128) 积分信息类目跳转的url。
balance_url string(128) 余额信息类目跳转的url
supply_balance bool 是否支持储值,仅支持从false变为true,默认为fals e 该字段须开通储值功能后方可使用, 详情见: 获取特殊权限
balance_rules string(3072) 储值说明。
prerogative string(3072) 特权说明。
wx_activate bool 是否开通一键开卡 设置为true时,该卡将支持一键开卡详情见 一键开卡 。 该选项与activate_url互斥。
auto_activate bool 是否开通自动激活 ,设置为true时用户领取会员卡自动设置为激活, 详情见 自动激活 。
activate_url string(128) 激活链接
custom_field1 Json结构 自定义会员信息类目,会员卡激活后显示。
custom_field2 Json结构 自定义会员信息类目,会员卡激活后显示。
custom_field3 Json结构 自定义会员信息类目,会员卡激活后显示。
name_type string(24) 会员信息类目名称。 FIELD_NAME_TYPE_LEVEL 等级 FIELD_NAME_TYPE_COUPON 优惠券 FIELD_NAME_TYPE_STAMP 印花 FIELD_NAME_TYPE_DISCOUNT 折扣FIELD_NAME_TYPE_ACHIEVEMEN 成就 FIELD_NAME_TYPE_MILEAGE 里程
url string(128) 点击类目跳转外链url
custom_cell1 JSON结构 自定义会员信息类目,会员卡激活后显示
bonus_rule JSON结构 积分规则结构体,用于 微信买单功能
cost_money_unit int 消费金额,以分为单位
increase_bonus int 根据以上消费金额对应增加的积分
max_increase_bonus int 单次获取的积分上限
init_increase_bonus int 用户激活后获得的初始积分
cost_bonus_unit int 每使用x积分。
reduce_money int 抵扣xx元,(这里以分为单位)
least_money_to_use_bonus int 抵扣条件,满xx元(这里以分为单位)可用
max_reduce_bonus int 抵扣条件,单笔最多使用xx积分
discount int 折扣,该会员卡享受的折扣优惠

返回数据说明

数据示例:

{
   "errcode":0,
   "errmsg":"ok",
  "send_check"true
}

参数名 描述
errcode 错误码,0为正常。
errmsg 错误信息。
send_check 此次更新是否需要提审,true为需要,false为不需要。

开发者注意事项注

1. 更改卡券的部分字段后会重新提交审核,详情见字段说明,更新成功后可通过调用查看卡券详情接口核查更新结果;

2. 仅填入需要更新的字段,许多开发者在调用该接口时会填入brandname等不支持修改的字段,导致更新不成功。

3. 调用该接口后更改卡券信息后,请务必调用*首页验证是否已成功更改。*

# 8.3 设置跟随推荐

功能介绍

支持开发者在积分、余额变动、会员卡激活等消息底部,配置优惠券或设置跳转外链URL,具体形式如下图,可以是URL也可以是一张卡券。

8.3.1 设置跟随推荐接口

接口说明

开发者可以通过该接口设置会员激活以及发生交易(积分变动、余额变动)后赠送优惠券。

接口详情

接口调用请求说明

http请求方式: POSTURL:https://api.weixin.qq.com/card/update?access_token=TOKEN

参数说明

参数 是否必须 说明
access_token 调用接口凭证
POST数据 Json数据

使用消息配置卡券

{
    "card_id": "pbLatjkoa7luhR3zIBjtQiaYtnz4",
    "member_card": {
        "activate_msg_operation": {
   //若指定的是积分、余额等变动消息赠券,则为modify_msg_operation
            "url_cell": {
                "card_id_list": [
                    "pbLatjhcI6XUxJWA0Au3Gaq5eFPs"
                ],
                "end_time": 1492724561,
                "text": "恭喜你获得一张50元代金券",
                "url": "www.qq.com"
            }
        }
    }
}

字段说明

字段名 必填 说明
card_id 卡券ID。
member_card 会员卡结构体,如示例
modify_msg_operation 推荐类型,代表积分余额等变动消息赠券
activate_msg_operation 推荐类型,代表会员卡激活消息赠券
url_cell 推荐内容结构体,如示例
card_id_list 送券的card_id列表,不支持普通券和朋友的券混合使用,最多填写10个card_id
end_time 推荐位展示的截止时间
text 文本内容
url 跳转链接,与card_id_list互斥,若设置了跳转url,用户点击模板消息详情后将跳转至该链接领券
app_brand_id 跳转链接对应的小程序appid,与card_id_list互斥,若设置了,用户点击模板消息详情后将跳转至该小程序领券
app_brand_pass 跳转链接对应的小程序路径,与card_id_list互斥,若设置了,用户点击模板消息详情后将跳转至该小程序领券

返回数据

{
   "errcode":0,
   "errmsg":"ok"
}

字段说明

字段名 说明
错误码 错误码,0为正常;43008为商户没有开通微信支付权限;
errmsg 错误信息

开发者注意事项

1.支持一张会员卡同时设置积分/余额变动消息赠券和激活赠券,开发者须分开设置;

2.开发者若填写了card_id_list后,若再填写url字段则card_id_list内容失效;

3.若开发者设置了url,则须支持在url上领券,否则会被视为恶意营销处罚。

# 8.4 设置支付后投放卡券

8.4.1 设置支付后投放卡券接口

开通微信支付的商户可以设置在用户微信支付后自动为用户发送一条领卡消息,用户点击消息即可领取会员卡/优惠券。

目前该功能仅支持微信支付商户号主体和制作会员卡公众号主体一致的情况下配置,否则报错。开发者可以登录

“公众平台”-“公众号设置”、**“微信支付商户平台首页”**插卡企业主体信息是否一致。

接口说明

支持商户设置支付后投放卡券规则,可以区分时间段和金额区间发会员卡。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/paygiftcard/add?access_token=TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

设置支付即会员时POST数据

{
    "rule_info": {
        "type": "RULE_TYPE_PAY_MEMBER_CARD",
        "base_info": {
            "mchid_list": [
                            "123",
                            "456"
            ],
            "begin_time": 1480317217,
            "end_time": 1580317217
        },
        "member_rule": {
            "card_id": "abcdefg",
            "least_cost": 2,
            "max_cost": 20000,
            "jump_url": "www.qq.com"
        }
         }
  }

字段说明

字段名 是否必填 说明
rule_info 支付后营销规则结构体

rule_info是一个JSON结构,包含以下字段

字段名 是否必填 说明
type 营销规则类型,支付即会员填 写RULE_TYPE_PAY_MEMBER_CARD
base_info 营销规则结构体
member_rule 支付即会员结构体

base_info是一个JSON结构,包含以下字段

字段名 是否必填 说明
mchid_list 商户号列表,是一个数组结构,建议单词 请求100个以下商户号
begin_time 规则开始时间
end_time 规则结束时间

member_rule是一个JSON结构,当前设置为支付即会员时填入,包含以下字段

字段名 是否必填 说明
card_id 要赠送的会员卡card_id
least_cost 单次消费送会员卡的金额下限 ,以分为单位
max_cost 单次消费送会员卡的金额上限 ,以分为单位
jump_url 商户自定义领卡网页链接,填入 后点击支付即会 员消息会跳转至商户网页领卡
app_brand_id 商户自定义领卡小程序appid,填入 后点击支付即会 员消息会跳转至商户小程序领卡
app_brand_pass 商户自定义领卡小程序路径,填入 后点击支付即会 员消息会跳转至商户小程序领卡

返回数据说明

数据示例:

  {
    "errcode": 0,
    "errmsg": "ok",
    "rule_id": 1231243,
    "fail_mchid_list": [
        {
            "mchid": "111",
            "errcode": 23112,
            "errmsg": "err",
            "occupy_rule_id": 12332123,
            "occupy_appid": "appid"
        }
    ]
    "succ_mchid_list": [
        "123",
        "456"
    ]
}

参数名 描述
errcode 错误码,0为正常。
errmsg 错误信息。
rule_id 本次设置的规则id,供后续修改删除使用
succ_list 设置成功的mchid列表
fail_list 设置失败的mchid列表
mchid 支付的商户号
occupy_appid 该mchid当前被占用的appid,商户须使用该appid解除绑定后重新设置
occupy_rule_id 该mchid当前被占用的rule_id,商户须使用修改或删除该rule_id重新设置

开发者注意事项

  1. 会员卡领卡消息针对单个新用户仅发送一次,若该用户已经接收或者已经领取过会员卡则不会重复发送;

  2. 通过该规则设置的card_id的制券appid主体必须和当前mch_id的主体一致,否则报错72001;

开发者可以登录**“公众平台”-“公众号设置”“微信支付商户平台首页”**插卡企业主体信息是否一致;

3.仅支持会员卡类型的卡券,否则报错:72003;

4.设置支付即会员时,须确认调用接口的appid须为制卡的appid,否则报错:72002;

5.须保证mchid之前没有被其他appid设置过,否则报错72004,须先删除支付即会员规则后调用;

6.单次仅限设置10个mchid,若超过10个请多次调用本接口。

Q&A

Q:我已有商户号和公众号,如何知道两者的主体是否一致?

A:可在“公众平台”-“公众号设置”、“微信支付商户平台首页”查看企业主体信息是否一致。

**Q:我们是集团和子公司的关系,希望在子公司商户号下支付后,发放集团的公众号创建的会员卡。但是用子公司的appid为子公司的mchid配置规则,设置集团公司的card_id报错72002,怎么办?**

A:对于这种情况,可以登录微信开放平台 (https://open.weixin.qq.com/) ,将所有子公司的公众号绑定在总公司的第三方平台账号下方,完成绑定后可实现集团号间发卡的配置,并相互识别会员身份(UnionID机制)。

Q:我们是集团和子公司的关系,希望在子公司商户号下支付后,发放集团的公众号创建的会员卡。但是用集团的appid为子商户的mchid配置规则,设置集团公司的card_id报错72001,怎么办?

A:解决方法同上

8.4.2 删除支付后投放卡券规则接口

删除之前已经设置的支付即会员规则。

接口说明

支持商户删除之前设置的规则id

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/paygiftcard/delete?access_token=TOKEN

参数说明

参数 是否必须 说明
POST数据 JSON数据
access_token 调用接口凭证

POST数据

{    "rule_id": 1233}

字段说明

字段名 说明
rule_id 支付即会员的规则名称

返回数据说明

数据示例:

{
    "errcode": 0,
    "errmsg": "ok"
}

参数名 描述
errcode 错误码,0为正常。
errmsg 错误信息。

8.4.3 查询支付后投放卡券规则详情接口

接口说明

可以查询某个支付即会员规则内容。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/paygiftcard/getbyid?access_token=TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{    "rule_id": 11233}

字段说明

字段名 说明
rule_id 要查询规则id

返回数据说明

数据示例:

{
    "errcode": 0,
    "errmsg": "ok",
    "rule_info": {
        "type": "RULE_TYPE_PAY_MEMBER_CARD",
        "base_info": {
            "mchid_list": [
                "123",
                "456"
            ],
            "begin_time": 1480317217,
            "end_time": 1580317217,
            "status": "RULE_STATUS_OK",
            "create_time": 1480317217,
            "update_time": 1480317217
        },
        "member_rule": {
            "card_id": "abcdefg",
            "least_cost": 2,
            "max_cost": 20000,
            "jump_url": "www.qq.com"
        }
    }
}

8.4.3批量查询支付后投放卡券规则接口

接口说明

可以批量查询某个商户支付即会员规则内容

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/paygiftcard/batchget?access_token=TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{
    "type": "RULE_TYPE_PAY_MEMBER_CARD",
    "effective": true,
    "offset": 0,
    "count" : 1
}

字段说明

字段名 说明
type 类型,此处填写 RULE_TYPE_PAY_MEMBER_CARD
effective 是否仅查询生效的规则
offset 起始偏移量
count 查询的数量

返回数据说明

数据示例:

{
    "errcode": 0,
    "errmsg": "ok",
    "total_count": 4,
    "rule_list": [
        {
            "type": "RULE_TYPE_PAY_MEMBER_CARD",
            "base_info": {
                "mchid_list": [
                    "123",
                    "456"
                    ],
                "begin_time": 1480317217,
                "end_time": 1580317217,
                "status": "RULE_STATUS_OK",
                "create_time": 1480317217,
                "update_time": 1480317217
            },
            "member_rule": {
                "card_id": "abcdefg",
                "least_cost": 2,
                "max_cost": 20000,
                "jump_url": "www.qq.com"
            }
        }
    ]
}

注意事项:

1.以上为支付即会员新接口协议,旧接口依然可以调用,旧协议见:

https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=1481363811&version=1&lang=zh_CN&platform=2

# 8.5 设置会员卡支持微信支付刷卡

通过接口创建支持刷卡类型的会员卡,用户点击快速买单后即可拉出刷卡界面进行支付。以下为示意图:

8.5.1 创建会员卡支持微信支付刷卡

商户可以创建一张会员卡支持微信支付刷卡,须在创建会员卡接口的JSON中加入以下字段:

{
     "card": {
         "card_type": "MEMBER_CARD",
         "member_card": {
             "base_info": {
                 "pay_info":
                 {
                         "swipe_card":
                         {
                           "is_swipe_card":true
                      }
                    }
             }
         }
     } 
}

详情请见:创建会员卡

8.5.2 更新会员卡支持微信支付刷卡

商户可以更新已有会员卡支持微信支付刷卡,须在更新会员卡接口的JSON中加入以下字段:

{
    "card_id": "ph_gmt7cUVrlRk8swPwx7aDyF-pg",
    "member_card": {
             "base_info": {
                 "pay_info":
                 {
                         "swipe_card":
                         {
                             "is_swipe_card":true
                     }
                   }
              }
     } 
}

详情请见:管理会员卡

开发者注意事项

1.设置该功能之前,请确认自己是否开通了微信支付,否则接口报错(开通微信支付

2.通过接口设置会员卡拉出刷卡后,当用户进行支付时通过授权码查询OPENID接口https://pay.weixin.qq.com/wiki/doc/api/micropay.php?chapter=9_13&index=9获取用户openid,

再调用获取用户领取卡券接口http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&token=&lang=zh_CN获取该openid的会员身份,并进行相应的批价。

3.仅微信6.3.18及以上版本支持会员卡拉出刷卡支付,低于6.3.18的客户端版本将提示用户升级。

# 8.6 其他接口

8.6.1 修改库存接口

调用修改库存接口增减某张卡券的库存,详情见:管理卡券

8.6.2 查询code接口

开发者可以通过该接口查询会员卡的基本信息,包括领取人的OpenID、会员卡状态,详情见:管理卡券

8.6.3 获取用户已领取的卡券

支持开发者调用该接口获取指定用户卡包中属于该appid下的卡券,详情见:管理卡券

8.6.4 查看卡券详情

调用该接口可查询card_id创建是传入的字段详情及卡券所处审核状态。详情见:管理卡券

8.6.5 批量查询卡列表

开发者可以通过该接口拉取当前商户(appid)下所有的卡券列表,用于卡券管理,详情见:管理卡券

8.6.6 删除会员卡

开发者可以通过该接口删除商户列表的card_id,用于卡券管理,详情见:管理卡券

8.6.7 设置会员卡失效接口

开发者可以通过该接口将某一个用户的某一张卡券置为失效,用于退款等场景,详情见:管理卡券

# 9 统计会员卡数据

开发者可以通过该接口拉取会员卡数据,详情见:管理卡券

# 10 我是第三方

第三方可以为接入的商户代制会员卡,详情参考:第三方开发者模式