首页 接入指引 产品中心 解决方案 文档中心 接入微信支付
文档中心
首页 接入指引 产品中心 解决方案 文档中心 接入微信支付
产品文档API字典通用规则SDK&开发工具更新日志
API字典
搜索

创建会员卡模板

更新时间：2023.11.28

通过此接口可以创建一张会员卡模板，创建成功将获得会员卡模板card_id

# 接口说明

支持商户： 【普通商户】

请求方式： 【POST】

请求URL： /v3/marketing/membercard-open/cards

# 请求参数

    Body 包体参数
  • appid 必填 string(32)
    【商户AppID】 商户的公众号AppID。
    1、只能为服务号AppID，不支持App、小程序、订阅号的AppID。
    2、该AppID用于获取会员OpenID及unionid。
    3、会员相关（会员状态、权益、服务）消息将通过该服务号触达用户
    4、该AppID需要与会员卡归属品牌有B-A关系
  • logo_url 必填 string(128)
    【会员卡logo】 会员卡logo的URL地址。仅支持通过《图片上传API》接口获取的图片URL地址。
    1、商户logo大小需为120像素*120像素。
    2、支持JPG/JPEG/PNG格式，且图片小于1M。
  • brand 必填 object
    【品牌信息】 该会员卡归属的品牌信息
    • 属性
  • title 必填 string(10)
    【卡名称】 1.展示在卡面上
    2.支持最长10个中文字
    3.支持中文字、英文字符、标点
  • background_picture_ur 必填 string(128)
    【会员卡背景图】 商家自定义会员卡背景图。仅支持通过《图片上传API》接口获取的图片URL地址。
    1、大小需为1000像素*600像素。
    2、支持JPG/JPEG/PNG格式，且图片小于1M。
  • description 必填 string(500)
    【使用须知】 展示在会员卡详情内，最长500个中文字符，建议填写会员权益及服务相关描述。
  • service_phone 选填 string(32)
    【服务电话】 展示在会员卡详情内，建议填写商家固定电话。
  • code_type 必填 string(32)
    【会员码型】 员卡的码型支持二维码/条形码/二维码+条形码/不展示码，这4种码型是根据membershipnumber字段生成，用户领卡后membershipnumber默认为code值，支持商户修改
    枚举值：
    BAR_CODE：条形码
    QRCODE：二维码
    BAR_CODE_AND_QRCODE：条形码和二维码
    NONE_CODE：不显示任何码型
  • total_quantity 选填 int
    【会员卡总库存】 可投放的最大会员卡数量。仅在会员卡code分配类型为系统自动分配（SYSTEM_ALLOCATE）时需要填写，其他分配类型不需要填写库存。系统分配code类型下，若未填写总库存，则微信支付系统会默认将总库存设置为5000000 （默认值）。
  • date_information 必填 object
    【有效期】 有效期
    • 属性
  • code_mode 必填 string(32)
    【会员卡code分配类型】 1、会员卡code是会员在card_id下唯一身份标识，平台支持3中分配类型：
    SYSTEM_ALLOCATE 微信支付系统分配，用户领取会员卡时从微信支付系统分配12位数字作为会员code；
    MERCHANT_DEPOSIT 商户预存code，商户可提前通过导入预存code接口导入code，用户领取会员卡时平台从商户导入的code中随机分配作为会员code
    REAL_TIME 商家在激活时实时传入code，该模式仅支持小程序拉起开卡组件投放，不支持通过支付后、二维码投放。
    2、会员卡code分配模式一旦指定，不支持修改。
    SYSTEM_ALLOCATE：系统分配
    MERCHANT_DEPOSIT：商户预存
    REAL_TIME：实时传入
  • need_display_level 选填 boolean
    【是否展示会员等级】 是否在会员卡面向用户展示等级信息，默认不展示（false）
  • init_level 选填 string(5)
    【会员初始等级】 如果展示会员等级，必填init_level，作为新用户开卡后的初始等级。如因商家业务规则需要变更某会员等级，可通过更新用户会员卡接口更新等级信息
  • out_request_no 必填 string(128)
    【商户请求单号】 商户创建会员卡凭据号。商户自定义，注意保持唯一性，仅供参考的格式：商户ID+日期+流水号。可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号。
  • balance_information 选填 object
    【储值信息】 储值信息
    • 属性
  • user_information_form 选填 object
    【开卡信息】 用户在开通会员卡时需要填写的信息
    • 属性
  • additional_statement 选填 object
    【商户补充声明】 商户补充声明
    • 属性
  • need_dynamic_code 选填 boolean
    【是否启用动态码】 是否启用动态码功能。若启用，用户会员卡的身份识别码会被系统生成的18位数字取替，动态改变，可有效保障用户的储值资产安全，降低用户因被截图带来的储值盗用风险。默认为false

