更新时间：2025-05-19 10:37:29文档更新记录 >配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档1 简介为简化商户的接入步骤并缩短商户的整体接入时长，支付宝开放平台提供了商户会员卡的基础功能接入指引，帮助商户和开发者极简化接入创建具备基本功能的会员卡，快速完成 创建会员卡模板 > 配置领卡表单 > 获取并投放领卡链接 > 开卡 的整体链路。完成本章基础功能接入的商户后续可以通过修改会员卡模板等接口为已创建的会员卡增加营销和权益等功能，体验 扩展功能 的更多玩法。1.1 注意事项如下接口为商家配置会员卡相关接口，配置内容可以重复使用，无需每次在用户领卡时调用：上传图片文件 alipay.offline.material.image.upload（支付宝图片资料上传接口）会员卡模板管理alipay.marketing.card.template.create（会员卡模板创建接口）alipay.marketing.card.template.modify（会员卡模板修改接口）alipay.marketing.card.template.query（会员卡模板查询接口）开卡组件alipay.marketing.card.formtemplate.set（会员卡开卡表单模板配置接口）alipay.marketing.card.activateurl.apply（获取会员卡领卡投放链接接口）2 上传图片文件会员卡中使用的 logo、背景图片等图片文件都需通过 alipay.offline.material.image.upload（上传门店照片和视频接口）获取对应的 image_id（图片资源 id） 。说明：1image_id 在同一 pid 下通用；2logo 图片规范：1m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 500px*500px 的等边矩形；请优先使用商户 logo；3background 图片规范：2m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 1020px* 643px 的等边矩形；图片不得有圆角，不得拉伸变形。 2.1 请求示例2.2 响应示例更多参数及响应示例详情参见 alipay.offline.material.image.upload（上传门店照片和视频接口）文档。3 创建卡模板开发者通过alipay.marketing.card.template.create（会员卡模板创建接口）创建会员卡模板。卡模板和卡实例是一对多的关系，即同一类卡只需要创建一次卡模板，后续发卡可直接使用，每个商家最多可创建 1000 个卡模板。页面展示信息和卡模板字段信息的对应关系3.1 请求示例3.1.1 bizcontent 示例传参注意事项1logo 图片规范：1m以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 500px*500px 的等边矩形；请优先使用商户 logo；2background 图片规范：2m 以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于 1020px* 643px 的等边矩形；图片不得有圆角，不得拉伸变形；3链接内容规范：链接内容不得违反法律法规或公序良俗；不得以任何形式外链到其他网站或者推广其他 app 下载；不得展示任何虚假信息、错误信息；4其中 template_style_info.feature_descriptions 支持配置多项，如果配置多项，页面上展示为翻滚效果；5卡权益信息 open_card_conf.card_rights ，权益 logo 通过 card_rights.logo_id 设置，权益标题通过 card_rights.title 设置。更多参数详情参见alipay.marketing.card.template.create（会员卡模板创建接口）文档。3.2 扩展功能创建会员卡模板时商家/isv 还可跟随 扩展功能 指引配置 展示样式、会员等级、积分、适用门店 等信息。详情参见：●展示样式，用于配置会员权益、卡行动点等 列表 或 宫格 形式展示。●会员等级，用于配置会员等级体系。●会员积分，用于展示用户在商家系统中会员积分详情，商家可实时更新此项内容至支付宝，方便用户通过卡包页随时查看积分信息。●余额信息，若商户会员卡为充值会员卡，可通过此项内容实时展示、更新用户卡余额信息。●权益玩法，商户会员卡底部支持商家自定义栏位，商家通过以下接口的参数拓展更多权益玩法，也支持商户创建外部权益。●投放会员卡至门店，商户可通过此项配置在会员卡中增加 适用门店 入口，用户可在会员卡卡面查看支持使用的门店，还可一键导航到店消费。商家门店凯发k8官方网娱乐官方主页也可展示领取会员卡入口，方便用户从不同渠道领取会员卡。●小程序服务直达，商户会员卡还为商户在会员卡上开辟了卡行动点，商户可以在卡行动点上设置小程序或 http(s) 跳转链接，引导用户在会员卡复访商家应用页面。●商户动态发码，商家/isv 如需在用户在支付宝卡包中打开会员卡时，展示自行生成的动态二维码/条形码，可根据本文指引集成动态发码功能。3.3 附录3.3.1 服务商代替商户创建卡模板接口调用流程图4 配置开卡表单在完成会员卡模板创建后，商户可以得到卡模板的唯一标识即 template_id（支付宝卡模板id）。商户根据 template_id，通过alipay.marketing.card.formtemplate.set（会员卡开卡表单模板配置接口）配置如下的领卡页面表单，限制用户领取会员卡时需填写的个人信息，如：姓名、性别、手机号等。说明：表单内容默认不自动回填，如需根据用户在支付宝的实名认证信息自动回填，请 申请用户信息。应用案例4.1 请求示例说明：●template_id：会员卡模板id，创建会员卡模板将会返回该 id。●是否学生认证和会员等级字段，如果在当前用户无法获取到数据时，表单页面不展示该字段。更多参数详情参见alipay.marketing.card.formtemplate.set（会员卡开卡表单模板配置接口）文档。4.2 附录isv 代替商户调用alipay.marketing.card.formtemplate.set（会员卡开卡表单模板配置接口） 接口调用流程如下图所示：5 获取投放链接商家通过alipay.marketing.card.activateurl.apply（获取会员卡领卡投放链接接口）得到 apply_card_url （领卡链接），商家需要把领卡链接 decode 后投放于支付宝生活号、商家页面或者生成二维码置于门店内。用户跳转至领卡页面填写信息后，点击 同意并领卡 后，完成领卡行为。注意：若商家未使用 支付宝卡包 插件能力，直接使用此文档中获取的开卡页链接进行会员卡推广，或会造成参与的激励政策无法被计入数据。可在获取链接后拼接 &sourceappid=xxxx（appid 为开卡小程序的 appid）进行 appid 回传。详情可查看 激励政策规范。5.1 请求示例说明：●template_id：必填，会员卡模板id，创建会员卡模板将会返回该 id。●callback：必填，会员卡领卡表单页面成功回调地址，此地址需要与应用配置的 授权回调地址 相同，callback 为单纯的服务端接收回调。 用户 点击领卡 后，支付宝将会回调商户在获取领卡投放链接时配置的 callback 地址，并且回传 auth_code、request_id 参数。商户可通过 request_id 参数从支付宝查询用户此次领取会员卡时提交的信息，并为用户开取会员卡。●out_string：可选，最大长度为 256。由商户自定义设置（不能包含 =、=），确认领卡成功后将作为 url 参数拼接在 callback 回调地址之后原样带回。 注意：禁止将该字段作为开卡流程的必要字段，否则会导致会员推广场景下的入会失败。更多参数详情参见 alipay.marketing.card.activateurl.apply（获取会员卡领卡投放链接接口）文档。5.2 附录isv 代替商户调用alipay.marketing.card.activateurl.apply（获取会员卡领卡投放链接接口） 接口调用流程如下图所示：6 小程序内唤起会员开卡授权页面6.1 订购插件商家需订购 用于小程序场景唤起开卡页。说明：支付宝客户端可前往 服务市场 进行搜索订购。6.2 引入插件6.2.1 第一步：声明插件开发者需在小程序 app.json 文件中声明卡包插件。6.2.2 第二步：使用插件说明：领卡表单内容默认不自动回填，如需根据用户在支付宝的实名认证信息自动回填，请 申请用户信息。plugin.opencard(params) 接口说明本插件接口用于唤起开卡页。入参说明参数名称参数类型是否必填描述urlstring是上文 获取投放链接 接口返回的开卡链接。callbackany是开卡完成回调 function。出参说明参数名称参数类型描述successboolean开卡结果。resultcodestring结果码。10000：'用户领卡成功'；10001：'用户主动退出'；10003：'用户取消支付'；10004：'用户支付失败'；10002：'网络链接错误'。resultmsgstring结果信息描述。extinfoobject扩展信息。6.2.3 展示案例开卡对用户具体展示的姓名、性别等信息字段依商家 配置开卡表单 设置而定。7 获取用户填写的表单信息商户通过查询用户提交的会员卡表单信息接口alipay.marketing.card.activateform.query（查询用户提交的会员卡表单信息接口） 获取用户在开卡表单中填写的信息（填写的信息字段为商户在第二步中配置开卡表单中设置的字段）。7.1 第一步：获取用户授权令牌开发者需调用alipay.system.oauth.token（换取授权访问令牌接口）接口，传入 callback 地址返回的 auth_code 值，获取 access_token 及 user_id（open_id） 用于查询用户提交信息及后续开卡操作。7.1.1 示例代码重要参数说明：●grant_type：授权类型，使用 auth_code 换取 accesstoken 场景固定为 authorization_code。●code：授权码，用户提交开卡申请后，支付宝返回至开卡链接中 callback 地址。 响应示例重要响应说明●user_id（open_id）：开卡用户支付宝 id，用于后续开卡。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。●access_token：用户授权令牌，用于后续查询用户提交信息及开卡。 7.2 第二步：查询用户提交表单信息7.2.1 请求示例说明：●template_id：为会员卡模板id，创建会员卡模板将会返回该 id。●request_id：用户开卡请求 id，通过 callback 地址返回。●access_token：用户授权令牌，通过用户授权码 auth_code 换取，详见上一步 获取用户授权令牌。 7.3 附录isv 代替商户调用alipay.marketing.card.activateform.query（查询用户提交的会员卡表单信息接口） 接口调用流程如下图所示：8 为用户开卡商户需要在用户领卡后，根据支付宝端的模板id（template_id）通过会员卡开卡接口alipay.marketing.card.open（会员卡开卡接口）完成商户会员卡的电子化，在用户支付宝app的卡包内展现会员卡，同时将卡信息保存至支付宝系统。说明：为保证用户体验，请在收到支付宝开卡回调 3s 内调用本接口完成会员卡发放操作，如未在 3s 内完成开卡页面会提示 等待处理。8.1 请求示例说明：●out_serial_no：唯一标识号，由商家自定义，需保证每次请求该值唯一。●card_template_id：模板 id，通过会员卡模板创建接口获取；●user_uni_id（open_id）：支付宝开卡用户 id，详见上一步 获取用户授权令牌。开卡成功后，登录到 user_id（open_id） 对应账号的支付宝钱包内卡券类目下即可查看发送成功的会员卡；●access_token：用户授权令牌，通过用户授权码 auth_code 换取，详见上一步 获取用户授权令牌。●card_ext_info：外部会员卡信息。○external_card_no：商户外部会员卡卡号。商家自定义且需保证在商家系统中唯一，若使用相同的 external_card_no 开卡，支付宝会幂等返回结果。○open_date：开卡时间。○valid_date：会员卡有效截止日期。○level：会员卡等级，需传入创建卡模板时 card_level_conf#level 对应的 value 值，详情参见 会员等级。○point：会员卡积分。○balance：资金卡余额，单位：元，精确到小数点后两位。8.2 附录isv 代替商户调用alipay.marketing.card.open（会员卡开卡接口） 接口调用流程如下图所示：9 辅助功能除了基本发卡链路外，开放平台还为开发者和商户提供了后续的配套接口，用于会员卡模板的查询和修改，以及会员卡的查询、更新和删除。9.1 会员卡查询接口商家/isv 可通过alipay.marketing.card.query（会员卡查询接口）接口根据卡号或者持卡人信息查询会员卡信息。9.1.1 请求示例说明：●target_card_no：会员卡业务号，在调用开卡接口成功后支付宝返回的 biz_card_no 参数的值。●user_uni_id（open_id）：支付宝用户 id。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。更多入参及响应示例详情参见alipay.marketing.card.query（会员卡查询接口）接口文档。9.2 会员卡更新接口商户/isv 可调用alipay.marketing.card.update（会员卡更新接口）接口，更新指定会员卡信息。注意：●更新会员卡后，只有该张会员卡会进行更新，其他会员卡不会更新。可借此实现不同会员等级会员卡展示不同样式，详情参见 按会员等级展示不同卡片内容。●open_date（开卡时间）和 valid_date（结束时间）不支持修改，设置后无效。●不支持设置 notify_messages（卡信息变更通知消息），设置后无效，不会发送通知。●其他修改项因为线上缓存的缘故，模板更新可能存在 1-5 分钟延时。 9.2.1 请求示例说明：target_card_no 为会员卡业务号，在调用开卡接口成功后支付宝返回的 biz_card_no 参数的值。 更多入参及响应示例详情参见alipay.marketing.card.update（会员卡更新接口）接口文档。9.3 会员卡删除接口商户/isv 可调用 alipay.marketing.card.delete（会员卡删卡接口）接口删除指定会员卡。9.3.1 接口调用流程9.3.2 请求示例说明：●out_serial_no 为请求唯一标识，每次请求需保证唯一。●target_card_no 为会员卡业务号，调用开卡接口成功后支付宝返回的 biz_card_no 参数的值。 更多入参及响应示例详情参见 alipay.marketing.card.delete（会员卡删卡接口）接口文档。9.4 会员卡模板修改接口商户/isv 可调用alipay.marketing.card.template.modify（会员卡模板修改接口）接口，修改该模板样式等信息。注意：●修改会员卡模板后，该模板下所有会员卡都会更新（ 包括已发放会员卡）。●修改会员卡模板，field_rule_list（字段规则列表）配置项不支持修改，设置后无效。●会员卡设置 shop_ids 后，shop_ids 只支持新增或修改门店，但是不支持删除 shop_ids 参数。详情参见 投放会员卡至门店。●其他修改项因为线上缓存的缘故，模板更新可能存在 1-5 分钟延时。 9.4.1 接口调用流程9.4.2 请求示例说明：●request_id 为请求唯一标识，每次请求请保证唯一性。●logo_id 和 background_id 通过支付宝alipay.offline.material.image.upload（上传门店照片和视频接口）获取。 更多入参及响应示例详情参见alipay.marketing.card.template.modify（会员卡模板修改接口）接口文档。9.5 会员卡模板查询接口商户/isv 可调用 alipay.marketing.card.template.query（会员卡模板查询接口）查询指定模板详情。9.5.1 接口调用流程9.5.2 请求示例说明：template_id ：模板 id，通过会员卡模板创建接口获取。 更多入参及响应示例详情参见 alipay.marketing.card.template.query（会员卡模板查询接口）接口。10 扩展功能在商家/服务商 完成接入会员卡的基本链路后，扩展功能可满足商户会员卡的个性化营销需求和玩法，通过额外的接口配置等步骤，实现生活号、小程序和蜻蜓设备的联动。如：●展示样式，用于配置会员权益、卡行动点等 列表 或 宫格 形式展示。●会员等级，用于配置会员等级体系。●会员积分，用于展示用户在商家系统中会员积分详情，商家可实时更新此项内容至支付宝，方便用户通过卡包页随时查看积分信息。●余额信息，若商户会员卡为充值会员卡，可通过此项内容实时展示、更新用户卡余额信息。●权益玩法，商户会员卡底部支持商家自定义栏位，商家通过以下接口的参数拓展更多权益玩法。●投放会员卡至门店，商户可通过此项配置在会员卡中增加 适用门店 入口，用户可在会员卡卡面查看支持使用的门店，还可一键导航到店消费。商家门店凯发k8官方网娱乐官方主页也可展示领取会员卡入口，方便用户从不同渠道领取会员卡。●小程序服务直达，商户会员卡还为商户在会员卡上开辟了卡行动点，商户可以在卡行动点上设置小程序跳转链接，引导用户在会员卡复访小程序，为小程序引流。更多详情参见 扩展功能。
