基础功能 -凯发app官方网站

更新时间：2022-07-06 17:24:08

我的文档

设置

为简化商家/服务商的接入步骤并缩短整体接入时长，本文为商户户会员卡的

基础功能

接入指南，旨在帮助商家或服务商极简化接入创建具备基本功能的会员卡，快速完成

会员卡模板创建

配置开卡组件

向用户开卡

的整体链路。

说明：

完成本章基础功能接入的商家/服务商可查看：

●

辅助功能：

接入会员卡模板、会员卡管理功能。

●

扩展功能：

为会员卡增加营销和权益等功能。

配置会员卡模板

说明：

如下接口为商家配置会员卡相关接口，配置内容可以重复使用，无需每次在用户领卡时调用。

1. 创建卡模板

会员卡模板创建是接入商户会员卡产品的第一个环节，也是最重要的环节，会员卡模板的配置决定了用户领卡后在支付宝卡包看到的会员卡内容和样式。商户通过

（会员卡模板创建接口）可快速创建会员卡模板。

注意事项

卡模板和卡实例是一对多的关系，即同一类卡只需要创建一次卡模板，后续发卡可直接使用，每个商家最多可创建 1000 个卡模板

请求示例

官方推荐创建样式如下，可直接使用 demo 的代码创建（如果需要自定义样式可通过模板创建接口，自行创建）。