# 返回参数

  • card_id 必填 string(32)
    【会员卡ID】 商户创建微信会员卡模板成功后系统返回的会员卡ID
  • create_time 选填 string(32)
    【创建时间】 创建会员卡的时间
    遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2020-05-20T13:29:35.120+08:00表示北京时间2020年05月20日13点29分35秒。
  • update_time 选填 string(32)
    【更新时间】 更新时间
    遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2020-05-20T13:29:35.120+08:00表示北京时间2020年05月20日13点29分35秒。
  • remain_quantity 选填 int
    【剩余库存】 会员卡剩余的库存
  • status 选填 string(16)
    【会员卡状态】 会员卡当前的状态：
    NOT_APPROVE：待审核
    APPROVE_FAIL：审核失败
    APPROVED：通过审核
    DELETED：卡被商户删除
  • brand 必填 object
    【品牌信息】 该会员卡归属的品牌信息
    • 属性
  • appid 必填 string(32)
    【商户AppID】 1.展示在卡面上
    2.支持最长10个中文字
    3.支持中文字、英文字符、标点
  • logo_url 必填 string(128)
    【会员卡logo】 会员卡logo的URL地址。仅支持通过《图片上传API》接口获取的图片URL地址。
    1、商户logo大小需为120像素*120像素。
    2、支持JPG/JPEG/PNG格式，且图片小于1M。
  • title 必填 string(10)
    【卡名称】 1.展示在卡面上
    2.支持最长10个中文字
    3.支持中文字、英文字符、标点
  • background_picture_ur 必填 string(128)
    【会员卡背景图】 商家自定义会员卡背景图。仅支持通过《图片上传API》接口获取的图片URL地址。
    1、大小需为1000像素*600像素。
    2、支持JPG/JPEG/PNG格式，且图片小于1M。
  • description 必填 string(500)
    【使用须知】 展示在会员卡详情内，最长500个中文字符，建议填写会员权益及服务相关描述。
  • service_phone 选填 string(32)
    【服务电话】 展示在会员卡详情内，建议填写商家固定电话。
  • code_type 必填 string(32)
    【会员码型】 员卡的码型支持二维码/条形码/二维码+条形码/不展示码，这4种码型是根据membershipnumber字段生成，用户领卡后membershipnumber默认为code值，支持商户修改
    枚举值：
    BAR_CODE：条形码
    QRCODE：二维码
    BAR_CODE_AND_QRCODE：条形码和二维码
    NONE_CODE：不显示任何码型
  • total_quantity 选填 int
    【会员卡总库存】 可投放的最大会员卡数量。仅在会员卡code分配类型为系统自动分配（SYSTEM_ALLOCATE）时需要填写，其他分配类型不需要填写库存。系统分配code类型下，若未填写总库存，则微信支付系统会默认将总库存设置为5000000 （默认值）。
  • date_information 必填 object
    【有效期】 有效期
    • 属性
  • code_mode 必填 string(32)
    【会员卡code分配类型】 1、会员卡code是会员在card_id下唯一身份标识，平台支持3中分配类型：
    SYSTEM_ALLOCATE 微信支付系统分配，用户领取会员卡时从微信支付系统分配12位数字作为会员code；
    MERCHANT_DEPOSIT 商户预存code，商户可提前通过导入预存code接口导入code，用户领取会员卡时平台从商户导入的code中随机分配作为会员code
    REAL_TIME 商家在激活时实时传入code，该模式仅支持小程序拉起开卡组件投放，不支持通过支付后、二维码投放。
    2、会员卡code分配模式一旦指定，不支持修改。
    SYSTEM_ALLOCATE：系统分配
    MERCHANT_DEPOSIT：商户预存
    REAL_TIME：实时传入
  • need_display_level 选填 boolean
    【是否展示会员等级】 是否在会员卡面向用户展示等级信息，默认不展示（false）
  • init_level 选填 string(5)
    【会员初始等级】 如果展示会员等级，必填init_level，作为新用户开卡后的初始等级。如因商家业务规则需要变更某会员等级，可通过更新用户会员卡接口更新等级信息
  • out_request_no 必填 string(128)
    【商户请求单号】 商户创建会员卡凭据号。商户自定义，注意保持唯一性，仅供参考的格式：商户ID+日期+流水号。可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号。
  • balance_information 选填 object
    【储值信息】 储值信息
    • 属性
  • user_information_form 选填 object
    【开卡信息】 用户在开通会员卡时需要填写的信息
    • 属性
  • additional_statement 选填 object
    【商户补充声明】 商户补充声明
    • 属性
  • need_dynamic_code 选填 boolean
    【是否启用动态码】 是否启用动态码功能。若启用，用户会员卡的身份识别码会被系统生成的18位数字取替，动态改变，可有效保障用户的储值资产安全，降低用户因被截图带来的储值盗用风险。默认为false

