更新时间：2024-11-12 17:53:27文档更新记录 >配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档为简化商家/服务商的接入步骤并缩短整体接入时长，本文为商家会员卡（3.1极速版）的 基础功能 接入指南，旨在帮助商家或服务商极简化接入创建具备基本功能的会员卡，快速完成 会员卡模板创建 > 配置开卡组件 > 向用户开卡 的整体链路。1 接口时序图2 配置会员卡模板以下接口为商家配置会员卡相关接口，配置内容可以重复使用，无需每次在用户领卡时调用。2.1 创建卡模板会员卡模板创建是接入商家会员卡产品的第一个环节，也是最重要的环节， 会员卡模板的配置决定了用户领卡后在支付宝卡包看到的会员卡内容和样式，通过调用 alipay.marketing.card.template.create（会员卡模板创建接口）可快速创建会员卡模板。2.1.1 注意事项卡模板和卡实例是一对多的关系，即同一类卡只需要创建一次卡模板，后续发卡可直接使用同一模板，每个商家最多可创建 1000 个卡模板。2.1.2 请求示例官方推荐创建样式如下，可直接使用 demo 的代码创建（如果需要自定义样式可通过模板创建接口，自行创建）。关键参数说明●spi_app_id：向用户开卡 环节中，商家需要实现 spi.alipay.user.opencard.get（会员卡开通，获取会员卡信息接口）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.2 创建标准会员卡模板通过卡面基础装修，创建标准的商家会员卡模板。2.3 上传卡模板图片文件会员卡模板中使用的 logo、背景图片等图片文件均需通过 获取对应的 image_id（图片资源 id）。2.3.1 注意事项1image_id 在同一 pid 下通用。2logo 图片规范：1m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 500px*500px 的等边矩形；请优先使用商家 logo。3background 图片规范：2m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 1020px* 643px 的等边矩形；图片不得有圆角，不得拉伸变形。 2.3.2 请求示例2.3.3 响应示例2.4 前端集成开卡组件支付宝提供了 半屏开卡 样式的开卡组件。开卡组件说明：●开卡组件支持在多个小程序中唤起，但需使创建小程序和创建会员卡的账号保持一致。●开卡组件里涉及的入会权益、会员权益、商家群、会员订阅消息等营销能力，需在 或 ，运营中心 > 营销工具 >会员卡管理 进行相关配置。完成配置后，由商家小程序唤起开卡组件时，除入会权益外的配置内容将自动展示。如需展示入会权益，需开发人员传入参数 入会活动 id，具体见下方插件入参说明。 2.5 订购开卡插件商家需订购 并完成前端集成。2.6 前端引入插件2.6.1 第一步：声明插件开发者需在小程序 app.json 文件中声明卡包插件。2.6.2 第二步：使用插件.axml 示例代码.js 示例代码plugin.opencard(params) 接口说明本插件接口用于唤起开卡组件。入参说明参数类型是否必填描述cardparamsstring是开卡入参。l cardparams.templateidstring是开卡的卡模板 id。l cardparams.templateappidstring是卡模板 id 所关联的 appid。l cardparams.outstringstring否商家自定义透传信息。注意：禁止将该字段作为开卡流程的必要字段，否则会导致会员推广场景下的入会失败。l cardparams.pagetypestring否开卡组件样式。默认 half（半屏开卡）。l cardparams.joinbenefittypestring否扩展功能 入会有礼 专用。为入会有礼对应的权益类型，固定传入：voucher_mrch。l cardparams.joinbenefitidstring否扩展功能 入会有礼 专用。为入会有礼对应的活动 id（商家平台配置所得）。callbackany是开卡完成回调 function。出参说明参数类型描述successboolean开卡结果。resultcodestring结果码。●10000：用户领卡成功。●10001：用户主动退出。●10002：网络链接错误。resultmsgstring结果信息描述。extinfoobject扩展信息。3 服务端集成开卡接口3.1 实现获取会员卡 spi 接口商家/服务商需根据 实现 spi.alipay.user.opencard.get（会员卡开通，获取会员卡信息接口）。当用户通过开卡组件，点击 同意开卡 后，支付宝会调用此接口同步商家/服务商用户提交的开卡信息（例如：姓名、性别等），商家/服务商可根据用户提交信息完成开卡并返回会员卡信息。注意：为保证用户体验，商家在收到支付宝 spi 消息后，需在 3s 内返回会员卡信息。当 spi.alipay.user.opencard.get（会员卡开通，获取会员卡信息接口） 状态为已上线时，才可以进行 spi 接口调试。3.1.1 支付宝请求业务字段支付宝将在请求 body 中传递如下字段给商家。参数类型是否必填最大长度示例值描述user_id（open_id）string否128-蚂蚁统一会员 id。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。template_idstring是3220200312000000000414103000300846会员卡模板 id，即 alipay.marketing.card.template.create（会员卡模板创建接口）返回的 template_id。out_serial_nostring是321621923366000out_serial_no：外部流水号，标识一次用户的开卡动作，用户每次打开开卡组件，都会生成一个全局唯一的 id。biz_card_nostring是32000001支付宝预先生成的 会员卡业务卡号，开卡结果需要回填。商家需要保存该业务卡号，后续可通过该卡号，更新、查询会员卡。user_infostring是10240[{"open_form_field_gender":"男"},{"open_form_field_mobile":"13888888888"},{"open_form_field_name":"李四"}]用户开卡时提交的表单信息，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_stringstring否1024test该值为商家拉起开卡组件的传递的 out_string 值。通常可用于区分不同业务场景。注意：禁止将该字段作为开卡流程的必要字段，否则会导致会员推广场景下的入会失败。3.1.2 约定返回业务字段商家/服务商需按如下规范返回业务信息给支付宝。主要包含两个模型：●card_info：商家定义的会员卡信息。●open_card_ext_info：用于传递开卡过程中附加的扩展信息。card_info 模型详解参数类型是否必填最大长度示例值描述biz_card_nostring是32000001支付宝预先生成的 会员卡业务卡号，回填。external_card_nostring是64ext0001商户外部会员卡卡号，卡号需要满足以下要求：1商家针对每一个 user_id，卡号需要保证唯一。2支付宝幂等规则为：商家 external_card_no。open_datestring是322000-01-01 21:20:46会员卡开卡时间，格式为 yyyy-mm-dd hh:mm:ss。valid_datestring是322100-02-20 21:20:46会员卡有效期，格式为 yyyy-mm-dd hh:mm:ss。若期望会员卡长期有效，可适当把有效期设置长远一些。levelstring否64vip1会员卡等级。由商户自定义，并可以在卡模板创建时，定义等级信息。pointstring否6488会员卡积分，小数点后最多两位。balancestring否64124.89余额，单位：元，小数点后最多两位。template_idstring是3220170308000000000058101000300045会员卡模板 id，即 （会员卡模板创建接口）返回的 template_id。open_card_ext_info 模型详解参数类型是否必填最大长度示例值描述is_new_memberboolean否10true是否新会员。商家可通过该字段，告诉支付宝是否是商家客户管理系统（crm）中的新会员。activity_idstring否12812345iot 场景专用，普通场景无需关注。3.1.3 实现示例注意：用户领卡成功后，可能会在支付宝卡包中主动删除会员卡。删除后，用户可能会重新进入开卡组件进行开卡，因此 spi 实现需要支持重复回调，大体逻辑如下：●商家/服务商 crm 系统中没有该用户的会员卡信息，则需重新为用户开卡并返回卡信息。●商家/服务商 crm 系统中已有该用户的会员卡，则可以直接返回已有的卡信息。3.2 监听开卡结果消息若商家/服务商关心支付宝侧开卡结果（例如：关注线上开卡的成功率、需要排查开卡失败原因），可以订阅 ，支付宝完成开卡后将通过此接口向商家/服务商的 应用网关地址 发送结果消息。3.2.1 第一步：订阅消息商家/服务商需根据 订阅消息 指引，为接入商家会员卡的 商家应用 或 第三方应用 订阅 。注意：仅完成订阅后才会收到支付宝发送的对应异步通知消息。3.2.2 第二步：接收消息监听消息示例代码消息示例消息参数说明参数类型是否必填最大长度示例值描述user_id（open_id）string必选128-支付宝用户 id。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。template_idstring必选3220200312000000000414103000300846会员卡模板 id（卡模板创建接口返回的模板 id）biz_card_nostring必选32000001支付宝业务卡号。external_card_nostring必选64ext0001商家外部会员卡卡号。successstring必选10true开卡结果（true/false）。error_codestring特殊可选32illegal_argument错误码，列表如下。error_msgstring特殊可选128参数非法错误描述。错误码列表error_code 类型错误描述isv.invalid-arguments参数有误，需要结合 error_msg 定位具体原因。isp.system-error系统繁忙。isv.template-not-exist模板不存在。isv.open-card-concurrently同一外部卡号并发开卡错误。isv.card-has-opened开卡失败，用户已有此外部卡号的卡实例。3.2.3 第二步：验签商家/服务商可使用支付宝 sdk 可根据 数据验签 指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。3.2.4 第三步：反馈消息接收结果收到异步通知完成验签后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其它值，表示消息获取失败，支付宝会根据 投递重试策略 重新发送消息到应用网关地址。说明：完成异步通知验签时，如果验签成功返回 success，验签失败返回 fail，重新接收异步进行处理。响应值描述是否重试fail消息获取失败重试success消息获取成功不重试4 会员卡更新接口商家/服务商可调用 alipay.marketing.card.update（会员卡更新接口），更新指定会员卡信息，进而进行“余额、积分、等级”等资产的变动，进而触发相关会员消息，增加小程序流量。注意：●更新会员卡后，只有该张会员卡会进行更新，其它会员卡不会更新。可借此实现不同会员等级会员卡展示不同样式，详情可查看 按会员等级展示不同卡片内容。●open_date（开卡时间）和 valid_date（结束时间）不支持修改，设置后无效。●不支持设置 notify_messages（卡信息变更通知消息），设置后无效，不会发送通知。●其它修改项因为线上缓存的缘故，模板更新可能存在 1 ～ 5 分钟延时。 4.1 请求示例说明：target_card_no 为会员卡业务号，在调用开卡接口成功后支付宝返回的 biz_card_no 参数的值。 更多入参及响应示例详情可查看 alipay.marketing.card.update（会员卡更新接口）文档。5 验收工具可通过下方的验收工具进行 商家会员卡 产品接入的完整性和准确性验证。开始验收前，你可以查看验收规则，明确产品的接入要求和规范。