{

"request_id":"20160805100000023100679", //请求id，商家自定义，创建不同的模板，需要保证request_id不同

"card_type":"out_member_card", //固定为out_member_card

"biz_no_prefix":"prex", // 支付宝业务卡号生成规则：biz_no_prefix(商户指定)卡号前缀 biz_no_suffix位的(实时生成）卡号

"biz_no_suffix_len":"20",// 建议设置成20，生成卡号biz_card_no 长度为：前缀(biz_no_prefix) 20

"write_off_type":"qrcode", // 静态二维码，码值为最终发卡指定的external_card_no

"spi_app_id":"2014072300007148",

"template_style_info":{

"card_show_name":"商家会员卡",

"logo_id":"1t8pp00at7eo9noajkmr3aaama****", //由alipay.offline.material.image.upload上传

"background_id":"okwbuiwcq761mdrzp4pvuwaaacm****",

"bg_color":"rgb(55,112,179)"

"column_info_list":[

{

"code":"column_info_1",

"more_info":{

"url":"https://www.alipay.com"

"title":"栏位信息1",

"operate_type":"openweb"

{

"code":"column_info_2",

"more_info":{

"url":"https://www.alipay.com"

"title":"栏位信息2",

"operate_type":"openweb"

{

"code":"column_info_3",

"more_info":{

"url":"https://www.alipay.com"

"title":"栏位信息3",

关键参数说明：

●

biz_no_prefix、biz_no_suffix_len：这两个参数决定了生成的支付宝业务卡号 biz_card_no 的长度

●

spi_app_id：

向用户开卡

环节中，商家需要实现

（会员卡开通，获取会员卡信息）

spi 接口，spi_app_id 为实现 spi 接口的 appid。若是第三方代理模式，可以设置成服务商的

appid

或者是商家自己的

appid

；若不是第三方代理模式，只能设置商家自己的

appid

。

传参注意事项

●

logo 图片规范：

1m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 500px*500px 的等边矩形；请优先使用商户 logo。

●

background 图片规范：

2m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 1020px* 643px 的等边矩形；图片不得有圆角，不得拉伸变形。

●

链接内容规范：

链接内容不得违反法律法规或公序良俗；不得以任何形式外链到其它网站或者推广其它 app 下载；不得展示任何虚假信息、错误信息。

展示效果

2. 上传卡模板图片文件

会员卡模板中使用的 logo、背景图片等图片文件均需通过

（

上传门店照片和视频接口

）获取对应的

image_id

（图片资源 id）。

注意事项

image_id 在同一 pid 下通用。

logo 图片规范：1m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 500px*500px 的等边矩形；请优先使用商户 logo。

background 图片规范：2m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 1020px* 643px 的等边矩形；图片不得有圆角，不得拉伸变形。

请求示例

响应示例

3. 配置卡模板开卡表单

不同的商户向用户发卡时，需要用户提供的会员信息不同，基于此商户会员卡产品提供了会员卡开卡组件表单配置功能，该表单的配置决定了用户在开卡环节时需要授权会员信息。

商户/服务商需调用

（会员卡开卡表单模板配置接口），传入

template_id

（会员卡模板 id）为对应的会员卡模板配置开卡页面表单，规定用户领取会员卡时需填写的个人信息，如：姓名、性别、手机号等。

说明：

表单内容默认不自动回填，如需根据用户在支付宝的实名认证信息自动回填，请

。

请求示例

bizcontent 示例

前端集成开卡组件

支付宝提供了支持

全屏开卡

和

半屏开卡

两种样式的开卡组件，商家/服务商可根据实际需求调整开卡组件展示样式。

●

全屏开卡样式

●

半屏开卡样式

1. 订购开卡插件

如果商户需要在小程序内向用户发卡，商户需订购

。

说明：

两种开卡组件样式，如需在商家小程序内打开，均需要先为商家小程序订阅

支付宝开卡插件

。

2. 前端引入插件

第一步：声明插件

开发者需在小程序 app.json 文件中声明卡包插件。

第二步：使用插件

.axml 示例代码

.js 示例代码

plugin.opencard(params) 接口说明

本插件接口用于唤起开卡组件。

入参说明

参数名称	参数类型	是否必填	描述
cardparams	string	是	开卡入参
l cardparams.templateid	string	是	开卡的卡模板 id
l cardparams.templateappid	string	是	卡模板 id 所关联的 appid。
l cardparams.outstring	string	否	商户自定义透传信息。
l cardparams.pagetype	string	否	开卡组件样式。默认 half（半屏开卡）。枚举支持： ●full：全屏开卡。 ●half：半屏开卡。
l cardparams.joinbenefittype	string	否	扩展功能入会有礼专用。为入会有礼对应的权益类型，固定传入：voucher_mrch。
l cardparams.joinbenefitid	string	否	扩展功能入会有礼专用。为入会有礼对应的活动 id（商家中心配置所得）。
callback	any	是	开卡完成回调 function。

出参说明

参数名称	参数类型	描述
success	boolean	开卡结果。
resultcode	string	结果码。 ●10000：用户领卡成功。 ●10001：用户主动退出。 ●10002：网络链接错误。
resultmsg	string	结果信息描述。
extinfo	object	扩展信息。

服务端集成开卡接口

1.实现获取会员卡 spi 接口

商户/服务商需根据

实现

（会员卡开通，获取会员卡信息接口）

。当用户通过开卡组件，点击

同意开卡

后，支付宝会调用此接口同步

商家/

服务商

用户提交的开卡信息（例如：姓名、性别等），商家/服务商可根据用户提交信息完成

开卡并返回会员卡信息。

注意：

为保证用户体验，商家在收到支付宝 spi 消息后，需在 3s 内返回会员卡信息。

支付宝请求业务字段

支付宝将在请求 body 中传递如下字段给商家。

参数	类型	是否必填	最大长度	示例值	描述
user_id	string	可选	16	2088902351536970	user_id：蚂蚁统一会员 id。
template_id	string	必选	32	20200312000000000414103000300846	template_id：会员卡模板 id，即（会员卡模板创建接口）返回的 template_id。
out_serial_no	string	必选	32	1621923366000	out_serial_no：外部流水号，标识一次用户的开卡动作，用户每次打开开卡组件，都会生成一个全局唯一的 id。
biz_card_no	string	必选	32	000001	biz_card_no：支付宝预先生成的会员卡业务卡号，开卡结果需要回填。商家需要保存该业务卡号，后续可通过该卡号，更新、查询会员卡。
user_info	string	必选	10240	[{"open_form_field_gender":"男"},{"open_form_field_mobile":"13888888888"},{"open_form_field_name":"李四"}]	user_info：用户开卡时提交的表单信息，json 数组格式。通用表单字段名称如下示例： open_form_field_mobile – 手机号 open_form_field_gender – 性别 open_form_field_name – 姓名 open_form_field_birthday – 生日 open_form_field_idcard – 身份证 open_form_field_email – 邮箱 open_form_field_address – 地址详细字段名称列表见会员卡开卡表单模板配置接口：alipay.marketing.card.formtemplate.set 注意：证件类型字段(open_form_field_cert_type)返回结果取值如下: ●0：身份证。 ●1：护照。 ●2：港澳居民通行证。 ●3：台湾居民通行证。
out_string	string	可选	1024	test	out_string：该值为商家拉起开卡组件的传递的out_string 值。通常可用于区分不同业务场景。

约定返回业务字段

商家/服务商需按如下规范返回业务信息给支付宝。主要包含两个模型：

●

card_info：商家定义的会员卡信息。

●

open_card_ext_info：用于传递开卡过程中附加的扩展信息。

card_info 模型详解

参数	类型	是否必填	最大长度	示例值	描述
biz_card_no	string	可选	32	000001	biz_card_no：支付宝预先生成的会员卡业务卡号，回填
external_card_no	string	可选	64	ext0001	external_card_no：商户外部会员卡卡号，卡号需要满足以下要求： 1商家针对每一个user_id，卡号需要保证唯一 2支付宝幂等规则为：商家 external_card_no
open_date	string	必填	32	2000-01-01 21:20:46	会员卡开卡时间，格式为yyyy-mm-dd hh:mm:ss
valid_date	string	必填	32	2100-02-20 21:20:46	会员卡有效期，格式为yyyy-mm-dd hh:mm:ss。若期望会员卡长期有效，可适当把有效期设置长远一些
level	string	可选	64	vip1	level：会员卡等级，由商户自定义，并可以在卡模板创建时，定义等级信息
point	string	可选	64	88	point：会员卡积分，小数点后最多两位。
balance	string	可选	64	124.89	balance：余额，单位：元，小数点后最多两位。
template_id	string	可选	32	20170308000000000058101000300045	template_id：会员卡模板 id，即（会员卡模板创建接口）返回的 template_id。

open_card_ext_info 模型详解

参数	类型	是否必填	最大长度	示例值	描述
is_new_member	boolean	可选	10	true	is_new_member：是否新会员。商家可通过该字段，告诉支付宝是否是商家 crm 中的新会员。
activity_id	string	可选	128	12345	activity_id： iot 场景专用，普通场景无需关注。

实现示例

注意：

用户领卡成功后，可能会在支付宝卡包中主动删除会员卡。删除后，用户可能会重新进入开卡组件进行开卡，因此 spi 实现需要支持重复回调，大体逻辑如下：

●

商家/服务商 crm 系统中没有该用户的会员卡信息，则需重新为用户开卡并返回卡信息。

●

商家/服务商 crm 系统中已有该用户的会员卡，则可以直接返回已有的卡信息。

监听开卡结果消息

若商家/服务商关心支付宝侧开卡结果（例如：关注线上开卡的成功率、需要排查开卡失败原因），可以订阅

（会员卡开卡结果通知接口），支付宝完成开卡后将通过此接口向商家/服务商的

应用网关地址

发送结果消息。

第一步：订阅消息

商家/服务商需根据

订阅消息

指引，为接入商户会员卡的

商家应用

或

第三方应用

（会员卡开卡结果通知

接口

）。

注意：

仅完成订阅后才会收到支付宝发送的对应异步通知消息。

第二步：接收消息

监听消息示例代码

消息示例

消息参数说明

参数	类型	是否必填	最大长度	示例值	描述
user_id	string	必选	16	2088902351536970	蚂蚁统一会员id。
template_id	string	必选	32	20200312000000000414103000300846	会员卡模板 id（卡模板创建接口返回的模板id）
biz_card_no	string	必选	32	000001	支付宝业务卡号。
external_card_no	string	必选	64	ext0001	商户外部会员卡卡号。
success	string	必选	10	true	开卡结果（true/false）。
error_code	string	特殊可选	32	illegal_argument	错误码，列表如下。
error_msg	string	特殊可选	128	参数非法	错误描述。

错误码列表

error_code 类型	错误描述
isv.invalid-arguments	参数有误：需要结合 error_msg 定位具体原因
isp.system-error	系统繁忙
isv.template-not-exist	模板不存在
isv.open-card-concurrently	同一外部卡号并发开卡错误
isv.card-has-opened	开卡失败，用户已有此外部卡号的卡实例

第二步：验签

商家/服务商可使用

支付宝 sdk

可根据

数据验签

指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。

第三步：反馈消息接收结果

收到异步通知完成验签后，商家/服务商需返回

success

表示消息获取成功，支付宝就会停止发送异步通知。如果返回

fail

或其它值，表示消息获取失败，支付宝会根据

投递重试策略

重新发送消息到应用网关地址。

说明：

完成异步通知验签时，如果验签成功

success

，验签失败返回

fail

，重新接收异步进行处理。

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

相关问题