请求示例

1{
2  "appid": "wxea9c30890f48d5ae",
3  "logo_url": "https://wxpaylogo.qpic.cn/wxpaylogo/PiajxSqBRaEIPAeia7Imvtsn7sYGNcEj33YzVvJF88ECQ19LXId8ZL2Q/0",
4  "brand": {
5    "brand_id": "1004",
6    "display_name": "微信支付"
7  },
8  "title": "微信支付测试卡",
9  "background_picture_url": "https://wxpaylogo.qpic.cn/wxpaylogo/PiajxSqBRaEIPAeia7Imvtsn7sYGNcEj33YzVvJF88ECQ19LXId8ZL2Q/0",
10  "description": "使用本会员卡表示你同意xxx公司的协议",
11  "service_phone": "010-8877xxxx",
12  "code_type": "BAR_CODE",
13  "total_quantity": 5000000,
14  "date_information": {
15    "type": "FIX_TIME_RANGE",
16    "available_begin_time": "2020-05-20T13:29:35.120+08:00",
17    "available_end_time": "2030-05-20T13:29:35.120+08:00",
18    "available_day_after_receive": 200,
19    "wait_days_after_receive": 1
20  },
21  "code_mode": "SYSTEM_ALLOCATE",
22  "need_display_level": true,
23  "init_level": "白银会员",
24  "out_request_no": "100002322019090134234sfdf",
25  "balance_information": {
26    "need_balance": false,
27    "balance_appid": "wxea9c30890f48d5ae",
28    "balance_path": "pages/balance/balance",
29    "balance_url": "https://xxx.com"
30  },
31  "user_information_form": {
32    "common_field_list": [
33        "USER_FORM_FLAG_MOBILE",
34        "USER_FORM_FLAG_SEX",
35        "USER_FORM_FLAG_NAME",
36        "USER_FORM_FLAG_BIRTHDAY"
37      ],
38    "custom_field_list": [
39      {
40        "type": "TEXT",
41        "name": "喜欢的运动",
42        "values": [
43          "篮球",
44          "足球",
45          "羽毛球"
46        ]
47      }
48    ]
49  },
50  "additional_statement": {
51    "title": "xxx会员卡使用须知",
52    "url": "https://xxx.111.com",
53    "appid": "wxea9c30890f48d5ae",
54    "path": "pages/statement/statement"
55  },
56  "need_dynamic_code": false
57}

