微信礼品卡
礼品卡接口文档
# 1.礼品卡概述
微信为礼品卡商户提供了一套完整的微信礼品卡的创建、销售以及使用流程,商户可以在微信卡券平台通过API创建礼品卡、创建礼品卡货架、调用接口进行余额同步。开发者通过将创建的礼品卡货架配置在在公众号或生成二维码贴在门店进行礼品卡的售卖。
用户可以通过购买礼品卡送给朋友并且附上祝福语,表达节日的祝福和慰问。一张小小的礼品卡,传递浓浓的情谊。
商户微信礼品卡有以下优势:
1卡包收纳、存储,用户再也不用担心弄丢礼品卡了;
2 原生社交转赠流程顺畅、安全,朋友之间赠送礼品卡变得更加容易了;
3 打开礼品卡礼包的惊喜感,让收到礼品的朋友享受双重喜悦;
4 商户使用微信提供的动态码能力,可以免开发就可以使用安全的二维码储值消费流程;
5 多渠道售卖,商户可以将礼品卡货架配置在公众号菜单、图文、二维码甚至广告渠道进行销售。 更多惊喜,等你一起来探索。
# 2.礼品卡产品流程
以下交互示意供参考,实际以最终实现为准。
# 2.1 礼品卡购买赠送流程
# 2.2 礼品卡接收流程
## 2.3礼品卡卡包内展示 # 3. 接入门槛# 3.1 类目范围
现阶段主要针对以下卡券类目商户开放,虚拟类目暂不支持。具体如下:
# 3.2 商户资质要求
微信礼品卡根据其承载内容,分为储值类型礼品卡和单品类型礼品卡。其中储值类型礼品卡,指卡面信息包含具体储值金额,如1000元礼品卡,单品类型礼品卡,指该礼品卡用于兑换指定单品,如汉堡礼品卡。两种礼品卡需要商户具备的资质条件有所不同,具体如下。
# 3.2.1储值类型礼品卡
商户需具备单用途预付卡备案才可开展礼品卡业务(含礼品储值卡和礼品兑换券),若备案主体与公众号主体不一致,需符合以下条件之一:集团发卡、品牌发卡、多用途牌照方担保。
补充材料
过渡阶段以邮件方式提交,说明如下:
1) 集团发卡:若单用途预付卡持牌机构为集团母公司,申请储值权限的公众号认证主体为集团旗下子公司,且股权占比50%以上,申请方可额外补充备案公司的《集团发卡授权书》(需有备案公司公章),以开通权限。
2) 品牌发卡:若单用途预付卡持牌机构为品牌方,申请储值权限的公众号认证主体为品牌授权的加盟商,申请方可额外补充《特许经营授权书》(需有备案公司公章),以开通权限。
这两种种情况下,授权书由企业自拟,需说明清楚以下情况:我是谁;我备案的情况; 我授权给谁;授权它做什么事情(以集团名义发卡?以品牌名义发卡?);被授权方发的卡,我负责兑现。
3) 多用途预付卡牌照:若申请方获得预付卡发行与受理的发行机构(《支付业务许可证》)的合作授权,申请方可通过邮件直接提交《多用途预付卡备案》材料,以及备案方与申请方的《合作协议》(需有备案公司公章),以开通权限。
此处需关注三点:
a. 牌照方必须是“预付卡发行与受理”的发行机构,不能是“预付卡受理”的受理机构;b. 完成授权后,品牌方需委托牌照方执行制卡、发卡等行为,品牌方自身公众号仍未获得预付卡权限,如果牌照方需要进行预付卡销售,为合规行为,经法务评估不存在二清风险,另由于目前法规规定发卡机构应当通过实体网点发行销售预付卡,建议优先接入有实体卡业务的商户;
c. 《支付机构预付卡业务管理办法》规定,支付机构应该严格按照《支付业务许可证》核准的业务类型和业务范围从事预付卡业务,不得在未设立省级分支机构的省(自治区、直辖市、计划单列市)从事预付卡业务。因此,地方性的牌照持有方不得在全国范围开展业务。
多用途牌照方授权的情况下,授权书在以上基础上,还需要补充以下说明,即需完整描述:
a) 我是谁,我备案的情况,我授权给谁,授权它做什么事情,被授权方发的卡,我负责兑现;
b) 特约商户基本信息;
c) 收费项目和标准;
d) 持卡人用卡权益的保障要求;
e) 卡片信息、交易数据、受理终端、交易凭证的管理要求;
f) 特约商户收款账户名称、开户行、账号及资金结算周期;
g) 账务核对、差错处理和业务纠纷的处置要求;
h) 相关业务风险承担和违约责任的承担机制 ;
i) 协议终止条件、终止后的债权债务清偿方式。
补充材料,在过渡阶段统一以邮件的方式,发送给:weixincard@tencent.com,后续会支持在MP系统提交。
# 3.2.2 单品类型礼品卡
无需具备预付卡资质,平台视为普通兑换卡业务。符合类目要求的商家无需单独走申请流程,凭接口文档可以直接开发。
# 4 接入准备
# 4.1 拥有一个认证公众号并开通卡券功能
# 4.1.1新注册流程
- 若商户还未拥有开通卡券功能的公众号,商户可以登录【微信公众平台】进行公众号注册并进行认证,具体流程参见:《注册微信公众平台》
- 注册完成后,商户可以登录【微信公众平台】,并进入【添加插件】-【卡包功能】提交相应资料并开通卡券功能,详情参见:《微信卡券功能使用规则》。
# 4.1.2非新注册流程
- 若商户已有开通卡券功能的公众号则可根据自身情况,决定是否直接复用。
注:以上开通均需3-5工作日的审核时间,请根据项目进度提前申请操作。
# 4.2 拥有一个认证小程序(礼品卡专用)
我们需要商户提供一个独立的小程序用于上传礼品卡的代码以及资料。须商户申请或拥有一个礼品卡专用的小程序。
# 4.2.1 新注册流程
- 若商户还未拥有认证的小程序,商户可以登录【微信公众平台】进行小程序注册并进行认证,具体流程参见:《注册小程序账号》。
# 4.2.2 复用公众号资质快速注册
- 若商户已有认证公众账号,可以登录【微信公众平台】,进入【小程序管理】-【添加】-【快速注册并认证小程序】直接快速注册认证的小程序。
# 4.3 使用用公众号申请商户号
- 商户须使用公众号申请的商户号来走通礼品卡的配置流程,申请流程请见:【微信公众平台】
注意事项
1 自助配置流程仅支持公众号申请的商户号,小程序申请的商户号暂不支持走自助配置流程;
2 商户号建议为礼品卡专用,便于对账统计;
3 支持普通服务商和直连商户模式的商户号,暂不支持银行服务商和支付机构服务商模式下的商户号。
# 5开发概述
# 5.1 须知
礼品卡为微信卡券的一种类型,请开发者在开发礼品卡功能之前请先概览《公众平台接口文档》、《微信卡券接口文档》以及《微信卡券功能使用规则》以确保熟悉礼品卡开发中涉及的基本概念和礼品卡运营相关的基本准则。
# 5.2 术语解释
为了避免开发者在开发过程中产生概念混淆,请开发在开发礼品卡接口前熟知以下术语。
# 5.3 开发步骤
礼品卡开发须经历创建礼品卡、投放礼品卡和礼品卡信息同步几个重要步骤,如下图所示。
注意事项:
本文档仅描述礼品卡创建的主线流程,支线流程请参考卡券接口文档
- 关于是否自定义code的区别以及导入code的操作请参考:
微信卡券接口调用说明:
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056&token=&lang=zh_CN&anchor=2.2
导入自定义code:
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025062&token=&lang=zh_CN&anchor=4.1
公众平台事件处理机制:
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_CN
# 5.4 文档参考
在开发礼品卡功能过程中,可能需要参考以下文档
公众平台接口文档(Token获取、缓存、事件推送处理):
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1445241432&token=&lang=zh_CN
微信卡券接口文档(创建礼品卡、自定义code机制、导入code机制):
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141229&token=&lang=zh_CN
# 6.创建礼品卡
# 6.1 上传礼品卡图片素材接口
开发者需要将展示在微信用户的礼品卡logo和背景图先上传到微信CDN上,获得url后用于创建礼品卡接口的logo_url字段和background_pic_url字段
详情请见:
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056&token=&lang=zh_CN&anchor=2.3
注意事项:
- 礼品卡背景图片设计请严格遵循《微信会员卡自定义背景设计规范》;
- 微信会对商户上传的图片进行防盗链保护,上传素材若被展示在非商户域名下网页时会被禁止显示。
# 6.2 上传礼品卡门店接口
对于与地理位置相关的使用场景的礼品卡,我们建议开发者创建礼品卡的时候填入门店,用户使用礼品卡时,若在门店附近,礼品卡排序会自动置顶。
详情请见:
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056&token=&lang=zh_CN
# 6.3 创建礼品卡接口
接口说明
创建礼品卡接口是微信卡券的基础接口,用于创建一类新的卡券,获取card_id,创建成功并通过审核后,商家可以通过文档提供的其他接口将卡券下发给用户,每次购买成功,库存数量相应扣除。
接口调用请求说明
请求参数说明
POST数据示例:
{
"card": {
"card_type": "GENERAL_CARD",
"general_card": {
"sub_card_type": "GIFT_CARD",
"background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/",
"base_info": {
"max_give_friend_times": 1,
"giftcard_info": {
"price": 1
},
"logo_url": "https://mmbiz.qlogo.cn/mmbiz/p98FjXy8LaeMq67mEpDmkj05EtiaVcGOibVaVux3Agib1ibcHFkCoic7HuQWFawx9XGCNWIO085drjdxTib2nBHlYGAA/0?wx_fmt=gif",
"brand_name": "微信咖啡厅",
"code_type": "CODE_TYPE_QRCODE",
"title": "心意卡",
"color": "Color020",
"notice": "使用时向服务员出示",
"service_phone": "020-88888888",
"description": "不可与其他优惠同享",
"date_info": {
"type": "DATE_TYPE_FIX_TIME_RANGE",
"begin_timestamp": 1397577600,
"end_timestamp": 1472724261
},
"sku": {
"quantity": 50000000
},
"get_limit": 0,
"use_custom_code": false,
"can_give_friend": true,
"location_id_list": [
213059884
],
"center_title": "顶部居中按钮",
"center_sub_title": "按钮下方的wording",
"center_url": "www.qq.com",
"center_app_brand_user_name": "gh_86a091e50ad4@app",
"center_app_brand_pass": "pages/index/index",
"custom_url_name": "新品推荐",
"custom_url": "https://www.starbucks.com.cn/",
"custom_app_brand_user_name": "gh_86a091e50ad4@app",
"custom_app_brand_pass": "pages/index/index",
"need_push_on_view": true
},
"advanced_info": {
"text_image_list": [
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品精选食材,以独特的烹饪方法,最大程度地刺激食 客的味"
},
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品迎合大众口味,老少皆宜,营养均衡"
}
]
},
"supply_balance": true,
"prerogative": "礼品卡享受更多优惠",
"auto_activate": true,
"init_balance": 10000,
"custom_field1": {
"name": "优惠券",
"url": "",
"app_brand_user_name": "",
"app_brand_pass": ""
},
"custom_field2": {
"name": "兑换券",
"url": "",
"app_brand_user_name": "",
"app_brand_pass": ""
}
}
}
}
`请求数据说明:
礼品卡
注意事项:开发者仅能在supply_balance和custom_field1、custom_field2、custom_field3中选择最多3个填写,否则报错。
base_info 字段描述
advanced_info 字段描述
返回数据示例:
{
"errcode":0,
"errmsg":"ok",
"card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"
}
返回数据说明
注意事项:
.
- 支持动态码的礼品卡请参照文档:https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=1478005752&version=1&lang=zh_CN&platform=2
7.礼品卡货架
7.1 货架样式
供参考,以实际实现为准:
7.2 创建-礼品卡货架接口
接口说明
开发者可以通过该接口创建一个礼品卡货架并且用于公众号、门店的礼品卡售卖。
接口调用请求说明
请求参数说明
POST数据示例:
{
"page": {
"page_title": "礼品卡",
"support_multi": true,
"banner_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"theme_list": [
{
"theme_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"title": "title",
"title_color": "#FB966E",
"show_sku_title_first": true,
"item_list": [
{
"card_id": "pbLatjiSj_yVRH5XTb2Zsln7DNQg",
"title": "焦糖拿铁"
},
{
"card_id": "pbLatjlq75CPBR_tYCRdPlxSGlOs",
"title": "焦糖拿铁"
}
],
"pic_item_list": [
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语1"
},
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语2"
},
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语3"
}
],
"category_index": 0
},
{
"theme_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"title": "title_lalala",
"title_color": "#FB966E",
"item_list": [
{
"card_id": "pbLatjiSj_yVRH5XTb2Zsln7DNQg",
"title": "焦糖拿铁"
},
{
"card_id": "pbLatjlq75CPBR_tYCRdPlxSGlOs",
"title": "蛋糕"
}
],
"pic_item_list": [
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语1",
"outer_img_id": "outer_img_id_1"
},
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语2",
"outer_img_id": "outer_img_id_2"
},
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语3",
"outer_img_id": "outer_img_id_3"
}
],
"category_index": 1
},
{
"theme_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"title": "title_lalala",
"title_color": "#FB966E",
"item_list": [
{
"card_id": "pbLatjiSj_yVRH5XTb2Zsln7DNQg"
},
{
"card_id": "pbLatjlq75CPBR_tYCRdPlxSGlOs"
}
],
"pic_item_list": [
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语1",
"outer_img_id": "outer_img_id_1"
},
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语2",
"outer_img_id": "outer_img_id_2"
},
{
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
"default_gifting_msg": "祝福语3",
"outer_img_id": "outer_img_id_3"
}
],
"is_banner": true
}
],
"category_list": [
{
"title": "主题分类一"
},
{
"title": "主题分类二"
}
],
"address": "广州市海珠区222号",
"service_phone": "020-12345678",
"biz_description": "退款指引",
"cell_1": {
"title": "申请发票",
"url": "https://open.weixin.qq.com"
},
"cell_2": {
"title": "申请退款",
"url": "https://mp.weixin.qq.com"
}
}
}
请求数据说明:
theme_list是一个JSON结构,包含以下字段
item_list和pic_item_list是JSON结构,包含以下字段
cell1和cell2是JSON结构,包含以下字段
category_list是JSON结构,包含以下字段
# 返回参数说明
返回数据示例:
{
"errcode": 0,
"errmsg": "ok",
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk"
}
返回数据说明:
注意事项
1.货架链接拼接规则
将page_id进行UrlEncode之后**替换到以下链接的page_id参数的值即可访问商城页首页。
https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id=123456#wechat_redirect
如page_id为:abcedfghifk=+Uasdaseq14fadkf8123h4jk
UrlEncode之后:abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk
加入链接后:
https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id= abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk #wechat_redirect
2. 关于渠道统计
提供outer_str字段做渠道区分,将会在页面中流转,后面在查询订单的api中或者相关callback中都能获取到对应字段。
例如outer_str=abc:
则上述链接变为:
https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id=123456&outer_str=abc#wechat_redirect
如page_id为:abcedfghifk=+Uasdaseq14fadkf8123h4jk
UrlEncode之后:abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk
加入链接后:
https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id=abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk#wechat_redirect
3.货架外链跳转协议
cell中的url,跳转时会在GET参数中带入order_id和openid
比如原本数据是
https://mp.weixin.qq.com 将会变成
https://mp.weixin.qq.com/?order_id=Z2y2rY4UxUZYitvVGA&openid=oAAAAAKe1ri5AAaAiB50-Ak6Vs1w
4.设置审核白名单
创建后的货架处于待审核状态,不可被外界查看购买,须商户申请上线并审核通过后方可完成。
开发人员可以将自己的微信号设置为白名单,用于测试流程,接口参见:[mp.weixin.qq.com]-[卡券部分]-[投放卡券]-[设置卡券白名单]
# 7.3 查询-礼品卡货架信息接口
接口说明
开发者可以查询某个礼品卡货架信息。
接口调用请求说明
请求参数说明
POST数据示例:
{
"page_id" : "abcedfghifk=+Uasdaseq14fadkf8123h4jk"
}
请求数据说明:
返回数据示例:
请求数据说明:参数说明是否必填page_id上一步获取到货架id是返回参数说明返回数据示例:
{
"errcode": 0,
"errmsg": "ok",
"page": {
"banner_pic_url": "http://img.com/banner_pic",
"theme_list": [
{
"theme_pic_url": "http://img.com/theme_pic",
"title": "title_lalala",
"title_color": "#FFFFFF",
"item_list": [
{
"card_id": "card_id_lalala"
}
],
"pic_item_list": [
{
"background_pic_url": "http://img.com/bg_pic1",
"default_gifting_msg": "祝福语1"
},
{
"background_pic_url": "http://img.com/bg_pic2",
"default_gifting_msg": "祝福语2"
},
{
"background_pic_url": "http://img.com/bg_pic3",
"default_gifting_msg": "祝福语3"
}
]
}
]
}
}
返回数据说明:
theme_list是一个JSON结构,包含以下字段
item_list和pic_item_list是JSON结构,包含以下字段
cell1和cell2是JSON结构,包含以下字段
category_list是JSON结构,包含以下字段
# 7.4 修改-礼品卡货架信息接口
接口说明
开发者可以通过该接口更新礼品卡货架信息。
接口调用请求说明
请求参数说明
POST数据示例:
{
"page": {
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"banner_pic_url": "http://img.com/banner_pic",
"theme_list": [
{
"theme_pic_url": "http://img.com/theme_pic",
"title": "title_lalala",
"title_color": "#FFFFFF",
"item_list": [
{
"card_id": "card_id_lalala"
}
],
"pic_item_list": [
{
"background_pic_url": "http://img.com/bg_pic1",
"default_gifting_msg": "祝福语1"
},
{
"background_pic_url": "http://img.com/bg_pic2",
"default_gifting_msg": "祝福语2"
},
{
"background_pic_url": "http://img.com/bg_pic3",
"default_gifting_msg": "祝福语3"
}
]
}
]
}
}
请求数据说明:
theme_list是一个JSON结构,包含以下字段
item_list和pic_item_list是JSON结构,包含以下字段
cell1和cell2是JSON结构,包含以下字段
category_list是JSON结构,包含以下字段
# 返回参数说明
返回数据示例:
{
"errcode" : 0,
"errmsg" : "ok"
}
返回数据说明:
# 7.5 查询-礼品卡货架列表接口
接口说明
开发者可以通过该接口查询当前商户下所有的礼品卡货架id。
接口调用请求说明
请求参数说明
POST数据示例:
{}
# 返回参数说明
返回数据示例:
{
"errcode": 0,
"errmsg": "ok",
"page_id_list": [
"abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"abcedfghifk=+Uasdaseq14fadkf8123h4jl",
"abcedfghifk=+Uasdaseq14fadkf8123h4jm",
"abcedfghifk=+Uasdaseq14fadkf8123h4jn"
]
}
返回数据说明:
# 7.6 下架-礼品卡货架接口
接口说明
开发者可以通过该接口查询当前商户下所有的礼品卡货架id。
接口调用请求说明
请求参数说明
请求参数说明:
POST数据示例:
将某个货架设置为下架
{
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"maintain": true
}
或者将该商户下所有的货架设置为下架
{
"all": true,
"maintain": true
}
返回数据示例:
{
"errcode": 0,
"errmsg": "ok",
"control_info": {
"biz_control_type": "E_PAGE_CONTROL_BIZ",
"system_biz_control_type": "E_PAGE_CONTROL_NORMAL",
"list": [
{
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"page_control_type": "E_PAGE_CONTROL_BIZ",
"system_page_control_type": "E_PAGE_CONTROL_SYSTEM"
}
]
}
}
返回数据说明:
control_info是一个结构体,包含以下字段
listo是一个结构体,包含以下字段
# 8.礼品卡小程序
# 8.1 开通微信支付礼品卡权限
# 8.1.1 申请微信支付礼品卡权限接口
url:
https://api.weixin.qq.com/card/giftcard/pay/whitelist/add?access_token=TOKEN
请求示例
{
"sub_mch_id": "1900015421"//微信支付子商户号
}
返回示例
{
"errcode": 0,
"errmsg": "ok",
"url": "https://pay.weixin.qq.com/index.php/public/product/detail?pid=61&productType=0"
}
注意事项
1.传入的商户号须为普通服务商模式或者直连商户号,建议为礼品卡专用商户号
2.商户号必须为公众号申请的商户号,否则报错
3.调用接口的token须为公众号对应的token,否则报错
4.调用接口的的公众号须与商户号同主体,非同主体情况须和对接人联系申请。 若礼品卡公众号的主体和小程序主体与商户号主体不一致,则须通过以下流程申请: _ 1.找对应的微信支付BD签署公众号-商户号和小程序-商户号联合运营函,并归档_ _ 2.发送以下内容至weixincard@tencent.com_ 邮件名称:xxx礼品卡非同主体支付绑定申请 邮件内容: 公众号名称 认证公众号appid 公众号主体信息 认证小程序appid 小程序主体信息 礼品卡专用商户号 商户号对应的公司名称
_3.确认信息无误后,我们将在五个工作日内处理;
# 8.1.2 登录商户平台后台点击确认
完成4.1步骤后,商户须点击4.1步骤返回的url登录微信支付商户后台,点击确认开通礼品卡支付功能,完成礼品卡支付功能开通。
1点击4.1得到的url,.登录微信支付商户后台
2.登录后进入产品中心,找到【微信礼品卡】点击开通
3.点击开通礼品卡功能
# 8.2 绑定商户号到礼品卡小程序接口
URL
https://api.weixin.qq.com/card/giftcard/pay/submch/bind?access_token=TOKEN
请求示例
{
"sub_mch_id": "1900015421",
"wxa_appid": "wx8638fbedaf138a87"
}
返回示例
{
"errcode": 0,
"errmsg": "ok"
}
注意事项
1.传入的商户号须为普通服务商模式或者直连商户号,建议为礼品卡专用商户号 ;
2.商户号必须为公众号申请的商户号,否则报错;
3.调用接口的token为公众号的token ;
4.公众号须与礼品卡小程序进行关联绑定,详情请见:https://mp.weixin.qq.com/debug/wxadoc/introduction/#公众号关联小程序
# 8.3上传小程序代码
# 8.3.1 上传小程序代码
URL
https://api.weixin.qq.com/card/giftcard/wxa/set?access_token=TOKEN
请求示例
{
"wxa_appid": "wx123456789",
"page_id": "asdasdjkafkjaslfjasl+fjas="
}
返回示例
{
"errcode": 0,
"errmsg": "ok"
}
注意事项
1.公众号须与小程序有绑定关系;
2.小程序代码上传后须登录小程序后台进行提交审核;
# 8.3.2登录小程序后台进行发布
填写礼品卡小程序基本信息
开发者在完成5.1步骤后须登录小程序后台mp.weixin.qq.com,填写小程序相关资料并发布审核
发布体验版测试
点击提交审核
点击提交发布
# 9.礼品卡订单
# 9.1 查询-单个礼品卡订单信息接口
接口说明
开发者可以通过该接口查询某个订单号对应的订单详情。
接口调用请求说明
请求参数说明
POST数据示例:
{
"order_id" : "Z2y2rY74ksZX1ceuGA"
}
请求参数说明:
# 返回参数说明
返回数据示例:
{
"errcode": 0,
"errmsg": "ok",
"order": {
"order_id": "Z2y2rY74ksZX1ceuGA",
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"trans_id": "4001562001201608292531663351",
"create_time": 123,
"pay_finish_time": 123,
"total_price": 123,
"open_id": "123",
"accepter_openid": "123",
"card_list": [
{
"card_id": "card_id_1",
"price": 123,
"code": "code_123456",
"default_gifting_msg": "",
"background_pic_url": "",
"accepter_openid": "123"
}
],
"outer_str": "web",
"IsChatRoom": true
}
}
返回数据说明:
# 9.2 查询-批量查询礼品卡订单信息接口
接口说明
开发者可以通过该接口查询该商户某个时间段内创建的所有订单详情。
接口调用请求说明
请求参数说明
POST数据示例:
{
"begin_time": 1472400000,
"end_time": 1472716604,
"sort_type": "ASC",
"offset": 0,
"count": 2
}
请求参数说明:
# 返回参数说明
返回数据示例:
{
"errcode": 0,
"errmsg": "ok",
"total_count": 47,
"order_list": [
{
"order_id": "Z2y2rY74ksZX1ceuGA",
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"trans_id": "4001562001201608292531663351",
"create_time": 123,
"pay_finish_time": 123,
"total_price": 123,
"open_id": "123",
"accepter_openid": "123",
"card_list": [
{
"card_id": "card_id_1",
"price": 123,
"code": "code_123456",
"default_gifting_msg": "",
"background_pic_url": "",
"accepter_openid": "123"
}
],
"outer_str": "web","IsChatRoom": true
},
{
"order_id": "Z2y2rY74ksZX1ceuGA",
"page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
"trans_id": "4001562001201608292531663351",
"create_time": 123,
"pay_finish_time": 123,
"total_price": 123,
"open_id": "123",
"accepter_openid": "123",
"card_list": [
{
"card_id": "card_id_1",
"price": 123,
"code": "code_123456",
"default_gifting_msg": "",
"background_pic_url": ""
}
],
"outer_str": "web"
}
]
}
返回数据说明:
注意事项:
1)返回中的total_count是在当前查询条件下的total_count,类似于分页的实现改变offset/count,直到某次请求的$offset+count \ge total_、count$时表示拉取结束。
2)begin_time和end_time的跨度不能超过31天。
3)count不能超过100。
- sort_type可以填"ASC" / "DESC",表示对*订单创建时间进行“升 / 降”排序。
# 10.礼品卡相关事件
特别说明
礼品卡作为金钱交易事务,商家可能自身有对账等需求,所以对商家服务器CallBack保证较高稳定性。
在商家未接受CallBack情况下,在24小时内,最大限度推送,最多30次。
与普通CallBack事件不同,商家在接收到CallBack之后,在Http的协议里,除了在Header中要返回200,还需要在Content中返回:
<xml\>ok</xml\>
以告诉微信平台,商家真正接收到了CallBack并处理成功
否则微信平台将继续重试推送。
# 10.1、用户购买礼品卡付款成功CallBack
协议
<xml>
<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>
<FromUserName><![CDATA[obLatjgoYejavUtHsWwrX-2GtFJE]]></FromUserName>
<CreateTime>1472631550</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[giftcard_pay_done]]></Event>
<PageId><![CDATA[OQK0R3MaFnCm74Phw5hwFJlz5sn+jy1zzM2amDidDbU=]]></PageId>
<OrderId><![CDATA[Z2y2rY74ksZX1ceuGA]]></OrderId>
</xml>
请求参数说明:
# 10.2、用户购买后赠送CallBack
协议
<xml>
<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>
<FromUserName><![CDATA[obLatjgoYejavUtHsWwrX-2GtFJE]]></FromUserName>
<CreateTime>1472631550</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[giftcard_send_to_friend]]></Event>
<PageId><![CDATA[OQK0R3MaFnCm74Phw5hwFJlz5sn+jy1zzM2amDidDbU=]]></PageId>
<OrderId><![CDATA[Z2y2rY74ksZX1ceuGA]]></OrderId>
<IsChatRoom>true</IsChatRoom>
<IsReturnBack><![CDATA[true]]></IsReturnBack>
</xml>
请求参数说明:
# 10.3、用户领取礼品卡成功CallBack
协议
<xml>
<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>
<FromUserName><![CDATA[obLatjgoYejavUtHsWwrX-2GtFJE]]></FromUserName>
<CreateTime>1472631800</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[giftcard_user_accept]]></Event>
<PageId><![CDATA[OQK0R3MaFnCm74Phw5hwFJlz5sn+jy1zzM2amDidDbU=]]></PageId>
<OrderId><![CDATA[Z2y2rY74ksZX1ceuGA]]></OrderId>
<IsChatRoom>true</IsChatRoom>
</xml>
请求参数说明:
# 10.4、赠送24小时对方未领取退回后的事件
若对方24小时未领取,则礼品卡会自动放入用户卡包,则这张卡再次发生转赠和领取时,推送的事件变为普通的转赠-领取事件。
领取
协议
<xml>
<ToUserName> <![CDATA[gh_fc0a06a20993]]> </ToUserName>
<FromUserName> <![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]> </FromUserName>
<CreateTime>1472551036</CreateTime>
<MsgType> <![CDATA[event]]> </MsgType>
<Event> <![CDATA[user_get_card]]> </Event>
<CardId> <![CDATA[pZI8Fjwsy5fVPRBeD78J4RmqVvBc]]> </CardId>
<IsGiveByFriend>0</IsGiveByFriend>
<UserCardCode> <![CDATA[226009850808]]> </UserCardCode>
<FriendUserName> <![CDATA[]]> </FriendUserName>
<OldUserCardCode> <![CDATA[]]> </OldUserCardCode>
</xml>
请求参数说明:
转赠
协议
<xml>
<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>
<FromUserName><![CDATA[obLatjjwDolFjRRd3doGIdwNqRXw]]></FromUserName>
<CreateTime>1474181868</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_gifting_card]]></Event>
<CardId><![CDATA[pbLatjhU-3pik3d4PsbVzvBxZvJc]]></CardId>
<UserCardCode><![CDATA[297466945104]]></UserCardCode>
<IsReturnBack>0</IsReturnBack>
<FriendUserName><![CDATA[obLatjlNerkb62HtSdQUx66C4NTU]]></FriendUserName>
<IsChatRoom>0</IsChatRoom>
</xml>
请求参数说明:
# 11.使用礼品卡
# 11.1 礼品卡使用方式
线下使用 线上使用
线下使用:开发者制作的礼品卡以二维码或条形码作为扣款识别码,用户到店时,出示二维码/条形码,商户POS识别后请求微信询问身份并进行余额扣减动作。
线上使用:用户购买礼品卡后,在礼品卡面上跳转至商户线上商城进行选择、购买,并在下单时默选择“礼品卡”支付渠道。商户收到扣款请求后,可向微信请求变更余额。
# 11.2 更新用户礼品卡信息接口
接口说明
当礼品卡被使用后,开发者可以通过该接口变更某个礼品卡的余额信息。
接口调用请求说明
请求参数说明
POST数据示例:
{
"code": "12312313",
"card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI",
"background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
"record_bonus": "消费30元,获得3积分",
"bonus": 3000,
"custom_field_value1": "xxxxx",
"can_give_friend": true
}
请求参数说明:
# 返回参数说明
{
"errcode": 0,
"errmsg": "ok",
"result_bonus": 100,
"result_balance": 200,
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}
# 11.3 核销用户礼品卡接口
接口说明
当礼品卡被使用完毕或者发生转存、绑定等操作后,开发者可以通过该接口核销用户的礼品卡,使礼品卡在列表中沉底并不再被使用。
接口调用请求说明
请求参数说明
POST数据示例:
{
"code": "12312313",
"card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI"
}
请求参数说明:
# 返回参数说明
{
"errcode": 0,
"errmsg": "ok",
}
# 11.4 查询礼品卡信息接口
接口说明
开发者可以通过该接口查询到code对应的信息,如余额、有效期、订单号等,主要用于防止在交易完成后丢单的情况下,用于核销/余额变动时兜底处理。
接口调用请求说明
请求参数说明
POST数据示例:
{
"code": "12312313",
"card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI"
}
请求参数说明:
# 返回参数说明
{
"errcode": 0,
"errmsg": "ok",
"card": {
"card_id": "pbLatjoAAyLz6Pt36wGQNfxNrucU",
"begin_time": 1397577600,
"end_time": 1662724261,
"balance": 1,
"code": "027691806183",
"card_number": "027691806183"
},
"openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
"can_consume": true,
"user_card_status": "NORMAL",
"order_id": "AQAAPdZIMrAvjeoKBmy2rY6RnF1D",
"background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/ibV1WeaY2IEuMzDp7RjSPib7GOIvMKPucibziaBPS0ialicialKWiaflOHMb5s1jGvCdZ9Z88kBUnfsUjq5Eo9NOGkH1Jg/0"
}
# 12.售后流程
# 12.1 财务对账
商家可以通过接收订单完成事件通知并定时查询成交订单笔数确保交易可对账。同时商家可以登录微信支付商户后台查询具体的交易以及交易详情,进行对账。
# 12.2 退款、发票流程
按照国家相关法律规定,礼品卡商户须提供退款相关流程,保障用户的合法群益。
商户可以调用退款接口完成退款流程的开发。
目前礼品卡货架支持商户在创建时传入发票和退款的链接,开发者可以开发相应页面处理用户请求。
# 12.2.1退款接口
接口说明
开发者可以通过该接口对某一笔订单操作退款,注意该接口比较隐私,请开发者提高操作该功能的权限等级。
接口调用请求说明
请求参数说明
POST数据示例:
{ "order_id": "xxx" }
请求数据说明:
# 返回参数说明
返回数据示例:
{
"errcode" : 0,
"errmsg" : "ok"
}
返回数据说明:
注意事项:退款后,对应的礼品卡将会在用户卡包消失。
# 12.2.2 支付后开发票
在创建礼品卡时商户可以填入“need_reciept”字段,即可开启支付后开票的功能,用户可以再支付成功的凭证消息上点入开具发票的页面,并填入抬头等信息,提交后微信将会通过事件通知的方式推送到商户的服务器。
# 12.2.2.1 整体流程
设置微信支付后开具电子发票须遵循以下步骤:
步骤1:商户通过接口设置支付后开票的商户号、appid以及s_appid等信息并设置开票页用户需要填写的信息
步骤2:商户设置抬头页面用户需要填写的字段信息;
步骤3用户支付完成后,在微信栏目【我】-【钱包】中点击右上角菜单打开【交易记录】,进入对应订单的【交易详情】,在页面中能看到【开具发票】按钮。填写发票的相关项目内容,【确认开票】后微信会反馈受理结果。开票请求受理成功后,微信会给用户发送已开票通知(如关注商户公众号,会通过该公众号下发已开具的通知,否则通过服务通知下发);
步骤4商户接收用户授权开票的信息,并将开票请求发送至开票平台,并由开票平台将发票下发给商户;
# 12.2.2.2设置支付后开票功能
设置支付后开票信息
接口说明
商户可以通过该接口设置某个商户号发生收款后在支付消息上出现开票授权按钮。
请求
url:
https://api.weixin.qq.com/card/invoice/setbizattr?action=set_pay_mch&access_token={access_token}
请求方法:POST
请求参数
数据格式:JSON
paymch_info包含以下字段:
返回参数
数据格式:JSON
示例
{
"paymch_info": {
"mchid": "1234",
"s_pappid": "wxabcd"
}
}
返回:
{ "errcode": 0, "errmsg": "ok" }
查询支付后开票信息接口
请求
url:
https://api.weixin.qq.com/card/invoice/setbizattr?action=get_pay_mch&access_token={access_token}
请求方法:POST
请求参数
数据格式:JSON
数据为空,传{}
返回参数
数据格式:JSON
当错误码为0是,有以下信息:
paymch_info包含以下字段:
示例
请求:
{}
返回:
{
"errcode": 0,
"errmsg": "ok",
"paymch_info": {
"mchid": "1234",
"s_pappid": "wxabcd"
}
}
# 12.2.2.3 设置开票页面信息接口
设置授权页字段信息接口
使用说明
商户可以通过该接口设置用户授权时应该填写的内容
请求说明
url:
https://api.weixin.qq.com/card/invoice/setbizattr?action=set_auth_field&access_token={access_token}
请求方法:POST
请求参数
数据格式:JSON
auth_field包含以下字段:
user_field包含以下字段:
biz_field包含以下字段:
custom_field为list,每个对象包含以下字段:
返回参数
数据格式:JSON
示例
{
"auth_field": {
"user_field": {
"show_title": 1,
"show_phone": 1,
"show_email": 1,
"custom_field": [
{
"key": "field1"
}
]
},
"biz_field": {
"show_title": 1,
"show_tax_no": 1,
"show_addr": 1,
"show_phone": 1,
"show_bank_type": 1,
"show_bank_no": 1,
"custom_field": [
{
"key": "field2"
}
]
}
}
}
返回:
{
"errcode": 0,
"errmsg": "ok"
}
备注
默认会显示个人发票的title和单位发票的title
查询授权页字段信息接口
接口说明
开发者可以通过该接口查看授权页抬头的填写项。
请求说明
url:
https://api.weixin.qq.com/card/invoice/setbizattr?action=get_auth_field&access_token={access_token}
请求方法:POST
请求参数
数据格式:JSON
数据为空,传{}
返回参数
数据格式:JSON
当错误码为0是,有以下信息:
auth_field包含以下字段:
user_field包含以下字段:
biz_field包含以下字段:
custom_field为list,每个对象包含以下字段:
请求示例
# 12.2.2.4接收开票事件
接口描述
用户授权完成后,商户会收到授权完成的事件,并请求开票平台进行开票。
关于事件推送请参考:
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_CN
请求参数
数据格式:xml
示例
<xml>
<ToUserName> <![CDATA[gh_fc0a06a20993]]> </ToUserName>
<FromUserName> <![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]> </FromUserName>
<CreateTime>1475134700</CreateTime>
<MsgType> <![CDATA[event]]> </MsgType>
<Event> <![CDATA[user_authorize_invoice]]> </Event>
<SuccOrderId> <![CDATA[1202933957956]]> </SuccOrderId>
<FailOrderId> <![CDATA[]]> </FailOrderId>
<AppId> <![CDATA[]]> </AppId>
<Source> <![CDATA[]]> </Source>
</xml>
# 12.2.2.5查询开票信息
接口说明
用户完成授权后,商户可以调用该接口查询某一个订单
请求格式
URL: https://api.weixin.qq.com/card/invoice/getauthdata?access_token={access_token}
请求方法:POST
协议:HTTPS
请求参数
数据格式:POST
返回参数
数据格式:POST
当错误码为0是,有以下信息:
user_auth_info是一个JSON结构,包含以下结构
user_auth_info是一个JSON结构,包含以下结构
请求示例
{
"s_pappid": "{s_pappid}",
"order_id": "{order_id}"
}
返回数据:
个人抬头:
{
"errcode": 0,
"errmsg": "ok",
"invoice_status": "auth success",
"auth_time": 1480342498,
"user_auth_info": {
"user_field": {
"title": "Dhxhhx ",
"phone": "5554545",
"email": "dhxhxhhx@qq.cind",
"custom_field": [
{
"key": "field1",
"value": "管理理论"
}
]
}
}
}
单位抬头:
{
"errcode": 0,
"errmsg": "ok",
"invoice_status": "auth success",
"auth_time": 1480342897,
"user_auth_info": {
"biz_field": {
"title": "王xx",
"tax_no": "6464646766",
"addr": "后过敏",
"phone": "1557548768",
"bank_type": "仔仔细细",
"bank_no": "545454646",
"custom_field": [
{
"key": "field2",
"value": "哈哈哈啊"
}
]
}
}
}
# 12.2.2.6 开具发票
商户收到上述信息后,须将信息转发至对应的开票平台进行开票,若该开票平台支持了电子发票,可开具电子发票,若不支持电子发票则可以采取寄送的方式开票。
# 13.3 在线客服
商家可以在货架的售后帮助页面定义一个自定义cell为在线客服,用户跳转时会将该用户的订单信息以及身份信息带至页面内,商户可以根据订单组织在线客服对话,帮助消费者完成售后流程。
# 14.备注
# 14.1 礼品卡卡面外链跳转协议
当用户在礼品卡跳转至商户自定义center_url、custom_url、promotion_url,跳转时会在GET参数中带入openid、encrypt_code和card_id。
encrypt_code为加密码码,需调用解码接口获取真实Code码。 假如指定的url为http://www.qq.com,
用户点击时,跳转的url则为:
http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID&openid=xxxx&outer_str=xxxxx
解码code接口请见:code解码接口
当用户在礼品卡跳转至商户自定义center_url、custom_url、promotion_url对应的小程序时,跳转时开发者可以在小程序的Page.onshow获取到对应的参数。
# 14.2礼品卡货架外链跳转协议
当用户在订单详情页跳转至商户自定义的售后流程处理cell中的url时,跳转时会在GET参数中带入order_id和openid
比如原本数据是:
https://mp.weixin.qq.com
将会变成
https://mp.weixin.qq.com/?order_id=Z2y2rY4UxUZYitvVGA&openid=oAAAAAKe1ri5AAaAiB50-Ak6Vs1w
openid为该用户在该上上商户下的身份识别id,order_id为该必订单的唯一识别id。
# 15.优惠功能
商户可以设置微信支付代金券或者立减金,控制仅微信礼品卡渠道使用,创建活动时,须设置goods_tag为mmbizgiftcard并保证本商户号其他订单不传入该goods_tag。
# 16.联系我们
若在调试过程中遇到技术问题,
请发送邮件至wx_card@tencent.com
反馈格式如下:
邮件标题:【礼品卡货架反馈】xxxxx
问题描述:xxxx
出现问题的page_id:xxxxx
出现问题用户的微信号:xxx
出现问题的时间点:xxxxx
联系方式:手机号/微信号