返回示例

1{
2  "card_id": "pbLatjvWOibDc5-TBnbUk1pD12o0",
3  "create_time": "2020-05-20T13:29:35.120+08:00",
4  "update_time": "2020-05-20T13:29:35.120+08:00",
5  "remain_quantity": 1004,
6  "status": "NOT_APPROVE",
7  "brand": {
8    "brand_id": "1004",
9    "display_name": "微信支付"
10  },
11  "appid": "wxea9c30890f48d5ae",
12  "logo_url": "https://wxpaylogo.qpic.cn/wxpaylogo/PiajxSqBRaEIPAeia7Imvtsn7sYGNcEj33YzVvJF88ECQ19LXId8ZL2Q/0",
13  "title": "微信支付测试卡",
14  "background_picture_url": "https://wxpaylogo.qpic.cn/wxpaylogo/PiajxSqBRaEIPAeia7Imvtsn7sYGNcEj33YzVvJF88ECQ19LXId8ZL2Q/0",
15  "description": "使用本会员卡表示你同意xxx公司的协议",
16  "service_phone": "010-8877xxxx",
17  "code_type": "BAR_CODE",
18  "total_quantity": 5000000,
19  "date_information": {
20    "type": "FIX_TIME_RANGE",
21    "available_begin_time": "2020-05-20T13:29:35.120+08:00",
22    "available_end_time": "2030-05-20T13:29:35.120+08:00",
23    "available_day_after_receive": 200,
24    "wait_days_after_receive": 1
25  },
26  "code_mode": "SYSTEM_ALLOCATE",
27  "need_display_level": true,
28  "init_level": "白银会员",
29  "out_request_no": "100002322019090134234sfdf",
30  "balance_information": {
31    "need_balance": false,
32    "balance_appid": "wxea9c30890f48d5ae",
33    "balance_path": "pages/balance/balance",
34    "balance_url": "https://xxx.com"
35  },
36  "user_information_form": {
37    "common_field_list": [
38        "USER_FORM_FLAG_MOBILE",
39        "USER_FORM_FLAG_SEX",
40        "USER_FORM_FLAG_NAME",
41        "USER_FORM_FLAG_BIRTHDAY"
42      ],
43    "custom_field_list": [
44      {
45        "type": "TEXT",
46        "name": "喜欢的运动",
47        "values": [
48          "篮球",
49          "足球",
50          "羽毛球"
51        ]
52      }
53    ]
54  },
55  "additional_statement": {
56    "title": "xxx会员卡使用须知",
57    "url": "https://xxx.111.com",
58    "appid": "wxea9c30890f48d5ae",
59    "path": "pages/statement/statement"
60  },
61  "need_dynamic_code": false
62}

# 错误码

# 公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 参数错误 请根据错误提示正确传入参数
400 INVALID_REQUEST HTTP 请求不符合微信支付 APIv3 接口规则 请参阅 接口规则
401 SIGN_ERROR 验证不通过 请参阅 签名常见问题
500 SYSTEM_ERROR 系统异常，请稍后重试 请稍后重试

# 业务错误码

状态码 错误码 描述 解决方案
403 NO_AUTH 商户暂无权限使用此功能 请开通商户号权限。请联系产品或商务申请
500 SYSTEM_ERROR 生成二维码链接失败，请重试 系统异常，请使用相同参数稍后重新调用
400 INVALID_REQUEST 扫码投放场景不支持实时code模式 请更换非实时code模式的会员卡再重试
400 INVALID_REQUEST 会员卡的创建商户号不等于调用方商户号 请使用会员卡的创建商户号进行操作
400 INVALID_REQUEST 请先升级会员卡才能使用此功能 请先调用《升级会员卡API》升级会员卡
400 INVALID_REQUEST AppID非服务号 请使用正确的服务号的AppID重新调用，不支持App、小程序、订阅号。
400 INVALID_REQUEST 会员卡code分配类型不支持修改 会员卡code分配类型为“系统分配”，不支持修改
400 INVALID_REQUEST 会员卡code分配类型不支持修改为“系统分配” 会员卡code分配类型无法修改为“系统分配”。
400 INVALID_REQUEST 储值小程序path为空 请填写储值小程序path
400 INVALID_REQUEST 会员卡ID无效 请检查会员卡ID是否正确填写
400 INVALID_REQUEST 该会员1年内未在本商家有微信支付交易，无法导入 请更换手机号重试
400 INVALID_REQUEST 会员已经领取过该卡 请使用其他会员卡
400 INVALID_REQUEST 会员卡code为实时模式，需要传入卡code 请填入卡code
400 INVALID_REQUEST 积分跳转path为空 请填写积分跳转path
400 INVALID_REQUEST 自助积分跳转path为空 请填写自助积分跳转path
400 INVALID_REQUEST 会员专享价跳转path为空 请填写会员专享价跳转path
400 INVALID_REQUEST 该手机号和会员卡已被导入过 请更换手机号或会员卡ID重试
400 INVALID_REQUEST 该商户号不是会员卡的创建商户号 请使用会员卡的创建商户号进行操作
400 INVALID_REQUEST 手机号未绑定微信号，无法导入 请更换手机号重试
400 INVALID_REQUEST 商户无授权，请重试 请开通商户号权限。请联系产品或商务申请
400 INVALID_REQUEST 该手机号会员卡记录不存在 请更换手机号或会员卡ID重试
400 INVALID_REQUEST 没有符合条件的数据 请使用正确的参数重新调用
400 INVALID_REQUEST 商户号不属于该卡的创建方 请使用会员卡创建方的商户号重新调用
400 INVALID_REQUEST 会员卡已经迁移 会员卡已经迁移，无需重复操作
400 INVALID_REQUEST 会员权益一旦展示无法关闭 会员权益一旦展示无法关闭
400 INVALID_REQUEST 会员储值一旦展示无法关闭 会员储值一旦展示无法关闭
400 INVALID_REQUEST 需要上架至少一个积分权益、优惠权益、服务才可以投放 请先给会员卡上架至少一个积分权益、优惠权益、服务
400 PARAM ERROR AppID有误 请使用正确的AppID重新调用
400 PARAM ERROR OpenID有误 请使用正确的OpenID重新调用
400 PARAM ERROR 商户和品牌关系校验失败 请先将商户号绑定到品牌
400 PARAM ERROR 品牌、AppID关系校验失败 请先将AppID绑定到品牌
服务商文档
服务商文档中心
更多支持
开发者社区 微信开放平台 微信公众平台 腾讯客服
更多技术问题
技术咨询
接口说明
请求参数
返回参数
错误码
公共错误码
业务错误码
反馈
咨询
目录
Powered By Tencent & Tenpay　Copyright 2005-2023 Tenpay All Rights Reserved.
Powered By Tencent & Tenpay
Copyright 2005-2023 Tenpay All Rights Reserved.

关于我们

关于微信支付 平台使用协议 支付服务协议 联系我们

服务支持

开发文档 (服务商) 开发文档 (V2版) 微信开放社区 物料下载

友情链接

微信开放平台 微信公众平台 企业微信

客服帮助

自助服务专区 客服：95017 （工作日 09:00-22:00）
Powered By Tencent & Tenpay　Copyright 2005-2022 Tenpay All Rights Reserved.
Powered By Tencent & Tenpay
Copyright 2005-2022 Tenpay All Rights Reserved.